@dxos/echo 0.8.4-main.66e292d → 0.8.4-main.69d29f4

package/src/internal/annotations/annotations.ts

@@ -7,7 +7,7 @@ import * as Option from 'effect/Option';
 import * as Schema from 'effect/Schema';
 import * as SchemaAST from 'effect/SchemaAST';
 
-import { Reference } from '@dxos/echo-protocol';
+import { raise } from '@dxos/debug';
 import { type JsonPath, getField } from '@dxos/effect';
 import { assertArgument, invariant } from '@dxos/invariant';
 import { DXN } from '@dxos/keys';
@@ -29,6 +29,10 @@ export const FIELD_PATH_ANNOTATION = 'path';
 // TODO(burdon): Field, vs. path vs. property.
 export const FieldPath = (path: string) => PropertyMeta(FIELD_PATH_ANNOTATION, path);
 
+//
+// Type
+//
+
 /**
  * ECHO identifier (for a stored schema).
  * Must be a `dxn:echo:` URI.
@@ -41,16 +45,56 @@ export const getTypeIdentifierAnnotation = (schema: Schema.Schema.All) =>
     Option.getOrElse(() => undefined),
   )(schema.ast);
 
+/**
+ * @returns DXN of the schema.
+ *
+ * For non-stored schema returns `dxn:type:`.
+ * For stored schema returns `dxn:echo:`.
+ */
+export const getSchemaDXN = (schema: Schema.Schema.All): DXN | undefined => {
+  assertArgument(Schema.isSchema(schema), 'schema', 'invalid schema');
+  const id = getTypeIdentifierAnnotation(schema);
+  if (id) {
+    return DXN.parse(id);
+  }
+
+  // TODO(dmaretskyi): Add support for dynamic schema.
+  const objectAnnotation = getTypeAnnotation(schema);
+  if (!objectAnnotation) {
+    return undefined;
+  }
+
+  return DXN.fromTypenameAndVersion(objectAnnotation.typename, objectAnnotation.version);
+};
+
+/**
+ * @param input schema or a typename string.
+ * @return type DXN.
+ */
+export const getTypeDXNFromSpecifier = (input: Schema.Schema.All | string): DXN => {
+  if (Schema.isSchema(input)) {
+    return getSchemaDXN(input) ?? raise(new TypeError('Schema has no DXN'));
+  } else {
+    assertArgument(typeof input === 'string', 'input');
+    assertArgument(!input.startsWith('dxn:'), 'input');
+    return DXN.fromTypename(input);
+  }
+};
+
+//
+// TypeAnnotation
+//
+
 /**
  * Fully qualified globally unique typename.
- * Example: `dxos.org/type/Person`
+ * Example: `dxos.org/type/Message`
  */
 // TODO(burdon): Reconcile with short DXN format.
-// TODO(burdon): Change type => schema throughout.
+// TODO(burdon): Change "/type" => "/schema" throughout.
 export const TypenameSchema = Schema.String.pipe(Schema.pattern(/^[a-zA-Z]\w+\.[a-zA-Z]\w{1,}\/[\w/_-]+$/)).annotations(
   {
     description: 'Fully qualified globally unique typename',
-    example: 'dxos.org/type/Person',
+    example: 'dxos.org/type/Message',
   },
 );
 
