@dxos/echo 0.8.4-main.c1de068 → 0.8.4-main.dedc0f3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/echo",
-  "version": "0.8.4-main.c1de068",
+  "version": "0.8.4-main.dedc0f3",
   "description": "ECHO API",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -10,31 +10,37 @@
   "type": "module",
   "exports": {
     ".": {
+      "source": "./src/index.ts",
       "types": "./dist/types/src/index.d.ts",
       "browser": "./dist/lib/browser/index.mjs",
       "node": "./dist/lib/node-esm/index.mjs"
     },
     "./Type": {
+      "source": "./src/Type.ts",
       "types": "./dist/types/src/Type.d.ts",
       "browser": "./dist/lib/browser/Type.mjs",
       "node": "./dist/lib/node-esm/Type.mjs"
     },
     "./Obj": {
+      "source": "./src/Obj.ts",
       "types": "./dist/types/src/Obj.d.ts",
       "browser": "./dist/lib/browser/Obj.mjs",
       "node": "./dist/lib/node-esm/Obj.mjs"
     },
     "./Relation": {
+      "source": "./src/Relation.ts",
       "types": "./dist/types/src/Relation.d.ts",
       "browser": "./dist/lib/browser/Relation.mjs",
       "node": "./dist/lib/node-esm/Relation.mjs"
     },
     "./Ref": {
+      "source": "./src/Ref.ts",
       "types": "./dist/types/src/Ref.d.ts",
       "browser": "./dist/lib/browser/Ref.mjs",
       "node": "./dist/lib/node-esm/Ref.mjs"
     },
     "./testing": {
+      "source": "./src/testing/types.ts",
       "types": "./dist/types/src/testing/types.d.ts",
       "browser": "./dist/lib/browser/testing/index.mjs",
       "node": "./dist/lib/node-esm/testing/index.mjs"
@@ -66,18 +72,18 @@
   ],
   "dependencies": {
     "@preact/signals-core": "^1.9.0",
-    "effect": "3.17.0",
-    "@dxos/debug": "0.8.4-main.c1de068",
-    "@dxos/echo-protocol": "0.8.4-main.c1de068",
-    "@dxos/echo-schema": "0.8.4-main.c1de068",
-    "@dxos/echo-signals": "0.8.4-main.c1de068",
-    "@dxos/invariant": "0.8.4-main.c1de068",
-    "@dxos/effect": "0.8.4-main.c1de068",
-    "@dxos/keys": "0.8.4-main.c1de068",
-    "@dxos/live-object": "0.8.4-main.c1de068",
-    "@dxos/log": "0.8.4-main.c1de068",
-    "@dxos/node-std": "0.8.4-main.c1de068",
-    "@dxos/util": "0.8.4-main.c1de068"
+    "effect": "3.17.7",
+    "@dxos/debug": "0.8.4-main.dedc0f3",
+    "@dxos/echo-protocol": "0.8.4-main.dedc0f3",
+    "@dxos/echo-schema": "0.8.4-main.dedc0f3",
+    "@dxos/effect": "0.8.4-main.dedc0f3",
+    "@dxos/echo-signals": "0.8.4-main.dedc0f3",
+    "@dxos/invariant": "0.8.4-main.dedc0f3",
+    "@dxos/keys": "0.8.4-main.dedc0f3",
+    "@dxos/live-object": "0.8.4-main.dedc0f3",
+    "@dxos/node-std": "0.8.4-main.dedc0f3",
+    "@dxos/log": "0.8.4-main.dedc0f3",
+    "@dxos/util": "0.8.4-main.dedc0f3"
   },
   "publishConfig": {
     "access": "public"

package/src/Obj.ts

@@ -3,41 +3,57 @@
 //
 
 import { Schema } from 'effect';
+import { dual } from 'effect/Function';
 
 import * as EchoSchema from '@dxos/echo-schema';
 import { assertArgument, invariant } from '@dxos/invariant';
 import { type DXN } from '@dxos/keys';
-import type * as LiveObject from '@dxos/live-object';
+import * as LiveObject from '@dxos/live-object';
 import { live } from '@dxos/live-object';
-import { assumeType } from '@dxos/util';
+import { assumeType, deepMapValues } from '@dxos/util';
 
 import type * as Ref from './Ref';
 import type * as Relation from './Relation';
 import type * as Type from './Type';
 
-// NOTE: Don't export: Obj.Any and Obj.Obj form the public API.
-interface ObjBase extends Type.OfKind<EchoSchema.EntityKind.Object> {
-  readonly id: EchoSchema.ObjectId;
-}
+/**
+ * NOTE: Don't export: Obj.Any and Obj.Obj form the public API.
+ */
+interface BaseObj extends EchoSchema.HasId, Type.OfKind<EchoSchema.EntityKind.Object> {}
 
 /**
  * Object type with specific properties.
  */
-export type Obj<Props> = ObjBase & Props;
+export type Obj<Props> = BaseObj & Props;
 
 /**
  * Base type for all ECHO objects.
  */
-export interface Any extends ObjBase {}
+export interface Any extends BaseObj {}
+
+type Props<T = any> = { id?: EchoSchema.ObjectId } & Type.Properties<T>;
+
+export type MakeProps<T extends Type.Obj.Any> = NoInfer<Props<Schema.Schema.Type<T>>> & {
+  [Meta]?: Partial<EchoSchema.ObjectMeta>;
+};
 
-type Props<T> = { id?: EchoSchema.ObjectId } & Type.Properties<T>;
+export const Meta: unique symbol = EchoSchema.MetaId as any;
 
-export type MakeProps<S extends Type.Obj.Any> = NoInfer<Props<Schema.Schema.Type<S>>>;
+// TODO(dmaretskyi): Expose Meta = EchoSchema.MetaId.
 
 /**
  * Creates new object.
+ * @param schema - Object schema.
+ * @param props - Object properties.
+ * @param meta - Object metadata (deprecated) -- pass with Obj.Meta.
+ *
+ * Meta can be passed as a symbol in `props`.
+ *
+ * Example:
+ * ```ts
+ * const obj = Obj.make(Person, { [Obj.Meta]: { keys: [...] }, name: 'John' });
+ * ```
  */
-// TODO(dmaretskyi): Move meta into props.
 export const make = <S extends Type.Obj.Any>(
   schema: S,
   props: MakeProps<S>,
@@ -45,6 +61,7 @@ export const make = <S extends Type.Obj.Any>(
 ): LiveObject.Live<Schema.Schema.Type<S>> => {
   assertArgument(
     EchoSchema.getTypeAnnotation(schema)?.kind === EchoSchema.EntityKind.Object,
+    'schema',
     'Expected an object schema',
   );
 
@@ -90,8 +107,8 @@ export const instanceOf: {
 export const getSchema = EchoSchema.getSchema;
 
 // TODO(dmaretskyi): Allow returning undefined.
-export const getDXN = (obj: Any): DXN => {
-  assertArgument(!Schema.isSchema(obj), 'Object should not be a schema.');
+export const getDXN = (obj: Any | Relation.Any): DXN => {
+  assertArgument(!Schema.isSchema(obj), 'obj', 'Object should not be a schema.');
   const dxn = EchoSchema.getObjectDXN(obj);
   invariant(dxn != null, 'Invalid object.');
   return dxn;
@@ -108,7 +125,7 @@ export const getTypeDXN = EchoSchema.getType;
  * @returns The typename of the object's type.
  * @example `example.com/type/Contact`
  */
-export const getTypename = (obj: Any): string | undefined => {
+export const getTypename = (obj: Any | Relation.Any): string | undefined => {
   const schema = getSchema(obj);
   if (schema == null) {
     // Try to extract typename from DXN.
@@ -119,27 +136,61 @@ export const getTypename = (obj: Any): string | undefined => {
 };
 
 // TODO(dmaretskyi): Allow returning undefined.
-export const getMeta = (obj: Any): EchoSchema.ObjectMeta => {
+export const getMeta = (obj: Any | Relation.Any): EchoSchema.ObjectMeta => {
   const meta = EchoSchema.getMeta(obj);
   invariant(meta != null, 'Invalid object.');
   return meta;
 };
 
+/**
+ * @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);
+  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 source
+ */
+export const deleteKeys = (obj: Any | Relation.Any, source: string) => {
+  const meta = EchoSchema.getMeta(obj);
+  for (let i = 0; i < meta.keys.length; i++) {
+    if (meta.keys[i].source === source) {
+      meta.keys.splice(i, 1);
+      i--;
+    }
+  }
+};
+
 // TODO(dmaretskyi): Default to `false`.
-export const isDeleted = (obj: Any): boolean => {
+export const isDeleted = (obj: Any | Relation.Any): boolean => {
   const deleted = EchoSchema.isDeleted(obj);
   invariant(typeof deleted === 'boolean', 'Invalid object.');
   return deleted;
 };
 
 // TODO(burdon): Rename "label"
-export const getLabel = (obj: Any): string | undefined => {
+export const getLabel = (obj: Any | Relation.Any): string | undefined => {
   const schema = getSchema(obj);
   if (schema != null) {
     return EchoSchema.getLabel(schema, obj);
   }
 };
 
+export const setLabel = (obj: Any | Relation.Any, label: string) => {
+  const schema = getSchema(obj);
+  if (schema != null) {
+    EchoSchema.setLabel(schema, obj, label);
+  }
+};
+
 /**
  * JSON representation of an object.
  */
@@ -150,6 +201,7 @@ export type JSON = EchoSchema.ObjectJSON;
  *
  * 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);
 
 /**
@@ -157,6 +209,139 @@ export const toJSON = (obj: Any | Relation.Any): JSON => EchoSchema.objectToJSON
  * 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.
+ *
+ * @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 }) => Promise<Any> =
+export const fromJSON: (json: unknown, options?: { refResolver?: Ref.Resolver; dxn?: DXN }) => Promise<Any> =
   EchoSchema.objectFromJSON as any;
+
+/**
+ * Returns an immutable snapshot of an object.
+ */
+export const getSnapshot: <T extends Any>(obj: Obj<T>) => T = LiveObject.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 | 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;
+  }
+  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);
+};
+
+export const VersionTypeId = EchoSchema.VersionTypeId;
+export type VersionType = typeof VersionTypeId;
+
+/**
+ * Represent object version.
+ * May be backed by Automerge.
+ * Objects with no history are not versioned.
+ */
+export interface Version {
+  [VersionTypeId]: {};
+
+  /**
+   * Whether the object is versioned.
+   */
+  versioned: boolean;
+
+  /**
+   * Automerge heads.
+   */
+  automergeHeads?: string[];
+}
+
+const unversioned: Version = {
+  [VersionTypeId]: {},
+  versioned: false,
+};
+
+/**
+ * Checks that `obj` is a version object.
+ */
+export const isVersion = (obj: unknown): obj is Version => {
+  return obj != null && typeof obj === 'object' && VersionTypeId in obj;
+};
+
+/**
+ * Returns the version of the object.
+ */
+export const version = (obj: Any | Relation.Any): Version => {
+  const version = (obj as any)[EchoSchema.ObjectVersionId];
+  if (version === undefined) {
+    return unversioned;
+  }
+  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/Relation.ts

@@ -14,22 +14,23 @@ import { assumeType } from '@dxos/util';
 import type * as Obj from './Obj';
 import type * as Type from './Type';
 
-// NOTE: Don't export: Relation.Relation and Relation.Any form the public API.
-interface RelationBase<Source, Target>
-  extends Type.Relation.Endpoints<Source, Target>,
-    Type.OfKind<EchoSchema.EntityKind.Relation> {
-  readonly id: EchoSchema.ObjectId;
-}
+/**
+ * NOTE: Don't export: Relation.Relation and Relation.Any form the public API.
+ */
+interface BaseRelation<Source, Target>
+  extends EchoSchema.HasId,
+    Type.Relation.Endpoints<Source, Target>,
+    Type.OfKind<EchoSchema.EntityKind.Relation> {}
 
 /**
  * Relation type with specific properties.
  */
-export type Relation<Source extends Obj.Any, Target extends Obj.Any, Props> = RelationBase<Source, Target> & Props;
+export type Relation<Source extends Obj.Any, Target extends Obj.Any, Props> = BaseRelation<Source, Target> & Props;
 
 /**
  * Base type for all ECHO relations.
  */
-export interface Any extends RelationBase<Obj.Any, Obj.Any> {}
+export interface Any extends BaseRelation<Obj.Any, Obj.Any> {}
 
 // TODO(dmaretskyi): Has to be `unique symbol`.
 export const Source: unique symbol = EchoSchema.RelationSourceId as any;
@@ -59,6 +60,7 @@ export const make = <S extends Type.Relation.Any>(
 ): Live<Schema.Schema.Type<S> & Type.OfKind<EchoSchema.EntityKind.Relation>> => {
   assertArgument(
     EchoSchema.getTypeAnnotation(schema)?.kind === EchoSchema.EntityKind.Relation,
+    'schema',
     'Expected a relation schema',
   );
 

package/src/Type.ts

@@ -39,7 +39,7 @@ export type Schema = EchoSchema.EchoSchema;
 /**
  * Returns all properties of an object or relation except for the id and kind.
  */
-export type Properties<T> = Omit<T, 'id' | KindId | RelationModule.Source | RelationModule.Target>;
+export type Properties<T = any> = Omit<T, 'id' | KindId | RelationModule.Source | RelationModule.Target>;
 
 //
 // Obj
@@ -80,6 +80,7 @@ export namespace Obj {
    * NOTE: This is not an instance type.
    */
   // TODO(dmaretskyi): If schema was covariant, we could specify props in here, like `id: ObjectId`.
+  // TODO(burdon): This erases the ECHO type info (e.g., id, typename).
   export type Any = Schema.Schema.AnyNoContext;
 }
 
@@ -87,6 +88,7 @@ export namespace Obj {
 // Expando
 //
 
+// TODO(burdon): We're using Expando in many places as a base type.
 export interface Expando extends OfKind<EchoSchema.EntityKind.Object> {
   [key: string]: any;
 }

package/src/index.ts

@@ -9,5 +9,6 @@ export * as Relation from './Relation';
 export * as Type from './Type';
 
 export { DXN } from '@dxos/keys';
-export { Filter, Query } from './query';
+export { Filter, Order, Query } from './query';
+export { QueryAST } from '@dxos/echo-protocol';
 export { type Live } from '@dxos/live-object';

package/src/query/dsl.test.ts

@@ -9,11 +9,12 @@ import { QueryAST } from '@dxos/echo-protocol';
 import { DXN } from '@dxos/keys';
 import { log } from '@dxos/log';
 
-import { Filter, Query } from './dsl';
 import * as Obj from '../Obj';
 import * as Ref from '../Ref';
 import * as Type from '../Type';
 
+import { Filter, Order, Query } from './dsl';
+
 //
 // Example schema
 //
@@ -73,6 +74,14 @@ describe('query api', () => {
     console.log('getAllPeople', JSON.stringify(getAllPeople.ast, null, 2));
   });
 
+  test('get all people ordered by name', () => {
+    const getAllPeopleOrderedByName = Query.type(Person).orderBy(Order.property('name', 'asc'));
+
+    log('query', { ast: getAllPeopleOrderedByName.ast });
+    Schema.validateSync(QueryAST.Query)(getAllPeopleOrderedByName.ast);
+    console.log('getAllPeopleOrderedByName', JSON.stringify(getAllPeopleOrderedByName.ast, null, 2));
+  });
+
   test('get all people named Fred', () => {
     const PeopleNamedFred = Query.select(Filter.type(Person, { name: 'Fred' }));
 

package/src/query/dsl.ts

@@ -3,6 +3,7 @@
 //
 
 import { Schema } from 'effect';
+import type { NonEmptyArray } from 'effect/Array';
 import type { Simplify } from 'effect/Schema';
 
 import { raise } from '@dxos/debug';
@@ -17,6 +18,35 @@ import type * as Type from '../Type';
 // TODO(dmaretskyi): Split up into interfaces for objects and relations so they can have separate verbs.
 // TODO(dmaretskyi): Undirected relation traversals.
 
+export interface Order<T> {
+  // TODO(dmaretskyi): See new effect-schema approach to variance.
+  '~Order': { value: T };
+
+  ast: QueryAST.Order;
+}
+
+class OrderClass implements Order<any> {
+  private static variance: Order<any>['~Order'] = {} as Order<any>['~Order'];
+
+  static is(value: unknown): value is Order<any> {
+    return typeof value === 'object' && value !== null && '~Order' in value;
+  }
+
+  constructor(public readonly ast: QueryAST.Order) {}
+
+  '~Order' = OrderClass.variance;
+}
+
+export namespace Order {
+  export const natural: Order<any> = new OrderClass({ kind: 'natural' });
+  export const property = <T>(property: keyof T & string, direction: QueryAST.OrderDirection): Order<T> =>
+    new OrderClass({
+      kind: 'property',
+      property,
+      direction,
+    });
+}
+
 export interface Query<T> {
   // TODO(dmaretskyi): See new effect-schema approach to variance.
   '~Query': { value: T };
@@ -85,6 +115,14 @@ export interface Query<T> {
    */
   target(): Query<Type.Relation.Target<T>>;
 
+  /**
+   * Order the query results.
+   * Orders are specified in priority order. The first order will be applied first, etc.
+   * @param order - Order to sort the results.
+   * @returns Query for the ordered results.
+   */
+  orderBy(...order: NonEmptyArray<Order<T>>): Query<T>;
+
   /**
    * Add options to a query.
    */
@@ -94,6 +132,9 @@ export interface Query<T> {
 interface QueryAPI {
   is(value: unknown): value is Query.Any;
 
+  /** Construct a query from an ast. */
+  fromAst(ast: QueryAST.Query): Query<any>;
+
   /**
    * Select objects based on a filter.
    * @param filter - Filter to select the objects.
@@ -329,6 +370,7 @@ class FilterClass implements Filter<any> {
   static ids(...ids: ObjectId[]): Filter<any> {
     assertArgument(
       ids.every((id) => ObjectId.isValid(id)),
+      'ids',
       'ids must be valid',
     );
 
@@ -357,7 +399,7 @@ class FilterClass implements Filter<any> {
   }
 
   static typename(typename: string): Filter<any> {
-    assertArgument(!typename.startsWith('dxn:'), 'Typename must no be qualified');
+    assertArgument(!typename.startsWith('dxn:'), 'typename', 'Typename must no be qualified');
     return new FilterClass({
       type: 'object',
       typename: DXN.fromTypename(typename).toString(),
@@ -506,7 +548,11 @@ type RefPropKey<T> = keyof T & string;
 const propsFilterToAst = (predicates: Filter.Props<any>): Pick<QueryAST.FilterObject, 'id' | 'props'> => {
   let idFilter: readonly ObjectId[] | undefined;
   if ('id' in predicates) {
-    assertArgument(typeof predicates.id === 'string' || Array.isArray(predicates.id), 'invalid id filter');
+    assertArgument(
+      typeof predicates.id === 'string' || Array.isArray(predicates.id),
+      'predicates.id',
+      'invalid id filter',
+    );
     idFilter = typeof predicates.id === 'string' ? [predicates.id] : predicates.id;
     Schema.Array(ObjectId).pipe(Schema.validateSync)(idFilter);
   }
@@ -528,6 +574,10 @@ class QueryClass implements Query<any> {
     return typeof value === 'object' && value !== null && '~Query' in value;
   }
 
+  static fromAst(ast: QueryAST.Query): Query<any> {
+    return new QueryClass(ast);
+  }
+
   static select<F extends Filter.Any>(filter: F): Query<Filter.Type<F>> {
     return new QueryClass({
       type: 'select',
@@ -634,6 +684,14 @@ class QueryClass implements Query<any> {
     });
   }
 
+  orderBy(...order: Order<any>[]): Query<any> {
+    return new QueryClass({
+      type: 'order',
+      query: this.ast,
+      order: order.map((o) => o.ast),
+    });
+  }
+
   options(options: QueryAST.QueryOptions): Query<any> {
     return new QueryClass({
       type: 'options',

package/src/test/api.test.ts

@@ -6,9 +6,9 @@ import { Schema } from 'effect';
 import { describe, test } from 'vitest';
 
 import { raise } from '@dxos/debug';
-import { FormatEnum, FormatAnnotation } from '@dxos/echo-schema';
+import { FormatAnnotation, FormatEnum } from '@dxos/echo-schema';
 
-import { Obj, Ref, Relation, Type, type Live } from '../index';
+import { type Live, Obj, Ref, Relation, Type } from '../index';
 
 namespace Testing {
   export const Organization = Schema.Struct({
@@ -151,6 +151,13 @@ describe('Experimental API review', () => {
     expect(Relation.getTarget(worksFor)).to.eq(organization);
   });
 
+  test('version', ({ expect }) => {
+    const person = Obj.make(Testing.Person, { name: 'Test' });
+    const version = Obj.version(person);
+    expect(Obj.isVersion(version)).to.be.true;
+    expect(Obj.versionValid(version)).to.be.false;
+  });
+
   test.skip('type narrowing', () => {
     const a: Obj.Any | Relation.Any = null as any;