@dxos/echo 0.8.4-main.b97322e → 0.8.4-main.c4373fc

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

@@ -2,20 +2,52 @@
 // 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 { 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 +65,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 +87,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 +98,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 +109,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 +125,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 +142,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 +161,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>>;
 
@@ -156,6 +207,9 @@ type Intersection<Types extends readonly unknown[]> = Types extends [infer First
 interface FilterAPI {
   is(value: unknown): value is Filter<any>;
 
+  /** Construct a filter from an ast. */
+  fromAst(ast: QueryAST.Filter): Filter<any>;
+
   /**
    * Filter that matches all objects.
    */
@@ -176,7 +230,7 @@ interface FilterAPI {
    * 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>>;
 
@@ -190,12 +244,15 @@ interface FilterAPI {
    */
   typeDXN(dxn: DXN): Filter<any>;
 
+  /**
+   * 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,6 +309,12 @@ 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<T[]>;
+
   /**
    * Predicate for property to be in the provided range.
    * @param from - Start of the range (inclusive).
@@ -287,9 +350,9 @@ 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]>;
 }
 
 class FilterClass implements Filter<any> {
@@ -299,6 +362,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 +396,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 +413,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 +425,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 +441,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 +464,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,6 +536,13 @@ class FilterClass implements Filter<any> {
     });
   }
 
+  static contains<T>(value: T): Filter<T[]> {
+    return new FilterClass({
+      type: 'contains',
+      value,
+    });
+  }
+
   static between<T>(from: T, to: T): Filter<T> {
     return new FilterClass({
       type: 'range',
@@ -506,7 +588,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 +602,37 @@ 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),
+  );
+};
+
 class QueryClass implements Query<any> {
   private static variance: Query<any>['~Query'] = {} as Query<any>['~Query'];
 
@@ -528,6 +640,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 +651,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,
@@ -577,7 +693,7 @@ class QueryClass implements Query<any> {
       return new QueryClass({
         type: 'filter',
         selection: this.ast,
-        filter: FilterClass._props(filter).ast,
+        filter: FilterClass.props(filter).ast,
       });
     }
   }
@@ -590,8 +706,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 +716,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 +725,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,
@@ -634,6 +750,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',
@@ -644,3 +768,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/query/tag.ts

@@ -0,0 +1,35 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+export const TagInfo = Schema.Struct({
+  label: Schema.String,
+  hue: Schema.optional(Schema.String), // TODO(burdon): Color name?
+});
+
+export type TagInfo = Schema.Schema.Type<typeof TagInfo>;
+
+export const Tag = Schema.extend(
+  TagInfo,
+  Schema.Struct({
+    id: Schema.String,
+  }),
+);
+
+export type Tag = Schema.Schema.Type<typeof Tag>;
+
+export type TagMap = Record<string, TagInfo>;
+
+export const sortTags = ({ label: a }: TagInfo, { label: b }: TagInfo) => a.localeCompare(b);
+
+export const createTagList = (tags: TagMap): Tag[] =>
+  Object.entries(tags)
+    .map(([id, tag]) => ({ ...tag, id }))
+    .sort(sortTags);
+
+export const findTagByLabel = (tags: Record<string, TagInfo> | undefined, name: string): Tag | undefined => {
+  const entry = Object.entries(tags ?? {}).find(([_, tag]) => tag.label.toLowerCase() === name.toLowerCase());
+  return entry ? { ...entry[1], id: entry[0] } : undefined;
+};

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';

package/src/testing/types.ts

@@ -2,7 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
-import { Schema } from 'effect';
+import * as Schema from 'effect/Schema';
 
 import { Type } from '..';