@dxos/echo 0.8.4-main.e098934 → 0.8.4-main.e8ec1fe

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

@@ -2,16 +2,18 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Match, Schema } from 'effect';
-import type { NonEmptyArray } from 'effect/Array';
-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';
 
@@ -86,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>>;
 
@@ -97,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>>;
 
@@ -108,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>>;
 
@@ -130,7 +132,7 @@ export interface Query<T> {
    * @param order - Order to sort the results.
    * @returns Query for the ordered results.
    */
-  orderBy(...order: NonEmptyArray<Order<T>>): Query<T>;
+  orderBy(...order: EffectArray.NonEmptyArray<Order<T>>): Query<T>;
 
   /**
    * Add options to a query.
@@ -160,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>>;
 
@@ -194,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;
 }
@@ -204,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.
@@ -306,14 +316,14 @@ interface FilterAPI {
    * Predicate for an array property to contain the provided value.
    * @param value - Value to check against.
    */
-  contains<T>(value: T): Filter<T[]>;
+  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.
@@ -343,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'];
 
@@ -355,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',
@@ -402,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(),
@@ -430,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,
@@ -449,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(),
@@ -518,14 +540,14 @@ class FilterClass implements Filter<any> {
     });
   }
 
-  static contains<T>(value: 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<T> {
+  static between<T>(from: T, to: T): Filter<unknown> {
     return new FilterClass({
       type: 'range',
       from,
@@ -615,6 +637,7 @@ const processPredicate = (predicate: any): QueryAST.Filter => {
   );
 };
 
+// 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'];
 
@@ -633,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,
@@ -664,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',
@@ -675,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,
@@ -688,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,
@@ -698,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,
@@ -707,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,
@@ -716,7 +739,7 @@ class QueryClass implements Query<any> {
     });
   }
 
-  source(): Query<any> {
+  source(): Query.Any {
     return new QueryClass({
       type: 'relation-traversal',
       anchor: this.ast,
@@ -724,7 +747,7 @@ class QueryClass implements Query<any> {
     });
   }
 
-  target(): Query<any> {
+  target(): Query.Any {
     return new QueryClass({
       type: 'relation-traversal',
       anchor: this.ast,
@@ -732,7 +755,7 @@ class QueryClass implements Query<any> {
     });
   }
 
-  orderBy(...order: Order<any>[]): Query<any> {
+  orderBy(...order: Order<any>[]): Query.Any {
     return new QueryClass({
       type: 'order',
       query: this.ast,
@@ -740,7 +763,7 @@ class QueryClass implements Query<any> {
     });
   }
 
-  options(options: QueryAST.QueryOptions): Query<any> {
+  options(options: QueryAST.QueryOptions): Query.Any {
     return new QueryClass({
       type: 'options',
       query: this.ast,
@@ -750,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,11 +2,11 @@
 // 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 { FormatAnnotation, FormatEnum } from '@dxos/echo-schema';
+import { FormatAnnotation, FormatEnum } from '@dxos/echo/internal';
 
 import { type Live, Obj, Ref, Relation, Type } from '../index';
 
@@ -159,21 +159,21 @@ describe('Experimental API review', () => {
   });
 
   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,13 +2,16 @@
 // Copyright 2024 DXOS.org
 //
 
-import { Schema } from 'effect';
+import * as Schema from 'effect/Schema';
 
 import { Type } from '..';
 
-// TODO(burdon): These are non-canonical test types, so we really shouldn't export and use in other classes (compare with @dxos/sdk/testing).
+/**
+ * @deprecated
+ */
+// TOOD(burdon): Reconcile with @dxos/schema.
 export namespace Testing {
-  const _Contact = Schema.Struct({
+  export const Person = Schema.Struct({
     name: Schema.String,
     username: Schema.String,
     email: Schema.String,
@@ -25,17 +28,17 @@ export namespace Testing {
   }).pipe(
     Schema.partial,
     Type.Obj({
-      typename: 'example.com/type/Contact',
+      typename: 'example.com/type/Person',
       version: '0.1.0',
     }),
   );
-  export interface Contact extends Schema.Schema.Type<typeof _Contact> {}
-  export const Contact: Schema.Schema<Contact, Schema.Schema.Encoded<typeof _Contact>, never> = _Contact;
 
-  const _Task = Schema.Struct({
+  export interface Person extends Schema.Schema.Type<typeof Person> {}
+
+  export const Task = Schema.Struct({
     title: Schema.optional(Schema.String),
     completed: Schema.optional(Schema.Boolean),
-    assignee: Schema.optional(Type.Ref(Contact)),
+    assignee: Schema.optional(Type.Ref(Person)),
     previous: Schema.optional(Schema.suspend((): Type.Ref<Task> => Type.Ref(Task))),
     subTasks: Schema.optional(Schema.mutable(Schema.Array(Schema.suspend((): Type.Ref<Task> => Type.Ref(Task))))),
     description: Schema.optional(Schema.String),
@@ -46,8 +49,34 @@ export namespace Testing {
       version: '0.1.0',
     }),
   );
-  export interface Task extends Schema.Schema.Type<typeof _Task> {}
-  export const Task: Schema.Schema<Task, Schema.Schema.Encoded<typeof _Task>, never> = _Task;
+
+  export interface Task extends Schema.Schema.Type<typeof Task> {}
+
+  export const WorksFor = Schema.Struct({
+    since: Schema.optional(Schema.String),
+  }).pipe(
+    Type.Relation({
+      typename: 'example.com/type/WorksFor',
+      version: '0.1.0',
+      source: Person,
+      target: Person,
+    }),
+  );
+
+  export interface WorksFor extends Schema.Schema.Type<typeof WorksFor> {}
+
+  export const HasManager = Schema.Struct({
+    since: Schema.optional(Schema.String),
+  }).pipe(
+    Type.Relation({
+      typename: 'example.com/type/HasManager',
+      version: '0.1.0',
+      source: Person,
+      target: Person,
+    }),
+  );
+
+  export interface HasManager extends Schema.Schema.Type<typeof HasManager> {}
 
   export enum RecordType {
     UNDEFINED = 0,
@@ -63,7 +92,7 @@ export namespace Testing {
           Schema.Struct({
             title: Schema.String,
             description: Schema.String,
-            contacts: Schema.mutable(Schema.Array(Type.Ref(Contact))),
+            contacts: Schema.mutable(Schema.Array(Type.Ref(Person))),
             type: Schema.Enums(RecordType),
           }),
         ),
@@ -76,16 +105,4 @@ export namespace Testing {
       version: '0.1.0',
     }),
   );
-
-  export const WorksFor = Schema.Struct({
-    since: Schema.optional(Schema.String),
-  }).pipe(
-    Type.Relation({
-      typename: 'example.com/type/WorksFor',
-      version: '0.1.0',
-      source: Contact,
-      target: Contact,
-    }),
-  );
-  export interface WorksFor extends Schema.Schema.Type<typeof WorksFor> {}
 }