@dxos/echo 0.8.4-main.67995b8 → 0.8.4-main.72ec0f3

package/src/query/{dsl.ts → query.ts}

@@ -2,20 +2,53 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Schema } from 'effect';
-import type { Simplify } from 'effect/Schema';
+import type * as EffectArray from 'effect/Array';
+import * as Match from 'effect/Match';
+import * as Schema from 'effect/Schema';
+import type * as Types from 'effect/Types';
 
 import { raise } from '@dxos/debug';
 import { type ForeignKey, type QueryAST } from '@dxos/echo-protocol';
-import { getTypeReference } from '@dxos/echo-schema';
 import { assertArgument } from '@dxos/invariant';
 import { DXN, ObjectId } from '@dxos/keys';
 
+import { getTypeReference } from '../internal';
+import type * as Obj from '../Obj';
 import * as Ref from '../Ref';
 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.
+// TODO(wittjosiah): Make Filter & Query pipeable.
+
+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.
@@ -33,10 +66,18 @@ export interface Query<T> {
 
   /**
    * Traverse an outgoing reference.
-   * @param key - Property path inside T that is a reference.
+   * @param key - Property path inside T that is a reference or optional reference.
    * @returns Query for the target of the reference.
    */
-  reference<K extends RefPropKey<T>>(key: K): Query<T[K] extends Ref.Any ? Ref.Target<T[K]> : never>;
+  reference<K extends RefPropKey<T>>(
+    key: K,
+  ): Query<
+    T[K] extends Ref.Any
+      ? Ref.Target<T[K]>
+      : T[K] extends Ref.Any | undefined
+        ? Ref.Target<Exclude<T[K], undefined>>
+        : never
+  >;
 
   /**
    * Find objects referencing this object.
@@ -47,7 +88,7 @@ export interface Query<T> {
   // TODO(dmaretskyi): any way to enforce `Ref.Target<Schema.Schema.Type<S>[key]> == T`?
   // TODO(dmaretskyi): Ability to go through arrays of references.
   referencedBy<S extends Schema.Schema.All>(
-    target: S,
+    target: S | string,
     key: RefPropKey<Schema.Schema.Type<S>>,
   ): Query<Schema.Schema.Type<S>>;
 
@@ -58,7 +99,7 @@ export interface Query<T> {
    * @param predicates - Predicates to filter the relation objects.
    */
   sourceOf<S extends Schema.Schema.All>(
-    relation: S,
+    relation: S | string,
     predicates?: Filter.Props<Schema.Schema.Type<S>>,
   ): Query<Schema.Schema.Type<S>>;
 
@@ -69,7 +110,7 @@ export interface Query<T> {
    * @param predicates - Predicates to filter the relation objects.
    */
   targetOf<S extends Schema.Schema.All>(
-    relation: S,
+    relation: S | string,
     predicates?: Filter.Props<Schema.Schema.Type<S>>,
   ): Query<Schema.Schema.Type<S>>;
 
@@ -85,6 +126,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: EffectArray.NonEmptyArray<Order<T>>): Query<T>;
+
   /**
    * Add options to a query.
    */
@@ -94,6 +143,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.
@@ -110,7 +162,7 @@ interface QueryAPI {
    * Shorthand for: `Query.select(Filter.type(schema, predicates))`.
    */
   type<S extends Schema.Schema.All>(
-    schema: S,
+    schema: S | string,
     predicates?: Filter.Props<Schema.Schema.Type<S>>,
   ): Query<Schema.Schema.Type<S>>;
 
@@ -144,7 +196,7 @@ export declare namespace Query {
 
 export interface Filter<T> {
   // TODO(dmaretskyi): See new effect-schema approach to variance.
-  '~Filter': { value: T };
+  '~Filter': { value: Types.Contravariant<T> };
 
   ast: QueryAST.Filter;
 }
@@ -154,48 +206,56 @@ type Intersection<Types extends readonly unknown[]> = Types extends [infer First
   : unknown;
 
 interface FilterAPI {
-  is(value: unknown): value is Filter<any>;
+  is(value: unknown): value is Filter.Any;
+
+  /** Construct a filter from an ast. */
+  fromAst(ast: QueryAST.Filter): Filter<Obj.Any>;
 
   /**
    * Filter that matches all objects.
    */
-  everything(): Filter<any>;
+  // TODO(dmaretskyi): `Obj.Any` would be more type-safe, but causes annoying errors in existing code
+  everything(): Filter<Obj.AnyProps>;
 
   /**
    * Filter that matches no objects.
    */
+  // TODO(dmaretskyi): Filter<never>?
   nothing(): Filter<any>;
 
   /**
    * Filter by object IDs.
    */
   // TODO(dmaretskyi): Rename to `Filter.id`.
-  ids(...id: ObjectId[]): Filter<any>;
+  ids(...id: ObjectId[]): Filter<Obj.AnyProps>;
 
   /**
    * Filter by type.
    */
   type<S extends Schema.Schema.All>(
-    schema: S,
+    schema: S | string,
     props?: Filter.Props<Schema.Schema.Type<S>>,
   ): Filter<Schema.Schema.Type<S>>;
 
   /**
    * Filter by non-qualified typename.
    */
-  typename(typename: string): Filter<any>;
+  typename(typename: string): Filter<Obj.AnyProps>;
 
   /**
    * Filter by fully qualified type DXN.
    */
-  typeDXN(dxn: DXN): Filter<any>;
+  typeDXN(dxn: DXN): Filter<Obj.AnyProps>;
+
+  /**
+   * Filter by tag.
+   */
+  tag(tag: string): Filter<Obj.Any>;
 
   /**
    * Filter by properties.
-   *
-   * INTERNAL API: Do not use.
    */
-  _props<T>(props: Filter.Props<T>): Filter<T>;
+  props<T>(props: Filter.Props<T>): Filter<T>;
 
   /**
    * Full-text or vector search.
@@ -252,12 +312,18 @@ interface FilterAPI {
    */
   in<T>(...values: T[]): Filter<T>;
 
+  /**
+   * Predicate for an array property to contain the provided value.
+   * @param value - Value to check against.
+   */
+  contains<T>(value: T): Filter<readonly T[] | undefined>;
+
   /**
    * Predicate for property to be in the provided range.
    * @param from - Start of the range (inclusive).
    * @param to - End of the range (exclusive).
    */
-  between<T>(from: T, to: T): Filter<T>;
+  between<T>(from: T, to: T): Filter<unknown>;
 
   /**
    * Negate the filter.
@@ -287,11 +353,12 @@ export declare namespace Filter {
 
   type Type<F extends Any> = F extends Filter<infer T> ? T : never;
 
-  type And<FS extends readonly Any[]> = Simplify<Intersection<{ [K in keyof FS]: Type<FS[K]> }>>;
+  type And<FS extends readonly Any[]> = Schema.Simplify<Intersection<{ [K in keyof FS]: Type<FS[K]> }>>;
 
-  type Or<FS extends readonly Any[]> = Simplify<{ [K in keyof FS]: Type<FS[K]> }[number]>;
+  type Or<FS extends readonly Any[]> = Schema.Simplify<{ [K in keyof FS]: Type<FS[K]> }[number]>;
 }
 
+// TODO(dmaretskyi): Separate object instead of statics for better devex with type errors.
 class FilterClass implements Filter<any> {
   private static variance: Filter<any>['~Filter'] = {} as Filter<any>['~Filter'];
 
@@ -299,6 +366,10 @@ class FilterClass implements Filter<any> {
     return typeof value === 'object' && value !== null && '~Filter' in value;
   }
 
+  static fromAst(ast: QueryAST.Filter): Filter<any> {
+    return new FilterClass(ast);
+  }
+
   static everything(): FilterClass {
     return new FilterClass({
       type: 'object',
@@ -329,6 +400,7 @@ class FilterClass implements Filter<any> {
   static ids(...ids: ObjectId[]): Filter<any> {
     assertArgument(
       ids.every((id) => ObjectId.isValid(id)),
+      'ids',
       'ids must be valid',
     );
 
@@ -345,10 +417,10 @@ class FilterClass implements Filter<any> {
   }
 
   static type<S extends Schema.Schema.All>(
-    schema: S,
+    schema: S | string,
     props?: Filter.Props<Schema.Schema.Type<S>>,
   ): Filter<Schema.Schema.Type<S>> {
-    const dxn = getTypeReference(schema)?.toDXN() ?? raise(new TypeError('Schema has no DXN'));
+    const dxn = getTypeDXNFromSpecifier(schema);
     return new FilterClass({
       type: 'object',
       typename: dxn.toString(),
@@ -357,7 +429,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(),
@@ -373,10 +445,14 @@ class FilterClass implements Filter<any> {
     });
   }
 
-  /**
-   * @internal
-   */
-  static _props<T>(props: Filter.Props<T>): Filter<T> {
+  static tag(tag: string): Filter<any> {
+    return new FilterClass({
+      type: 'tag',
+      tag,
+    });
+  }
+
+  static props<T>(props: Filter.Props<T>): Filter<T> {
     return new FilterClass({
       type: 'object',
       typename: null,
@@ -392,8 +468,11 @@ class FilterClass implements Filter<any> {
     });
   }
 
-  static foreignKeys<S extends Schema.Schema.All>(schema: S, keys: ForeignKey[]): Filter<Schema.Schema.Type<S>> {
-    const dxn = getTypeReference(schema)?.toDXN() ?? raise(new TypeError('Schema has no DXN'));
+  static foreignKeys<S extends Schema.Schema.All>(
+    schema: S | string,
+    keys: ForeignKey[],
+  ): Filter<Schema.Schema.Type<S>> {
+    const dxn = getTypeDXNFromSpecifier(schema);
     return new FilterClass({
       type: 'object',
       typename: dxn.toString(),
@@ -461,7 +540,14 @@ class FilterClass implements Filter<any> {
     });
   }
 
-  static between<T>(from: T, to: T): Filter<T> {
+  static contains<T>(value: T): Filter<readonly T[] | undefined> {
+    return new FilterClass({
+      type: 'contains',
+      value,
+    });
+  }
+
+  static between<T>(from: T, to: T): Filter<unknown> {
     return new FilterClass({
       type: 'range',
       from,
@@ -506,7 +592,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);
   }
@@ -516,11 +606,38 @@ const propsFilterToAst = (predicates: Filter.Props<any>): Pick<QueryAST.FilterOb
     props: Object.fromEntries(
       Object.entries(predicates)
         .filter(([prop, _value]) => prop !== 'id')
-        .map(([prop, predicate]) => [prop, Filter.is(predicate) ? predicate.ast : Filter.eq(predicate).ast]),
+        .map(([prop, predicate]) => [prop, processPredicate(predicate)]),
     ) as Record<string, QueryAST.Filter>,
   };
 };
 
+const processPredicate = (predicate: any): QueryAST.Filter => {
+  return Match.value(predicate).pipe(
+    Match.withReturnType<QueryAST.Filter>(),
+    Match.when(Filter.is, (predicate) => predicate.ast),
+    // TODO(wittjosiah): Add support for array predicates.
+    Match.when(Array.isArray, (_predicate) => {
+      throw new Error('Array predicates are not yet supported.');
+    }),
+    Match.when(
+      (predicate: any) => !Ref.isRef(predicate) && typeof predicate === 'object' && predicate !== null,
+      (predicate) => {
+        const nestedProps = Object.fromEntries(
+          Object.entries(predicate).map(([key, value]) => [key, processPredicate(value)]),
+        );
+
+        return {
+          type: 'object',
+          typename: null,
+          props: nestedProps,
+        };
+      },
+    ),
+    Match.orElse((value) => Filter.eq(value).ast),
+  );
+};
+
+// TODO(dmaretskyi): Separate object instead of statics for better devex with type errors.
 class QueryClass implements Query<any> {
   private static variance: Query<any>['~Query'] = {} as Query<any>['~Query'];
 
@@ -528,6 +645,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',
@@ -535,7 +656,7 @@ class QueryClass implements Query<any> {
     });
   }
 
-  static type(schema: Schema.Schema.All, predicates?: Filter.Props<unknown>): Query<any> {
+  static type(schema: Schema.Schema.All | string, predicates?: Filter.Props<unknown>): Query<any> {
     return new QueryClass({
       type: 'select',
       filter: FilterClass.type(schema, predicates).ast,
@@ -566,7 +687,7 @@ class QueryClass implements Query<any> {
 
   '~Query' = QueryClass.variance;
 
-  select(filter: Filter<any> | Filter.Props<any>): Query<any> {
+  select(filter: Filter.Any | Filter.Props<any>): Query.Any {
     if (Filter.is(filter)) {
       return new QueryClass({
         type: 'filter',
@@ -577,12 +698,12 @@ class QueryClass implements Query<any> {
       return new QueryClass({
         type: 'filter',
         selection: this.ast,
-        filter: FilterClass._props(filter).ast,
+        filter: FilterClass.props(filter).ast,
       });
     }
   }
 
-  reference(key: string): Query<any> {
+  reference(key: string): Query.Any {
     return new QueryClass({
       type: 'reference-traversal',
       anchor: this.ast,
@@ -590,8 +711,8 @@ class QueryClass implements Query<any> {
     });
   }
 
-  referencedBy(target: Schema.Schema.All, key: string): Query<any> {
-    const dxn = getTypeReference(target)?.toDXN() ?? raise(new TypeError('Target schema has no DXN'));
+  referencedBy(target: Schema.Schema.All | string, key: string): Query.Any {
+    const dxn = getTypeDXNFromSpecifier(target);
     return new QueryClass({
       type: 'incoming-references',
       anchor: this.ast,
@@ -600,7 +721,7 @@ class QueryClass implements Query<any> {
     });
   }
 
-  sourceOf(relation: Schema.Schema.All, predicates?: Filter.Props<unknown> | undefined): Query<any> {
+  sourceOf(relation: Schema.Schema.All | string, predicates?: Filter.Props<unknown> | undefined): Query.Any {
     return new QueryClass({
       type: 'relation',
       anchor: this.ast,
@@ -609,7 +730,7 @@ class QueryClass implements Query<any> {
     });
   }
 
-  targetOf(relation: Schema.Schema.All, predicates?: Filter.Props<unknown> | undefined): Query<any> {
+  targetOf(relation: Schema.Schema.All | string, predicates?: Filter.Props<unknown> | undefined): Query.Any {
     return new QueryClass({
       type: 'relation',
       anchor: this.ast,
@@ -618,7 +739,7 @@ class QueryClass implements Query<any> {
     });
   }
 
-  source(): Query<any> {
+  source(): Query.Any {
     return new QueryClass({
       type: 'relation-traversal',
       anchor: this.ast,
@@ -626,7 +747,7 @@ class QueryClass implements Query<any> {
     });
   }
 
-  target(): Query<any> {
+  target(): Query.Any {
     return new QueryClass({
       type: 'relation-traversal',
       anchor: this.ast,
@@ -634,7 +755,15 @@ class QueryClass implements Query<any> {
     });
   }
 
-  options(options: QueryAST.QueryOptions): 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',
       query: this.ast,
@@ -644,3 +773,17 @@ class QueryClass implements Query<any> {
 }
 
 export const Query: QueryAPI = QueryClass;
+
+/**
+ * @param input schema or a typename string
+ * @return type DXN
+ */
+const getTypeDXNFromSpecifier = (input: Schema.Schema.All | string): DXN => {
+  if (Schema.isSchema(input)) {
+    return getTypeReference(input)?.toDXN() ?? raise(new TypeError('Schema has no DXN'));
+  } else {
+    assertArgument(typeof input === 'string', 'input');
+    assertArgument(!input.startsWith('dxn:'), 'input');
+    return DXN.fromTypename(input);
+  }
+};

package/src/test/api.test.ts

@@ -2,13 +2,13 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Schema } from 'effect';
+import * as Schema from 'effect/Schema';
 import { describe, test } from 'vitest';
 
 import { raise } from '@dxos/debug';
-import { FormatEnum, FormatAnnotation } from '@dxos/echo-schema';
+import { FormatAnnotation, FormatEnum } from '@dxos/echo/internal';
 
-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,22 +151,29 @@ 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;
+    const any: Obj.Any | Relation.Any = null as any;
 
     {
-      if (Obj.isObject(a)) {
-        a;
+      if (Obj.isObject(any)) {
+        any;
       } else {
-        a;
+        any;
       }
     }
 
     {
-      if (Relation.isRelation(a)) {
-        a;
+      if (Relation.isRelation(any)) {
+        any;
       } else {
-        a;
+        any;
       }
     }
   });

package/src/testing/echo-schema.ts

@@ -0,0 +1,39 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { effect } from '@preact/signals-core';
+import type * as Schema from 'effect/Schema';
+
+import { registerSignalsRuntime } from '@dxos/echo-signals';
+import { assertArgument } from '@dxos/invariant';
+
+import { EchoSchema, StoredSchema, getSchemaTypename, live, toJsonSchema } from '../internal';
+
+// NOTE: Registration is done here is this is the module that calls out to `effect`.
+registerSignalsRuntime();
+
+/**
+ * Create a reactive mutable schema that updates when the JSON schema is updated.
+ */
+// TODO(dmaretskyi): Should be replaced by registration of typed object.
+export const createEchoSchema = (schema: Schema.Schema.AnyNoContext): EchoSchema => {
+  const typename = getSchemaTypename(schema);
+  assertArgument(typename, 'typename', 'Schema does not have a typename.');
+
+  const echoSchema = new EchoSchema(
+    live(StoredSchema, {
+      typename,
+      version: '0.1.0',
+      jsonSchema: toJsonSchema(schema),
+    }),
+  );
+
+  // TODO(burdon): Unsubscribe is never called.
+  effect(() => {
+    const _ = echoSchema.jsonSchema;
+    echoSchema._invalidate();
+  });
+
+  return echoSchema;
+};

package/src/testing/index.ts

@@ -2,4 +2,6 @@
 // Copyright 2025 DXOS.org
 //
 
+export { prepareAstForCompare, Testing as TestingDeprecated, updateCounter } from '../internal/testing';
 export * from './types';
+export * from './echo-schema';