@dxos/echo 0.8.4-main.7ace549 → 0.8.4-main.937b3ca

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

@@ -7,14 +7,12 @@ import type * as Schema from 'effect/Schema';
 
 import { type QueryAST } from '@dxos/echo-protocol';
 
-import type * as Ref from '../Ref';
-import type * as Type from '../Type';
+import * as Filter from './Filter';
+import { getTypeDXNFromSpecifier } from './internal';
+import type * as Order from './Order';
+import type * as Ref from './Ref';
+import type * as Type$ from './Type';
 
-import { Filter, FilterClass } from './filter';
-import { type Order } from './order';
-import { getTypeDXNFromSpecifier } from './util';
-
-// TODO(burdon): Query namespace (and move Filter, Order into Query namespace).
 // 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.
@@ -37,7 +35,7 @@ export interface Query<T> {
    * @param filter - Filter to select the objects.
    * @returns Query for the selected objects.
    */
-  select(filter: Filter<T>): Query<T>;
+  select(filter: Filter.Filter<T>): Query<T>;
   select(props: Filter.Props<T>): Query<T>;
 
   /**
@@ -48,17 +46,17 @@ export interface Query<T> {
   reference<K extends RefPropKey<T>>(
     key: K,
   ): Query<
-    T[K] extends Ref.Any
+    T[K] extends Ref.Unknown
       ? Ref.Target<T[K]>
-      : T[K] extends Ref.Any | undefined
+      : T[K] extends Ref.Unknown | undefined
         ? Ref.Target<Exclude<T[K], undefined>>
         : never
   >;
 
   /**
    * Find objects referencing this object.
-   * @param target - Schema of the referencing object.
-   * @param key - Property path inside the referencing object that is a reference.
+   * @param target - Schema of the referencing object. If not provided, matches any type.
+   * @param key - Property path inside the referencing object that is a reference. If not provided, matches any property.
    * @returns Query for the referencing objects.
    */
   // TODO(dmaretskyi): any way to enforce `Ref.Target<Schema.Schema.Type<S>[key]> == T`?
@@ -67,6 +65,8 @@ export interface Query<T> {
     target: S | string,
     key: RefPropKey<Schema.Schema.Type<S>>,
   ): Query<Schema.Schema.Type<S>>;
+  referencedBy<S extends Schema.Schema.All>(target: S | string): Query<Schema.Schema.Type<S>>;
+  referencedBy(): Query<any>;
 
   /**
    * Find relations where this object is the source.
@@ -94,13 +94,13 @@ export interface Query<T> {
    * For a query for relations, get the source objects.
    * @returns Query for the source objects.
    */
-  source(): Query<Type.Relation.Source<T>>;
+  source(): Query<Type$.Relation.Source<T>>;
 
   /**
    * For a query for relations, get the target objects.
    * @returns Query for the target objects.
    */
-  target(): Query<Type.Relation.Target<T>>;
+  target(): Query<Type$.Relation.Target<T>>;
 
   /**
    * Order the query results.
@@ -108,114 +108,33 @@ export interface Query<T> {
    * @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.
-   */
-  options(options: QueryAST.QueryOptions): 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.
-   * @returns Query for the selected objects.
-   */
-  select<F extends Filter.Any>(filter: F): Query<Filter.Type<F>>;
-
-  /**
-   * Query for objects of a given schema.
-   * @param schema - Schema of the objects.
-   * @param predicates - Predicates to filter the objects.
-   * @returns Query for the objects.
-   *
-   * Shorthand for: `Query.select(Filter.type(schema, predicates))`.
-   */
-  type<S extends Schema.Schema.All>(
-    schema: S | string,
-    predicates?: Filter.Props<Schema.Schema.Type<S>>,
-  ): Query<Schema.Schema.Type<S>>;
+  orderBy(...order: EffectArray.NonEmptyArray<Order.Order<T>>): Query<T>;
 
   /**
-   * Combine results of multiple queries.
-   * @param queries - Queries to combine.
-   * @returns Query for the combined results.
+   * Limit the number of results.
+   * @param limit - Maximum number of results to return.
+   * @returns Query for the limited results.
    */
-  // TODO(dmaretskyi): Rename to `combine` or `union`.
-  all<T>(...queries: Query<T>[]): Query<T>;
+  limit(limit: number): Query<T>;
 
   /**
-   * Subtract one query from another.
-   * @param source - Query to subtract from.
-   * @param exclude - Query to subtract.
-   * @returns Query for the results of the source query minus the results of the exclude query.
+   * Add options to a query.
    */
-  without<T>(source: Query<T>, exclude: Query<T>): Query<T>;
-}
-
-export declare namespace Query {
-  export type Any = Query<any>;
-
-  export type Type<Q extends Any> = Q extends Query<infer T> ? T : never;
+  options(options: QueryAST.QueryOptions): Query<T>;
 }
 
