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

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

@@ -2,21 +2,24 @@
 // Copyright 2025 DXOS.org
 //
 
-import { 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';
 
 // 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.
@@ -63,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.
@@ -77,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>>;
 
@@ -88,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>>;
 
@@ -99,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>>;
 
@@ -121,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.
@@ -151,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>>;
 
@@ -185,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;
 }
@@ -195,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.
@@ -293,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.
@@ -328,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'];
 
@@ -340,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',
@@ -387,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(),
@@ -415,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,
@@ -434,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(),
@@ -503,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,
@@ -562,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'];
 
@@ -585,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,
@@ -616,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',
@@ -627,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,
@@ -640,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,
@@ -650,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,
@@ -659,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,
@@ -668,7 +739,7 @@ class QueryClass implements Query<any> {
     });
   }
 
-  source(): Query<any> {
+  source(): Query.Any {
     return new QueryClass({
       type: 'relation-traversal',
       anchor: this.ast,
@@ -676,7 +747,7 @@ class QueryClass implements Query<any> {
     });
   }
 
-  target(): Query<any> {
+  target(): Query.Any {
     return new QueryClass({
       type: 'relation-traversal',
       anchor: this.ast,
@@ -684,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,
@@ -692,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,
@@ -702,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/query/tag.ts

@@ -0,0 +1,37 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { LabelAnnotation } from '../internal';
+import * as Obj from '../Obj';
+import * as Type from '../Type';
+
+export const Tag = Schema.Struct({
+  label: Schema.String,
+  hue: Schema.optional(Schema.String), // TODO(burdon): Color name?
+}).pipe(
+  Type.Obj({
+    typename: 'dxos.org/type/Tag',
+    version: '0.1.0',
+  }),
+  LabelAnnotation.set(['label']),
+);
+export type Tag = Schema.Schema.Type<typeof Tag>;
+
+export const make = (props: Obj.MakeProps<typeof Tag>) => Obj.make(Tag, props);
+
+export type TagMap = Record<string, Tag>;
+
+export const sortTags = ({ label: a }: Tag, { label: b }: Tag) => a.localeCompare(b);
+
+export const createTagList = (tags: TagMap): Tag[] =>
+  Object.entries(tags)
+    .map(([id, tag]) => ({ ...tag, id }))
+    .sort(sortTags);
+
+export const findTagByLabel = (tags: TagMap | 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,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,7 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
-import { Schema } from 'effect';
+import * as Schema from 'effect/Schema';
 
 import { Type } from '..';