@dxos/echo 0.8.4-main.5ea62a8 → 0.8.4-main.66e292d

package/src/Obj.ts

@@ -2,24 +2,61 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Schema } from 'effect';
-import { dual } from 'effect/Function';
+import * as Function from 'effect/Function';
+import * as Schema from 'effect/Schema';
 
-import * as EchoSchema from '@dxos/echo-schema';
+import { type ForeignKey } from '@dxos/echo-protocol';
 import { assertArgument, invariant } from '@dxos/invariant';
-import { type DXN } from '@dxos/keys';
-import type * as LiveObject from '@dxos/live-object';
-import { live } from '@dxos/live-object';
+import { type DXN, ObjectId } from '@dxos/keys';
+import { getSnapshot as getSnapshot$ } from '@dxos/live-object';
 import { assumeType, deepMapValues } from '@dxos/util';
 
-import type * as Ref from './Ref';
-import type * as Relation from './Relation';
-import type * as Type from './Type';
+import * as Entity from './Entity';
+import {
+  type AnyEchoObject,
+  type AnyProperties,
+  type InternalObjectProps,
+  MetaId,
+  type ObjectJSON,
+  type ObjectMeta,
+  ObjectVersionId,
+  VersionTypeId,
+  getDescription as getDescription$,
+  getLabel as getLabel$,
+  getMeta as getMeta$,
+  getObjectDXN,
+  getSchema as getSchema$,
+  getSchemaTypename,
+  getTypeAnnotation,
+  getTypeDXN as getTypeDXN$,
+  isDeleted as isDeleted$,
+  isInstanceOf,
+  makeObject,
+  objectFromJSON,
+  objectToJSON,
+  setDescription as setDescription$,
+  setLabel as setLabel$,
+} from './internal';
+import * as Ref from './Ref';
+import * as Type from './Type';
 
 /**
- * NOTE: Don't export: Obj.Any and Obj.Obj form the public API.
+ * Base type for all ECHO objects.
+ * @private
  */
-interface BaseObj extends EchoSchema.HasId, Type.OfKind<EchoSchema.EntityKind.Object> {}
+interface BaseObj extends AnyEchoObject, Entity.OfKind<typeof Entity.Kind.Object> {}
+
+/**
+ * Base type for all Obj objects.
+ */
+export interface Any extends BaseObj {}
+
+export const Any = Schema.Struct({}).pipe(
+  Type.Obj({
+    typename: 'dxos.org/type/Any',
+    version: '0.1.0',
+  }),
+);
 
 /**
  * Object type with specific properties.
@@ -27,22 +64,30 @@ interface BaseObj extends EchoSchema.HasId, Type.OfKind<EchoSchema.EntityKind.Ob
 export type Obj<Props> = BaseObj & Props;
 
 /**
- * Base type for all ECHO objects.
+ * Object with arbitrary properties.
+ *
+ * NOTE: Due to how typescript works, this type is not assignable to a specific schema type.
+ * In that case, use `Obj.instanceOf` to check if an object is of a specific type.
  */
-export interface Any extends BaseObj {}
-
-type Props<T = any> = { id?: EchoSchema.ObjectId } & Type.Properties<T>;
+export interface AnyProps extends BaseObj, AnyProperties {}
 
