@dxos/echo 0.8.4-main.84f28bd → 0.8.4-main.937b3ca

package/src/Query.ts

@@ -0,0 +1,296 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type * as EffectArray from 'effect/Array';
+import type * as Schema from 'effect/Schema';
+
+import { type QueryAST } from '@dxos/echo-protocol';
+
+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';
+
+// 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.
+
+/**
+ * All property paths inside T that are references.
+ */
+// TODO(dmaretskyi): Filter only properties that are references (or optional references, or unions that include references).
+type RefPropKey<T> = keyof T & string;
+
+// TODO(burdon): Narrow T to Entity.Unknown?
+export interface Query<T> {
+  // TODO(dmaretskyi): See new effect-schema approach to variance.
+  '~Query': { value: T };
+
+  ast: QueryAST.Query;
+
+  /**
+   * Filter the current selection based on a filter.
+   * @param filter - Filter to select the objects.
+   * @returns Query for the selected objects.
+   */
+  select(filter: Filter.Filter<T>): Query<T>;
+  select(props: Filter.Props<T>): Query<T>;
+
+  /**
+   * Traverse an outgoing 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.Unknown
+      ? Ref.Target<T[K]>
+      : 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. 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`?
+  // TODO(dmaretskyi): Ability to go through arrays of references.
+  referencedBy<S extends Schema.Schema.All>(
+    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.
+   * @returns Query for the relation objects.
+   * @param relation - Schema of the relation.
+   * @param predicates - Predicates to filter the relation objects.
+   */
+  sourceOf<S extends Schema.Schema.All>(
+    relation: S | string,
+    predicates?: Filter.Props<Schema.Schema.Type<S>>,
+  ): Query<Schema.Schema.Type<S>>;
+
+  /**
+   * Find relations where this object is the target.
+   * @returns Query for the relation objects.
+   * @param relation - Schema of the relation.
+   * @param predicates - Predicates to filter the relation objects.
+   */
+  targetOf<S extends Schema.Schema.All>(
+    relation: S | string,
+    predicates?: Filter.Props<Schema.Schema.Type<S>>,
+  ): Query<Schema.Schema.Type<S>>;
+
+  /**
+   * For a query for relations, get the source objects.
+   * @returns Query for the source objects.
+   */
+  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>>;
+
+  /**
+   * 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.Order<T>>): Query<T>;
+
+  /**
+   * Limit the number of results.
+   * @param limit - Maximum number of results to return.
+   * @returns Query for the limited results.
+   */
+  limit(limit: number): Query<T>;
+
+  /**
+   * Add options to a query.
+   */
+  options(options: QueryAST.QueryOptions): Query<T>;
+}
+
+export type Any = Query<any>;
+
+export type Type<Q extends Any> = Q extends Query<infer T> ? T : never;
+
+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>): Any {
+    if (Filter.is(filter)) {
+      return new QueryClass({
+        type: 'filter',
+        selection: this.ast,
+        filter: filter.ast,
+      });
+    } else {
+      return new QueryClass({
+        type: 'filter',
+        selection: this.ast,
+        filter: Filter.props(filter).ast,
+      });
+    }
+  }
+
+  reference(key: string): Any {
+    return new QueryClass({
+      type: 'reference-traversal',
+      anchor: this.ast,
+      property: key,
+    });
+  }
+
+  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 ?? null,
+      typename: dxn?.toString() ?? null,
+    });
+  }
+
+  sourceOf(relation: Schema.Schema.All | string, predicates?: Filter.Props<unknown> | undefined): Any {
+    return new QueryClass({
+      type: 'relation',
+      anchor: this.ast,
+      direction: 'outgoing',
+      filter: Filter.type(relation, predicates).ast,
+    });
+  }
+
+  targetOf(relation: Schema.Schema.All | string, predicates?: Filter.Props<unknown> | undefined): Any {
+    return new QueryClass({
+      type: 'relation',
+      anchor: this.ast,
+      direction: 'incoming',
+      filter: Filter.type(relation, predicates).ast,
+    });
+  }
+
+  source(): Any {
+    return new QueryClass({
+      type: 'relation-traversal',
+      anchor: this.ast,
+      direction: 'source',
+    });
+  }
+
+  target(): Any {
+    return new QueryClass({
+      type: 'relation-traversal',
+      anchor: this.ast,
+      direction: 'target',
+    });
+  }
+
+  orderBy(...order: Order.Order<any>[]): Any {
+    return new QueryClass({
+      type: 'order',
+      query: this.ast,
+      order: order.map((o) => o.ast),
+    });
+  }
+
+  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,
+      options,
+    });
+  }
+}
+
+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,28 +2,44 @@
 // Copyright 2025 DXOS.org
 //
 
-import * as EchoSchema from '@dxos/echo-schema';
+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> = EchoSchema.Ref<T>;
-export type Any = EchoSchema.Ref<Obj.Any>;
+export type Ref<T> = Ref$<T>;
+export type Unknown = Ref$<Obj.Unknown>;
 
-export const Array = EchoSchema.RefArray;
+export const Array = RefArray;
 
 /**
  * Extract reference target.
  */
-export type Target<R extends Any> = R extends EchoSchema.Ref<infer T> ? T : never;
+export type Target<R extends Unknown> = R extends Ref$<infer T> ? T : never;
 
 /**
  * Reference resolver.
  */
-export type Resolver = EchoSchema.RefResolver;
+export type Resolver = RefResolver;
 
-export const isRef: (value: unknown) => value is Any = EchoSchema.Ref.isRef;
+export const isRef: (value: unknown) => value is Unknown = Ref$.isRef;
 
-export const make = EchoSchema.Ref.make;
+export const make = Ref$.make;
 
 // TODO(dmaretskyi): Consider just allowing `make` to accept DXN.
-export const fromDXN = EchoSchema.Ref.fromDXN;
+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();
+    });
+  });
+});