@@ -82,9 +126,6 @@ export const TypeAnnotation = Schema.extend(
   TypeMeta,
   Schema.Struct({
     kind: Schema.Enums(EntityKind),
-    // kind: Schema.Enums(EntityKind),
-    // typename: Typename,
-    // version: VersionSchema,
 
     /**
      * If this is a relation, the schema of the source object.
@@ -102,8 +143,6 @@ export const TypeAnnotation = Schema.extend(
 
 export interface TypeAnnotation extends Schema.Schema.Type<typeof TypeAnnotation> {}
 
-// export type TypeMeta = Pick<TypeAnnotation, 'typename' | 'version'>;
-
 /**
  * @returns {@link TypeAnnotation} from a schema.
  * Schema must have been created with {@link TypedObject} or {@link TypedLink} or manually assigned an appropriate annotation.
@@ -228,6 +267,10 @@ export const isInstanceOf = <Schema extends Schema.Schema.AnyNoContext>(
   return typeDXN.type === typename;
 };
 
+//
+// PropertyMeta
+//
+
 /**
  * PropertyMeta (metadata for dynamic schema properties).
  * For user-defined annotations.
@@ -261,18 +304,16 @@ export const getPropertyMetaAnnotation = <T>(prop: SchemaAST.PropertySignature,
     Option.getOrElse(() => undefined),
   );
 
+//
+// Reference
+//
+
 /**
  * Schema reference.
  */
 export const ReferenceAnnotationId = Symbol.for('@dxos/schema/annotation/Reference');
-
 export type ReferenceAnnotationValue = TypeAnnotation;
-
-export const getReferenceAnnotation = (schema: Schema.Schema.AnyNoContext) =>
-  Function.pipe(
-    SchemaAST.getAnnotation<ReferenceAnnotationValue>(ReferenceAnnotationId)(schema.ast),
-    Option.getOrElse(() => undefined),
-  );
+export const ReferenceAnnotation = createAnnotationHelper<ReferenceAnnotationValue>(ReferenceAnnotationId);
 
 /**
  * SchemaMeta.
@@ -295,9 +336,13 @@ export const LabelAnnotation = createAnnotationHelper<string[]>(LabelAnnotationI
 
 /**
  * Returns the label for a given object based on {@link LabelAnnotationId}.
+ * Lower-level version that requires explicit schema parameter.
  */
 // TODO(burdon): Convert to JsonPath?
-export const getLabel = <S extends Schema.Schema.Any>(schema: S, object: Schema.Schema.Type<S>): string | undefined => {
+export const getLabelWithSchema = <S extends Schema.Schema.Any>(
+  schema: S,
+  object: Schema.Schema.Type<S>,
+): string | undefined => {
   const annotation = LabelAnnotation.get(schema).pipe(Option.getOrElse(() => ['name']));
   for (const accessor of annotation) {
     assertArgument(
@@ -325,8 +370,13 @@ export const getLabel = <S extends Schema.Schema.Any>(schema: S, object: Schema.
 
 /**
  * Sets the label for a given object based on {@link LabelAnnotationId}.
+ * Lower-level version that requires explicit schema parameter.
  */
-export const setLabel = <S extends Schema.Schema.Any>(schema: S, object: Schema.Schema.Type<S>, label: string) => {
+export const setLabelWithSchema = <S extends Schema.Schema.Any>(
+  schema: S,
+  object: Schema.Schema.Type<S>,
+  label: string,
+) => {
   const annotation = LabelAnnotation.get(schema).pipe(
     Option.map((field) => field[0]),
     Option.getOrElse(() => 'name'),
@@ -342,10 +392,11 @@ export const DescriptionAnnotationId = Symbol.for('@dxos/schema/annotation/Descr
 export const DescriptionAnnotation = createAnnotationHelper<string>(DescriptionAnnotationId);
 
 /**
- * Returns the label for a given object based on {@link LabelAnnotationId}.
+ * Returns the description for a given object based on {@link DescriptionAnnotationId}.
+ * Lower-level version that requires explicit schema parameter.
  */
 // TODO(burdon): Convert to JsonPath?
-export const getDescription = <S extends Schema.Schema.Any>(
+export const getDescriptionWithSchema = <S extends Schema.Schema.Any>(
   schema: S,
   object: Schema.Schema.Type<S>,
 ): string | undefined => {
@@ -369,8 +420,9 @@ export const getDescription = <S extends Schema.Schema.Any>(
 
 /**
  * Sets the description for a given object based on {@link DescriptionAnnotationId}.
+ * Lower-level version that requires explicit schema parameter.
  */
-export const setDescription = <S extends Schema.Schema.Any>(
+export const setDescriptionWithSchema = <S extends Schema.Schema.Any>(
   schema: S,
   object: Schema.Schema.Type<S>,
   description: string,
@@ -406,58 +458,3 @@ export type GeneratorAnnotationValue =
     };
 
 export const GeneratorAnnotation = createAnnotationHelper<GeneratorAnnotationValue>(GeneratorAnnotationId);
-
-/**
- * @returns DXN of the schema.
- *
- * For non-stored schema returns `dxn:type:`.
- * For stored schema returns `dxn:echo:`.
- */
-export const getSchemaDXN = (schema: Schema.Schema.All): DXN | undefined => {
-  assertArgument(Schema.isSchema(schema), 'schema', 'invalid schema');
-
-  const id = getTypeIdentifierAnnotation(schema);
-  if (id) {
-    return DXN.parse(id);
-  }
-
-  // TODO(dmaretskyi): Add support for dynamic schema.
-  const objectAnnotation = getTypeAnnotation(schema);
-  if (!objectAnnotation) {
-    return undefined;
-  }
-
-  return DXN.fromTypenameAndVersion(objectAnnotation.typename, objectAnnotation.version);
-};
-
-/**
- * Returns a reference that will be used to point to a schema.
- * @deprecated Use {@link getSchemaDXN} instead.
- */
-export const getTypeReference = (schema: Schema.Schema.All | undefined): Reference | undefined => {
-  if (!schema) {
-    return undefined;
-  }
-
-  const schemaDXN = getSchemaDXN(schema);
-  if (!schemaDXN) {
-    return undefined;
-  }
-  return Reference.fromDXN(schemaDXN);
-};
-
-/**
- * Returns a reference that will be used to point to a schema.
- * @throws If it is not possible to reference this schema.
- *
- * @deprecated Use {@link getSchemaDXN} instead.
- */
-export const requireTypeReference = (schema: Schema.Schema.AnyNoContext): Reference => {
-  const typeReference = getTypeReference(schema);
-  if (typeReference == null) {
-    // TODO(burdon): Catalog user-facing errors (this is too verbose).
-    throw new Error('Schema must be defined via TypedObject.');
-  }
-
-  return typeReference;
-};

package/src/internal/annotations/util.ts

@@ -13,12 +13,14 @@ import { EntityKind } from '../types';
 
 export interface AnnotationHelper<T> {
   get: (schema: Schema.Schema.Any) => Option.Option<T>;
+  getFromAst: (ast: SchemaAST.AST) => Option.Option<T>;
   set: (value: T) => <S extends Schema.Schema.Any>(schema: S) => S;
 }
 
 export const createAnnotationHelper = <T>(id: symbol): AnnotationHelper<T> => {
   return {
     get: (schema) => SchemaAST.getAnnotation(schema.ast, id),
+    getFromAst: (ast) => SchemaAST.getAnnotation(ast, id),
     set:
       (value) =>
       <S extends Schema.Schema.Any>(schema: S) =>

package/src/internal/api/annotations.ts

@@ -0,0 +1,60 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+/**
+ * Common annotation helpers shared by Obj and Relation modules.
+ */
+
+import {
+  getDescriptionWithSchema,
+  getLabelWithSchema,
+  setDescriptionWithSchema,
+  setLabelWithSchema,
+} from '../annotations';
+import { type Mutable } from '../proxy';
+import { type AnyProperties, getSchema as getSchema$ } from '../types';
+
+/**
+ * Get the label of an entity.
+ * Accepts both reactive entities and snapshots.
+ */
+export const getLabel = (entity: AnyProperties): string | undefined => {
+  const schema = getSchema$(entity);
+  if (schema != null) {
+    return getLabelWithSchema(schema, entity);
+  }
+};
+
+/**
+ * Set the label of an entity.
+ * Must be called within an Obj.change or Relation.change callback.
+ */
+export const setLabel = (entity: Mutable<AnyProperties>, label: string) => {
+  const schema = getSchema$(entity);
+  if (schema != null) {
+    setLabelWithSchema(schema, entity, label);
+  }
+};
+
+/**
+ * Get the description of an entity.
+ * Accepts both reactive entities and snapshots.
+ */
+export const getDescription = (entity: AnyProperties): string | undefined => {
+  const schema = getSchema$(entity);
+  if (schema != null) {
+    return getDescriptionWithSchema(schema, entity);
+  }
+};
+
+/**
+ * Set the description of an entity.
+ * Must be called within an Obj.change or Relation.change callback.
+ */
+export const setDescription = (entity: Mutable<AnyProperties>, description: string) => {
+  const schema = getSchema$(entity);
+  if (schema != null) {
+    setDescriptionWithSchema(schema, entity, description);
+  }
+};

package/src/internal/api/entity.ts

@@ -0,0 +1,29 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { invariant } from '@dxos/invariant';
+import { type DXN } from '@dxos/keys';
+import { assumeType } from '@dxos/util';
+
+import { type InternalObjectProps, ObjectDatabaseId, getObjectDXN } from '../entities';
+import type { AnyEntity } from '../types';
+
+/**
+ * Get the DXN of an entity.
+ * Accepts both reactive entities and snapshots.
+ */
+export const getDXN = (entity: AnyEntity): DXN => {
+  const dxn = getObjectDXN(entity);
+  invariant(dxn != null, 'Invalid entity.');
+  return dxn;
+};
+
+/**
+ * Get the database the entity belongs to.
+ * Accepts both reactive entities and snapshots.
+ */
+export const getDatabase = (entity: AnyEntity): any | undefined => {
+  assumeType<InternalObjectProps>(entity);
+  return entity[ObjectDatabaseId];
+};

package/src/internal/api/index.ts

@@ -0,0 +1,19 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+/**
+ * Shared API helpers for Obj and Relation modules.
+ * These implementations use generic Entity types.
+ * Obj and Relation modules re-export with strongly-typed signatures.
+ *
+ * TODO(wittjosiah): Could this become the new "internal" where we slowly refactor
+ * existing internal modules into here? This would provide a cleaner boundary
+ * and prevent external packages from using internals directly.
+ */
+
+export * from './annotations';
+export * from './entity';
+export * from './meta';
+export * from './sorting';
+export * from './version';

package/src/internal/api/meta.ts

@@ -0,0 +1,88 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type { ForeignKey } from '@dxos/echo-protocol';
+import { assertArgument, invariant } from '@dxos/invariant';
+import type { DeepReadonly } from '@dxos/util';
+
+import { type Mutable } from '../proxy';
+import { type AnyProperties, type ObjectMeta, getMeta as getMeta$ } from '../types';
+
+/**
+ * Deeply read-only version of ObjectMeta.
+ */
+export type ReadonlyMeta = DeepReadonly<ObjectMeta>;
+
+/**
+ * Mutable meta type received in meta mutation callbacks.
+ */
+export type Meta = Mutable<ObjectMeta>;
+
+/**
+ * Get the metadata for an entity with validation.
+ * Returns mutable meta when passed a mutable entity (inside change callback).
+ * Returns read-only meta when passed a regular entity or snapshot.
+ *
+ * TODO(burdon): When passed a Snapshot, should return a snapshot of meta, not the live meta proxy.
+ */
+export function getMetaChecked(entity: Mutable<AnyProperties>): Meta;
+export function getMetaChecked(entity: AnyProperties): ReadonlyMeta;
+export function getMetaChecked(entity: AnyProperties): Meta | ReadonlyMeta {
+  assertArgument(entity, 'entity', 'Should be an entity.');
+  const meta = getMeta$(entity);
+  invariant(meta != null, 'Invalid entity.');
+  return meta;
+}
+
+/**
+ * @returns Foreign keys for the entity from the specified source.
+ * Accepts both reactive entities and snapshots.
+ */
+export const getKeys = (entity: AnyProperties, source: string): ForeignKey[] => {
+  assertArgument(entity, 'entity', 'Should be an entity.');
+  const meta = getMetaChecked(entity);
+  invariant(meta != null, 'Invalid entity.');
+  return meta.keys.filter((key) => key.source === source);
+};
+
+/**
+ * Delete all keys from the entity for the specified source.
+ * Must be called within an Obj.change or Relation.change callback.
+ */
+export const deleteKeys = (entity: Mutable<AnyProperties>, source: string) => {
+  const meta = getMetaChecked(entity);
+  for (let i = 0; i < meta.keys.length; i++) {
+    if (meta.keys[i].source === source) {
+      meta.keys.splice(i, 1);
+      i--;
+    }
+  }
+};
+
+/**
+ * Add a tag to the entity.
+ * Must be called within an Obj.change or Relation.change callback.
+ */
+export const addTag = (entity: Mutable<AnyProperties>, tag: string) => {
+  const meta = getMetaChecked(entity);
+  meta.tags ??= [];
+  meta.tags.push(tag);
+};
+
+/**
+ * Remove a tag from the entity.
+ * Must be called within an Obj.change or Relation.change callback.
+ */
+export const removeTag = (entity: Mutable<AnyProperties>, tag: string) => {
+  const meta = getMetaChecked(entity);
+  if (!meta.tags) {
+    return;
+  }
+  for (let i = 0; i < meta.tags.length; i++) {
+    if (meta.tags[i] === tag) {
+      meta.tags.splice(i, 1);
+      i--;
+    }
+  }
+};

package/src/internal/api/sorting.ts

@@ -0,0 +1,53 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { getTypename } from '../annotations';
+import type { AnyEntity } from '../types';
+
+import { getLabel } from './annotations';
+
+/**
+ * String comparison helper for sorting.
+ */
+export const compare = (a?: string, b?: string): number => {
+  if (a == null) {
+    return b == null ? 0 : 1;
+  }
+  if (b == null) {
+    return -1;
+  }
+  return a.localeCompare(b);
+};
+
+/**
+ * Comparator function type for sorting entities.
+ * Accepts both reactive entities and snapshots.
+ */
+export type Comparator<T extends AnyEntity = AnyEntity> = (a: T, b: T) => number;
+
+/**
+ * Sort entities by label.
+ */
+export const sortByLabel: Comparator = (a: AnyEntity, b: AnyEntity) => compare(getLabel(a), getLabel(b));
+
+/**
+ * Sort entities by typename.
+ */
+export const sortByTypename: Comparator = (a: AnyEntity, b: AnyEntity) => compare(getTypename(a), getTypename(b));
+
+/**
+ * Compose multiple comparators into one.
+ * Applies comparators in order until one returns non-zero.
+ */
+export const sort = <T extends AnyEntity>(...comparators: Comparator<T>[]): Comparator<T> => {
+  return (a: T, b: T) => {
+    for (const comparator of comparators) {
+      const result = comparator(a, b);
+      if (result !== 0) {
+        return result;
+      }
+    }
+    return 0;
+  };
+};

package/src/internal/api/version.ts

@@ -0,0 +1,96 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { assertArgument } from '@dxos/invariant';
+
+import { ObjectVersionId } from '../entities';
+import { type AnyEntity, VersionTypeId } from '../types';
+
+/**
+ * Represent entity version.
+ * May be backed by Automerge.
+ * Entities with no history are not versioned.
+ * Named EntityVersion to avoid conflict with types/version.ts.
+ */
+export interface EntityVersion {
+  [VersionTypeId]: {};
+
+  /**
+   * Whether the entity is versioned.
+   */
+  versioned: boolean;
+
+  /**
+   * Automerge heads.
+   */
+  automergeHeads?: string[];
+}
+
+const unversioned: EntityVersion = {
+  [VersionTypeId]: {},
+  versioned: false,
+};
+
+/**
+ * Checks that `obj` is a version object.
+ */
+export const isVersion = (entity: unknown): entity is EntityVersion => {
+  return entity != null && typeof entity === 'object' && VersionTypeId in entity;
+};
+
+/**
+ * Returns the version of an entity.
+ * Accepts both reactive entities and snapshots.
+ */
+export const version = (entity: AnyEntity): EntityVersion => {
+  const ver = (entity as any)[ObjectVersionId];
+  if (ver === undefined) {
+    return unversioned;
+  }
+  return ver;
+};
+
+/**
+ * Checks that `version` is a valid version object.
+ */
+export const versionValid = (ver: EntityVersion): boolean => {
+  assertArgument(isVersion(ver), 'version', 'Invalid version object');
+  return !!ver.versioned;
+};
+
+export type VersionCompareResult = 'unversioned' | 'equal' | 'different';
+
+/**
+ * Compares two versions.
+ * @param version1
+ * @param version2
+ * @returns 'unversioned' if either entity is unversioned, 'equal' if the versions are equal, 'different' if the versions are different.
+ */
+export const compareVersions = (version1: EntityVersion, version2: EntityVersion): VersionCompareResult => {
+  assertArgument(isVersion(version1), 'version1', 'Invalid version object');
+  assertArgument(isVersion(version2), 'version2', 'Invalid version object');
+
+  if (!versionValid(version1) || !versionValid(version2)) {
+    return 'unversioned';
+  }
+
+  if (version1.automergeHeads?.length !== version2.automergeHeads?.length) {
+    return 'different';
+  }
+  if (version1.automergeHeads?.some((head) => !version2.automergeHeads?.includes(head))) {
+    return 'different';
+  }
+
+  return 'equal';
+};
+
+export const encodeVersion = (ver: EntityVersion): string => {
+  return JSON.stringify(ver);
+};
+
+export const decodeVersion = (ver: string): EntityVersion => {
+  const parsed = JSON.parse(ver);
+  parsed[VersionTypeId] = {};
+  return parsed;
+};