-export type MakeProps<T extends Type.Obj.Any> = NoInfer<Props<Schema.Schema.Type<T>>> & {
-  [Meta]?: Partial<EchoSchema.ObjectMeta>;
+const defaultMeta: ObjectMeta = {
+  keys: [],
 };
 
-export const Meta: unique symbol = EchoSchema.MetaId as any;
+type Props<T = any> = {
+  id?: ObjectId;
+  [Meta]?: Partial<ObjectMeta>;
+} & Type.Properties<T>;
 
-// TODO(dmaretskyi): Expose Meta = EchoSchema.MetaId.
+// TODO(burdon): Should we allow the caller to set the id?
+export type MakeProps<T extends Schema.Schema.AnyNoContext> = {
+  id?: ObjectId;
+  [Meta]?: Partial<ObjectMeta>;
+} & NoInfer<Props<Schema.Schema.Type<T>>>;
 
 /**
- * Creates new object.
+ * Creates a new object of the given types.
  * @param schema - Object schema.
  * @param props - Object properties.
  * @param meta - Object metadata (deprecated) -- pass with Obj.Meta.
@@ -54,89 +99,157 @@ export const Meta: unique symbol = EchoSchema.MetaId as any;
  * const obj = Obj.make(Person, { [Obj.Meta]: { keys: [...] }, name: 'John' });
  * ```
  */
-export const make = <S extends Type.Obj.Any>(
+export const make = <S extends Schema.Schema.AnyNoContext>(
   schema: S,
   props: MakeProps<S>,
-  meta?: EchoSchema.ObjectMeta,
-): LiveObject.Live<Schema.Schema.Type<S>> => {
-  assertArgument(
-    EchoSchema.getTypeAnnotation(schema)?.kind === EchoSchema.EntityKind.Object,
-    'Expected an object schema',
-  );
-
-  if (props[EchoSchema.MetaId] != null) {
-    meta = props[EchoSchema.MetaId] as any;
-    delete props[EchoSchema.MetaId];
+  meta?: Partial<ObjectMeta>,
+): Obj<Schema.Schema.Type<S>> => {
+  assertArgument(getTypeAnnotation(schema)?.kind === Entity.Kind.Object, 'schema', 'Expected an object schema');
+
+  // Set default fields on meta on creation.
+  if (props[MetaId] != null) {
+    meta = { ...structuredClone(defaultMeta), ...props[MetaId] };
+    delete props[MetaId];
   }
 
-  return live<Schema.Schema.Type<S>>(schema, props as any, meta);
+  // Filter undefined values.
+  const filterUndefined = Object.fromEntries(Object.entries(props).filter(([_, v]) => v !== undefined));
+
+  return makeObject<Schema.Schema.Type<S>>(schema, filterUndefined as any, {
+    ...defaultMeta,
+    ...meta,
+  });
 };
 
+/**
+ * Determine if object is an ECHO object.
+ */
 export const isObject = (obj: unknown): obj is Any => {
-  assumeType<EchoSchema.InternalObjectProps>(obj);
-  return typeof obj === 'object' && obj !== null && obj[EchoSchema.EntityKindId] === EchoSchema.EntityKind.Object;
+  assumeType<InternalObjectProps>(obj);
+  return typeof obj === 'object' && obj !== null && obj[Entity.KindId] === Entity.Kind.Object;
+};
+
+//
+// Snapshot
+//
+
+/**
+ * Returns an immutable snapshot of an object.
+ */
+export const getSnapshot: <T extends Any>(obj: Obj<T>) => T = getSnapshot$;
+
+export type CloneOptions = {
+  /**
+   * Retain the original object's ID.
+   * @default false
+   */
+  retainId?: boolean;
+};
+
+/**
+ * Clones an object or relation.
+ * This does not clone referenced objects, only the properties in the object.
+ * @returns A new object with the same schema and properties.
+ */
+export const clone = <T extends Any>(obj: T, opts?: CloneOptions): T => {
+  const { id, ...data } = obj;
+  const schema = getSchema$(obj);
+  invariant(schema != null, 'Object should have a schema');
+  const props: any = deepMapValues(data, (value, recurse) => {
+    if (Ref.isRef(value)) {
+      return value;
+    }
+    return recurse(value);
+  });
+
+  if (opts?.retainId) {
+    props.id = id;
+  }
+  const meta = getMeta(obj);
+  props[MetaId] = deepMapValues(meta, (value, recurse) => {
+    if (Ref.isRef(value)) {
+      return value;
+    }
+    return recurse(value);
+  });
+
+  return make(schema as Type.Obj.Any, props);
 };
 
+//
+// Type
+//
+
+// TODO(burdon): To discuss: prefer over ObjectId or Key.ObjectId or Type.ID?
+export const ID = ObjectId;
+export type ID = ObjectId;
+
 /**
  * Test if object or relation is an instance of a schema.
  * @example
  * ```ts
  * const john = Obj.make(Person, { name: 'John' });
- * const johnIsPerson = Obj.instanceOf(Person)(john);
- *
  * const isPerson = Obj.instanceOf(Person);
- * if(isPerson(john)) {
+ * if (isPerson(john)) {
  *   // john is Person
  * }
  * ```
  */
 export const instanceOf: {
-  <S extends Type.Relation.Any | Type.Obj.Any>(schema: S): (value: unknown) => value is Schema.Schema.Type<S>;
-  <S extends Type.Relation.Any | Type.Obj.Any>(schema: S, value: unknown): value is Schema.Schema.Type<S>;
-} = ((
-  ...args: [schema: Type.Relation.Any | Type.Obj.Any, value: unknown] | [schema: Type.Relation.Any | Type.Obj.Any]
-) => {
+  <S extends Type.Entity.Any>(schema: S): (value: unknown) => value is Schema.Schema.Type<S>;
+  <S extends Type.Entity.Any>(schema: S, value: unknown): value is Schema.Schema.Type<S>;
+} = ((...args: [schema: Type.Entity.Any, value: unknown] | [schema: Type.Entity.Any]) => {
   if (args.length === 1) {
-    return (obj: unknown) => EchoSchema.isInstanceOf(args[0], obj);
+    return (entity: unknown) => isInstanceOf(args[0], entity);
   }
 
-  return EchoSchema.isInstanceOf(args[0], args[1]);
+  return isInstanceOf(args[0], args[1]);
 }) as any;
 
-export const getSchema = EchoSchema.getSchema;
-
 // TODO(dmaretskyi): Allow returning undefined.
-export const getDXN = (obj: Any | Relation.Any): DXN => {
-  assertArgument(!Schema.isSchema(obj), 'Object should not be a schema.');
-  const dxn = EchoSchema.getObjectDXN(obj);
+export const getDXN = (entity: Entity.Unknown): DXN => {
+  assertArgument(!Schema.isSchema(entity), 'obj', 'Object should not be a schema.');
+  const dxn = getObjectDXN(entity);
   invariant(dxn != null, 'Invalid object.');
   return dxn;
 };
 
 /**
  * @returns The DXN of the object's type.
- * @example dxn:example.com/type/Contact:1.0.0
+ * @example dxn:example.com/type/Person:1.0.0
+ */
+// TODO(burdon): Must define and return type for expando.
+export const getTypeDXN = getTypeDXN$;
+
+/**
+ * Get the schema of the object.
  */
-// TODO(burdon): Expando does not have a type.
-export const getTypeDXN = EchoSchema.getType;
+export const getSchema = getSchema$;
 
 /**
  * @returns The typename of the object's type.
- * @example `example.com/type/Contact`
+ * @example `example.com/type/Person`
  */
-export const getTypename = (obj: Any | Relation.Any): string | undefined => {
-  const schema = getSchema(obj);
+export const getTypename = (entity: Entity.Unknown): string | undefined => {
+  const schema = getSchema$(entity);
   if (schema == null) {
     // Try to extract typename from DXN.
-    return EchoSchema.getType(obj)?.asTypeDXN()?.type;
+    return getTypeDXN$(entity)?.asTypeDXN()?.type;
   }
 
-  return EchoSchema.getSchemaTypename(schema);
+  return getSchemaTypename(schema);
 };
 
+//
+// Meta
+//
+
+export const Meta: unique symbol = MetaId as any;
+
+// TODO(burdon): Narrow type.
 // TODO(dmaretskyi): Allow returning undefined.
-export const getMeta = (obj: Any | Relation.Any): EchoSchema.ObjectMeta => {
-  const meta = EchoSchema.getMeta(obj);
+export const getMeta = (entity: AnyProperties): ObjectMeta => {
+  const meta = getMeta$(entity);
   invariant(meta != null, 'Invalid object.');
   return meta;
 };
@@ -145,21 +258,21 @@ export const getMeta = (obj: Any | Relation.Any): EchoSchema.ObjectMeta => {
  * @returns Foreign keys for the object from the specified source.
  */
 export const getKeys: {
-  (obj: Any | Relation.Any, source: string): EchoSchema.ForeignKey[];
-  (source: string): (obj: Any | Relation.Any) => EchoSchema.ForeignKey[];
-} = dual(2, (obj: Any | Relation.Any, source?: string): EchoSchema.ForeignKey[] => {
-  const meta = EchoSchema.getMeta(obj);
+  (entity: Entity.Unknown, source: string): ForeignKey[];
+  (source: string): (entity: Entity.Unknown) => ForeignKey[];
+} = Function.dual(2, (entity: Entity.Unknown, source?: string): ForeignKey[] => {
+  const meta = getMeta(entity);
   invariant(meta != null, 'Invalid object.');
   return meta.keys.filter((key) => key.source === source);
 });
 
 /**
  * Delete all keys from the object for the specified source.
- * @param obj
+ * @param entity
  * @param source
  */
-export const deleteKeys = (obj: Any | Relation.Any, source: string) => {
-  const meta = EchoSchema.getMeta(obj);
+export const deleteKeys = (entity: Entity.Unknown, source: string) => {
+  const meta = getMeta(entity);
   for (let i = 0; i < meta.keys.length; i++) {
     if (meta.keys[i].source === source) {
       meta.keys.splice(i, 1);
@@ -168,85 +281,218 @@ export const deleteKeys = (obj: Any | Relation.Any, source: string) => {
   }
 };
 
+export const addTag = (entity: Entity.Unknown, tag: string) => {
+  const meta = getMeta(entity);
+  meta.tags ??= [];
+  meta.tags.push(tag);
+};
+
+export const removeTag = (entity: Entity.Unknown, tag: string) => {
+  const meta = getMeta(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--;
+    }
+  }
+};
+
 // TODO(dmaretskyi): Default to `false`.
-export const isDeleted = (obj: Any | Relation.Any): boolean => {
-  const deleted = EchoSchema.isDeleted(obj);
+export const isDeleted = (entity: Entity.Unknown): boolean => {
+  const deleted = isDeleted$(entity);
   invariant(typeof deleted === 'boolean', 'Invalid object.');
   return deleted;
 };
 
-// TODO(burdon): Rename "label"
-export const getLabel = (obj: Any | Relation.Any): string | undefined => {
-  const schema = getSchema(obj);
+//
+// Annotations
+//
+
+export const getLabel = (entity: Entity.Unknown): string | undefined => {
+  const schema = getSchema$(entity);
   if (schema != null) {
-    return EchoSchema.getLabel(schema, obj);
+    return getLabel$(schema, entity);
   }
 };
 
-export const setLabel = (obj: Any | Relation.Any, label: string) => {
-  const schema = getSchema(obj);
+export const setLabel = (entity: Entity.Unknown, label: string) => {
+  const schema = getSchema$(entity);
   if (schema != null) {
-    EchoSchema.setLabel(schema, obj, label);
+    setLabel$(schema, entity, label);
   }
 };
 
+export const getDescription = (entity: Entity.Unknown): string | undefined => {
+  const schema = getSchema$(entity);
+  if (schema != null) {
+    return getDescription$(schema, entity);
+  }
+};
+
+export const setDescription = (entity: Entity.Unknown, description: string) => {
+  const schema = getSchema$(entity);
+  if (schema != null) {
+    setDescription$(schema, entity, description);
+  }
+};
+
+//
+// JSON
+//
+
 /**
  * JSON representation of an object.
  */
-export type JSON = EchoSchema.ObjectJSON;
+export type JSON = ObjectJSON;
 
 /**
  * Converts object to its JSON representation.
  *
  * The same algorithm is used when calling the standard `JSON.stringify(obj)` function.
  */
-// TODO(burdon): Base util type for Obj/Relation?
-export const toJSON = (obj: Any | Relation.Any): JSON => EchoSchema.objectToJSON(obj);
+export const toJSON = (entity: Entity.Unknown): JSON => objectToJSON(entity);
 
 /**
  * Creates an object from its json representation, performing schema validation.
  * References and schemas will be resolvable if the `refResolver` is provided.
  *
- * The function need to be async to support resolving the schema as well as the relation endpoints.
+ * The function must be async to support resolving the schema as well as the relation endpoints.
  *
  * @param options.refResolver - Resolver for references. Produces hydrated references that can be resolved.
  * @param options.dxn - Override object DXN. Changes the result of `Obj.getDXN`.
  */
 export const fromJSON: (json: unknown, options?: { refResolver?: Ref.Resolver; dxn?: DXN }) => Promise<Any> =
-  EchoSchema.objectFromJSON as any;
+  objectFromJSON as any;
+
+//
+// Sorting
+//
+
+const compare = (a?: string, b?: string) => {
+  if (a == null) {
+    return b == null ? 0 : 1;
+  }
+
+  if (b == null) {
+    return -1;
+  }
+
+  return a.localeCompare(b);
+};
+
+export type Comparator = (a: Entity.Unknown, b: Entity.Unknown) => number;
+
+export const sortByLabel: Comparator = (a: Entity.Unknown, b: Entity.Unknown) => compare(getLabel(a), getLabel(b));
+export const sortByTypename: Comparator = (a: Entity.Unknown, b: Entity.Unknown) =>
+  compare(getTypename(a), getTypename(b));
+export const sort = (...comparators: Comparator[]): Comparator => {
+  return (a: Entity.Unknown, b: Entity.Unknown) => {
+    for (const comparator of comparators) {
+      const result = comparator(a, b);
+      if (result !== 0) {
+        return result;
+      }
+    }
+
+    return 0;
+  };
+};
+
+//
+// Version
+//
+
+/**
+ * Unique symbol for version type identification.
+ */
+export { VersionTypeId };
+
+/**
+ * Represent object version.
+ * May be backed by Automerge.
+ * Objects with no history are not versioned.
+ */
+export interface Version {
+  [VersionTypeId]: {};
 
-export type CloneOptions = {
   /**
-   * Retain the original object's ID.
-   * @default false
+   * Whether the object is versioned.
    */
-  retainId?: boolean;
+  versioned: boolean;
+
+  /**
+   * Automerge heads.
+   */
+  automergeHeads?: string[];
+}
+
+const unversioned: Version = {
+  [VersionTypeId]: {},
+  versioned: false,
 };
 
 /**
- * Clones an object or relation.
- * This does not clone referenced objects, only the properties in the object.
- * @returns A new object with the same schema and properties.
+ * Checks that `obj` is a version object.
  */
-export const clone = <T extends Any | Relation.Any>(obj: T, opts?: CloneOptions): T => {
-  const { id, ...data } = obj;
-  const schema = getSchema(obj);
-  invariant(schema != null, 'Object should have a schema');
-  const props: any = deepMapValues(data, (value, recurse) => {
-    if (EchoSchema.Ref.isRef(value)) {
-      return value;
-    }
-    return recurse(value);
-  });
-  if (opts?.retainId) {
-    props.id = id;
+export const isVersion = (entity: unknown): entity is Version => {
+  return entity != null && typeof entity === 'object' && VersionTypeId in entity;
+};
+
+/**
+ * Returns the version of the object.
+ */
+export const version = (entity: Entity.Unknown): Version => {
+  const version = (entity as any)[ObjectVersionId];
+  if (version === undefined) {
+    return unversioned;
   }
-  const meta = getMeta(obj);
-  props[EchoSchema.MetaId] = deepMapValues(meta, (value, recurse) => {
-    if (EchoSchema.Ref.isRef(value)) {
-      return value;
-    }
-    return recurse(value);
-  });
-  return make(schema, props);
+
+  return version;
+};
+
+/**
+ * Checks that `version` is a valid version object.
+ */
+export const versionValid = (version: Version): boolean => {
+  assertArgument(isVersion(version), 'version', 'Invalid version object');
+  return !!version.versioned;
+};
+
+export type VersionCompareResult = 'unversioned' | 'equal' | 'different';
+
+/**
+ * Compares two versions.
+ * @param version1
+ * @param version2
+ * @returns 'unversioned' if either object is unversioned, 'equal' if the versions are equal, 'different' if the versions are different.
+ */
+export const compareVersions = (version1: Version, version2: Version): 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 = (version: Version): string => {
+  return JSON.stringify(version);
+};
+
+export const decodeVersion = (version: string): Version => {
+  const parsed = JSON.parse(version);
+  parsed[VersionTypeId] = {};
+  return parsed;
 };

package/src/Ref.ts

@@ -2,28 +2,27 @@
 // Copyright 2025 DXOS.org
 //
 
-import * as EchoSchema from '@dxos/echo-schema';
-
+import { Ref as Ref$, RefArray, type RefResolver } from './internal';
 import type * as Obj from './Obj';
 
-export type Ref<T> = EchoSchema.Ref<T>;
-export type Any = EchoSchema.Ref<Obj.Any>;
+export type Ref<T> = Ref$<T>;
+export type Any = Ref$<Obj.Any>;
 
-export const Array = EchoSchema.RefArray;
+export const Array = RefArray;
 
 /**
  * Extract reference target.
  */
-export type Target<R extends Any> = R extends EchoSchema.Ref<infer T> ? T : never;
+export type Target<R extends Any> = R extends Ref$<infer T> ? T : never;
 
 /**
  * Reference resolver.
  */
-export type Resolver = EchoSchema.RefResolver;
+export type Resolver = RefResolver;
 
-export const isRef: (value: unknown) => value is Any = EchoSchema.Ref.isRef;
+export const isRef: (value: unknown) => value is Any = Ref$.isRef;
 
-export const make = EchoSchema.Ref.make;
+export const make = Ref$.make;
 
 // TODO(dmaretskyi): Consider just allowing `make` to accept DXN.
-export const fromDXN = EchoSchema.Ref.fromDXN;
+export const fromDXN = Ref$.fromDXN;