-// 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'];
+export type Any = Query<any>;
 
-  static is(value: unknown): value is Query<any> {
-    return typeof value === 'object' && value !== null && '~Query' in value;
-  }
-
-  static fromAst(ast: QueryAST.Query): Query<any> {
-    return new QueryClass(ast);
-  }
+export type Type<Q extends Any> = Q extends Query<infer T> ? T : never;
 
-  static select<F extends Filter.Any>(filter: F): Query<Filter.Type<F>> {
-    return new QueryClass({
-      type: 'select',
-      filter: filter.ast,
-    });
-  }
-
-  static type(schema: Schema.Schema.All | string, predicates?: Filter.Props<unknown>): Query<any> {
-    return new QueryClass({
-      type: 'select',
-      filter: FilterClass.type(schema, predicates).ast,
-    });
-  }
-
-  static all(...queries: Query<any>[]): Query<any> {
-    if (queries.length === 0) {
-      throw new TypeError(
-        'Query.all combines results of multiple queries, to query all objects use Query.select(Filter.everything())',
-      );
-    }
-    return new QueryClass({
-      type: 'union',
-      queries: queries.map((q) => q.ast),
-    });
-  }
-
-  static without<T>(source: Query<T>, exclude: Query<T>): Query<T> {
-    return new QueryClass({
-      type: 'set-difference',
-      source: source.ast,
-      exclude: exclude.ast,
-    });
-  }
+class QueryClass implements Any {
+  private static variance: Any['~Query'] = {} as Any['~Query'];
 
   constructor(public readonly ast: QueryAST.Query) {}
 
   '~Query' = QueryClass.variance;
 
-  select(filter: Filter.Any | Filter.Props<any>): Query.Any {
+  select(filter: Filter.Any | Filter.Props<any>): Any {
     if (Filter.is(filter)) {
       return new QueryClass({
         type: 'filter',
@@ -226,12 +145,12 @@ class QueryClass implements Query<any> {
       return new QueryClass({
         type: 'filter',
         selection: this.ast,
-        filter: FilterClass.props(filter).ast,
+        filter: Filter.props(filter).ast,
       });
     }
   }
 
-  reference(key: string): Query.Any {
+  reference(key: string): Any {
     return new QueryClass({
       type: 'reference-traversal',
       anchor: this.ast,
@@ -239,35 +158,35 @@ class QueryClass implements Query<any> {
     });
   }
 
-  referencedBy(target: Schema.Schema.All | string, key: string): Query.Any {
-    const dxn = getTypeDXNFromSpecifier(target);
+  referencedBy(target?: Schema.Schema.All | string, key?: string): Any {
+    const dxn = target !== undefined ? getTypeDXNFromSpecifier(target) : null;
     return new QueryClass({
       type: 'incoming-references',
       anchor: this.ast,
-      property: key,
-      typename: dxn.toString(),
+      property: key ?? null,
+      typename: dxn?.toString() ?? null,
     });
   }
 
-  sourceOf(relation: Schema.Schema.All | string, predicates?: Filter.Props<unknown> | undefined): Query.Any {
+  sourceOf(relation: Schema.Schema.All | string, predicates?: Filter.Props<unknown> | undefined): Any {
     return new QueryClass({
       type: 'relation',
       anchor: this.ast,
       direction: 'outgoing',
-      filter: FilterClass.type(relation, predicates).ast,
+      filter: Filter.type(relation, predicates).ast,
     });
   }
 
-  targetOf(relation: Schema.Schema.All | string, predicates?: Filter.Props<unknown> | undefined): Query.Any {
+  targetOf(relation: Schema.Schema.All | string, predicates?: Filter.Props<unknown> | undefined): Any {
     return new QueryClass({
       type: 'relation',
       anchor: this.ast,
       direction: 'incoming',
-      filter: FilterClass.type(relation, predicates).ast,
+      filter: Filter.type(relation, predicates).ast,
     });
   }
 
-  source(): Query.Any {
+  source(): Any {
     return new QueryClass({
       type: 'relation-traversal',
       anchor: this.ast,
@@ -275,7 +194,7 @@ class QueryClass implements Query<any> {
     });
   }
 
-  target(): Query.Any {
+  target(): Any {
     return new QueryClass({
       type: 'relation-traversal',
       anchor: this.ast,
@@ -283,7 +202,7 @@ class QueryClass implements Query<any> {
     });
   }
 
-  orderBy(...order: Order<any>[]): Query.Any {
+  orderBy(...order: Order.Order<any>[]): Any {
     return new QueryClass({
       type: 'order',
       query: this.ast,
@@ -291,7 +210,15 @@ class QueryClass implements Query<any> {
     });
   }
 
-  options(options: QueryAST.QueryOptions): Query.Any {
+  limit(limit: number): Any {
+    return new QueryClass({
+      type: 'limit',
+      query: this.ast,
+      limit,
+    });
+  }
+
+  options(options: QueryAST.QueryOptions): Any {
     return new QueryClass({
       type: 'options',
       query: this.ast,
@@ -300,4 +227,70 @@ class QueryClass implements Query<any> {
   }
 }
 
-export const Query: QueryAPI = QueryClass;
+export const is = (value: unknown): value is Any => {
+  return typeof value === 'object' && value !== null && '~Query' in value;
+};
+
+/** Construct a query from an ast. */
+export const fromAst = (ast: QueryAST.Query): Any => {
+  return new QueryClass(ast);
+};
+
+/**
+ * Select objects based on a filter.
+ * @param filter - Filter to select the objects.
+ * @returns Query for the selected objects.
+ */
+export const select = <F extends Filter.Any>(filter: F): Query<Filter.Type<F>> => {
+  return new QueryClass({
+    type: 'select',
+    filter: filter.ast,
+  });
+};
+
+/**
+ * Query for objects of a given schema.
+ * @param schema - Schema of the objects.
+ * @param predicates - Predicates to filter the objects.
+ * @returns Query for the objects.
+ *
+ * Shorthand for: `Query.select(Filter.type(schema, predicates))`.
+ */
+export const type = (schema: Schema.Schema.All | string, predicates?: Filter.Props<unknown>): Any => {
+  return new QueryClass({
+    type: 'select',
+    filter: Filter.type(schema, predicates).ast,
+  });
+};
+
+/**
+ * Combine results of multiple queries.
+ * @param queries - Queries to combine.
+ * @returns Query for the combined results.
+ */
+// TODO(dmaretskyi): Rename to `combine` or `union`.
+export const all = (...queries: Any[]): Any => {
+  if (queries.length === 0) {
+    throw new TypeError(
+      'Query.all combines results of multiple queries, to query all objects use Query.select(Filter.everything())',
+    );
+  }
+  return new QueryClass({
+    type: 'union',
+    queries: queries.map((q) => q.ast),
+  });
+};
+
+/**
+ * Subtract one query from another.
+ * @param source - Query to subtract from.
+ * @param exclude - Query to subtract.
+ * @returns Query for the results of the source query minus the results of the exclude query.
+ */
+export const without = <T>(source: Query<T>, exclude: Query<T>): Query<T> => {
+  return new QueryClass({
+    type: 'set-difference',
+    source: source.ast,
+    exclude: exclude.ast,
+  });
+};

package/src/QueryResult.ts

@@ -0,0 +1,106 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type CleanupFn } from '@dxos/async';
+
+import type * as Entity from './Entity';
+
+/**
+ * Individual query result entry.
+ */
+export type Entry<T> = {
+  id: string;
+
+  /**
+   * May not be present for remote results.
+   */
+  result?: T;
+
+  match?: {
+    // TODO(dmaretskyi): text positional info.
+
+    /**
+     * Higher means better match.
+     */
+    rank: number;
+  };
+
+  /**
+   * Query resolution metadata.
+   */
+  // TODO(dmaretskyi): Rename to meta?
+  resolution?: {
+    // TODO(dmaretskyi): Make this more generic.
+    source: 'remote' | 'local' | 'index';
+
+    /**
+     * Query resolution time in milliseconds.
+     */
+    time: number;
+  };
+};
+
+/**
+ * Invidual query result entry for a database Entity.
+ */
+export type EntityEntry<T extends Entity.Unknown = Entity.Unknown> = Entry<T>;
+
+export type RunOptions = {
+  timeout?: number;
+};
+
+export type SubscriptionOptions = {
+  /**
+   * Fire the callback immediately.
+   */
+  fire?: boolean;
+};
+
+// TODO(burdon): Should T be constrained to Entity.Any?
+export interface QueryResult<T> {
+  /**
+   * Currently available results along with their match metadata.
+   */
+  readonly entries: Entry<T>[];
+
+  /**
+   * Currently available results.
+   */
+  readonly results: T[];
+
+  /**
+   * Returns all known results.
+   */
+  run(opts?: RunOptions): Promise<T[]>;
+
+  /**
+   * Returns all known results along with their match metadata.
+   */
+  runEntries(opts?: RunOptions): Promise<Entry<T>[]>;
+
+  /**
+   * Returns currently available results synchronously.
+   */
+  runSync(): T[];
+
+  /**
+   * Returns currently available results synchronously along with their match metadata.
+   */
+  runSyncEntries(): Entry<T>[];
+
+  /**
+   * Returns first result.
+   */
+  first(opts?: RunOptions): Promise<T>;
+
+  /**
+   * Returns first result if there is one.
+   */
+  firstOrUndefined(opts?: RunOptions): Promise<T | undefined>;
+
+  /**
+   * Subscribes to changes in query results.
+   */
+  subscribe(callback?: (query: QueryResult<T>) => void, opts?: SubscriptionOptions): CleanupFn;
+}

package/src/Ref.ts

@@ -2,27 +2,44 @@
 // Copyright 2025 DXOS.org
 //
 
+import * as Option from 'effect/Option';
+import * as SchemaAST from 'effect/SchemaAST';
+
 import { Ref as Ref$, RefArray, type RefResolver } from './internal';
+import { getSchemaReference } from './internal';
+import type * as JsonSchema from './JsonSchema';
 import type * as Obj from './Obj';
 
 export type Ref<T> = Ref$<T>;
-export type Any = Ref$<Obj.Any>;
+export type Unknown = Ref$<Obj.Unknown>;
 
 export const Array = RefArray;
 
 /**
  * Extract reference target.
  */
-export type Target<R extends Any> = R extends Ref$<infer T> ? T : never;
+export type Target<R extends Unknown> = R extends Ref$<infer T> ? T : never;
 
 /**
  * Reference resolver.
  */
 export type Resolver = RefResolver;
 
-export const isRef: (value: unknown) => value is Any = Ref$.isRef;
+export const isRef: (value: unknown) => value is Unknown = Ref$.isRef;
 
 export const make = Ref$.make;
 
 // TODO(dmaretskyi): Consider just allowing `make` to accept DXN.
 export const fromDXN = Ref$.fromDXN;
+
+// TODO(wittjosiah): Factor out?
+export const isRefType = (ast: SchemaAST.AST): boolean => {
+  return SchemaAST.getAnnotation<JsonSchema.JsonSchema>(ast, SchemaAST.JSONSchemaAnnotationId).pipe(
+    Option.flatMap((jsonSchema) => ('$id' in jsonSchema ? Option.some(jsonSchema) : Option.none())),
+    Option.flatMap((jsonSchema) => {
+      const { typename } = getSchemaReference(jsonSchema) ?? {};
+      return typename ? Option.some(true) : Option.some(false);
+    }),
+    Option.getOrElse(() => false),
+  );
+};

package/src/Relation.test.ts

@@ -0,0 +1,82 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import * as Entity from './Entity';
+import { SnapshotKindId } from './internal';
+import * as Obj from './Obj';
+import * as Relation from './Relation';
+import { TestSchema } from './testing';
+
+describe('Relation', () => {
+  describe('Snapshot', () => {
+    test('getSnapshot returns an immutable snapshot with SnapshotKindId', ({ expect }) => {
+      const obj1 = Obj.make(TestSchema.Person, { name: 'Alice' });
+      const obj2 = Obj.make(TestSchema.Person, { name: 'Bob' });
+      const rel = Relation.make(TestSchema.HasManager, {
+        [Relation.Source]: obj1,
+        [Relation.Target]: obj2,
+      });
+      const snapshot = Relation.getSnapshot(rel);
+
+      // Snapshot has SnapshotKindId, not KindId.
+      expect(snapshot[SnapshotKindId]).toBe(Entity.Kind.Relation);
+      expect((snapshot as any)[Entity.KindId]).toBeUndefined();
+
+      // Snapshot has same id.
+      expect(snapshot.id).toBe(rel.id);
+    });
+
+    test('read-only helpers work with both reactive and snapshot', ({ expect }) => {
+      const obj1 = Obj.make(TestSchema.Person, { name: 'Alice' });
+      const obj2 = Obj.make(TestSchema.Person, { name: 'Bob' });
+      const rel = Relation.make(TestSchema.HasManager, {
+        [Relation.Source]: obj1,
+        [Relation.Target]: obj2,
+      });
+      const snapshot = Relation.getSnapshot(rel);
+
+      // getSourceDXN - works with both.
+      expect(Relation.getSourceDXN(rel)).toBeDefined();
+      expect(Relation.getSourceDXN(snapshot)).toBeDefined();
+
+      // getTargetDXN - works with both.
+      expect(Relation.getTargetDXN(rel)).toBeDefined();
+      expect(Relation.getTargetDXN(snapshot)).toBeDefined();
+
+      // getSource - works with both.
+      expect(Relation.getSource(rel)).toBeDefined();
+      expect(Relation.getSource(snapshot)).toBeDefined();
+
+      // getTarget - works with both.
+      expect(Relation.getTarget(rel)).toBeDefined();
+      expect(Relation.getTarget(snapshot)).toBeDefined();
+
+      // getDXN - works with both.
+      expect(Relation.getDXN(rel)).toBeDefined();
+      expect(Relation.getDXN(snapshot)).toBeDefined();
+
+      // getTypename - works with both.
+      expect(Relation.getTypename(rel)).toBe('example.com/type/HasManager');
+      expect(Relation.getTypename(snapshot)).toBe('example.com/type/HasManager');
+
+      // getMeta - works with both.
+      expect(Relation.getMeta(rel)).toBeDefined();
+      expect(Relation.getMeta(snapshot)).toBeDefined();
+
+      // isDeleted - works with both.
+      expect(Relation.isDeleted(rel)).toBe(false);
+      expect(Relation.isDeleted(snapshot)).toBe(false);
+
+      // version - works with both.
+      expect(Relation.version(rel)).toBeDefined();
+      expect(Relation.version(snapshot)).toBeDefined();
+
+      // toJSON - works with both.
+      expect(Relation.toJSON(rel)).toBeDefined();
+      expect(Relation.toJSON(snapshot)).toBeDefined();
+    });
+  });
+});