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

package/src/Query.ts

@@ -0,0 +1,567 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+import type * as EffectArray from 'effect/Array';
+import type * as Schema from 'effect/Schema';
+
+import { type QueryAST } from '@dxos/echo-protocol';
+
+import type * as Collection from './Collection';
+import * as Database from './Database';
+import type * as Dataset from './Dataset';
+import * as Feed from './Feed';
+import * as Filter from './Filter';
+import * as internal from './internal';
+import * as Obj from './Obj';
+import type * as Order from './Order';
+import type * as Ref from './Ref';
+import type * as Relation from './Relation';
+import type * as View from './View';
+
+// 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<Relation.SourceOf<T>>;
+
+  /**
+   * For a query for relations, get the target objects.
+   * @returns Query for the target objects.
+   */
+  'target'(): Query<Relation.TargetOf<T>>;
+
+  /**
+   * Get the parent object of the current selection.
+   * @returns Query for the parent objects.
+   */
+  'parent'(): Query<any>;
+
+  /**
+   * Get all child objects of the current selection.
+   * @returns Query for the child objects.
+   */
+  'children'(): Query<any>;
+
+  /**
+   * 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>;
+
+  /**
+   * Query from selected databases only.
+   *
+   * Example:
+   *
+   * ```ts
+   * Query.select(Filter.type(Person)).from(db);
+   * ```
+   *
+   * @param options.includeFeeds [false] - Whether to include feeds in the query. Default is to query from automerge documents only.
+   */
+  'from'(database: Database.Database | Database.Database[], options?: { includeFeeds?: boolean }): Query<T>;
+
+  /**
+   * Query from selected feeds only.
+   *
+   * Example:
+   *
+   * ```ts
+   * Query.select(Filter.type(Person)).from(feed);
+   * ```
+   *
+   */
+  'from'(feeds: Feed.Feed | Feed.Feed[]): Query<T>;
+
+  /**
+   * Query from all accessible spaces.
+   *
+   * Example:
+   *
+   * ```ts
+   * Query.select(Filter.type(Person)).from('all-accessible-spaces');
+   * ```
+   *
+   * @param options.includeFeeds [false] - Whether to include feeds in the query. Default is to query from automerge documents only.
+   */
+  'from'(allSpaces: 'all-accessible-spaces', options?: { includeFeeds?: boolean }): Query<T>;
+
+  /**
+   * Query from a dataset.
+   * Currently only feeds are supported.
+   *
+   * Example:
+   *
+   * ```ts
+   * Query.type(Person).from(feed);
+   * ```
+   */
+  'from'(dataset: Dataset.Dataset): Query<T>;
+
+  /**
+   * Query from the results of another query.
+   *
+   * Example:
+   *
+   * ```ts
+   * Query.select(Filter.props({ foo: 'foo' })).from(Query.select(Filter.type(Contact)).reference('org'));
+   * ```
+   */
+  'from'(query: Any): Query<T>;
+
+  /**
+   * Query from a raw scope specification.
+   */
+  'from'(scope: QueryAST.Scope): Query<T>;
+
+  /**
+   * Add options to a query.
+   */
+  'options'(options: QueryAST.QueryOptions): Query<T>;
+
+  /**
+   * Attach a diagnostic label for logs and tooling (execution semantics unchanged).
+   */
+  'debugLabel'(label: string): 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 ? internal.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: relation !== undefined ? Filter.type(relation, predicates).ast : undefined,
+    });
+  }
+
+  targetOf(relation?: Schema.Schema.All | string, predicates?: Filter.Props<unknown> | undefined): Any {
+    return new QueryClass({
+      type: 'relation',
+      anchor: this.ast,
+      direction: 'incoming',
+      filter: relation !== undefined ? Filter.type(relation, predicates).ast : undefined,
+    });
+  }
+
+  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',
+    });
+  }
+
+  parent(): Any {
+    return new QueryClass({
+      type: 'hierarchy-traversal',
+      anchor: this.ast,
+      direction: 'to-parent',
+    });
+  }
+
+  children(): Any {
+    return new QueryClass({
+      type: 'hierarchy-traversal',
+      anchor: this.ast,
+      direction: 'to-children',
+    });
+  }
+
+  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,
+    });
+  }
+
+  from(
+    arg:
+      | Database.Database
+      | Database.Database[]
+      | Feed.Feed
+      | Feed.Feed[]
+      | Collection.Collection
+      | View.View
+      | Any
+      | QueryAST.Scope
+      | 'all-accessible-spaces',
+    options?: { includeFeeds?: boolean },
+  ): Any {
+    if (arg == null) {
+      throw new TypeError(
+        'Query.from() requires a valid data source argument (database, feed, query, scope, or "all-accessible-spaces").',
+      );
+    }
+
+    if (is(arg)) {
+      return new QueryClass({
+        type: 'from',
+        query: this.ast,
+        from: { _tag: 'query', query: arg.ast },
+      });
+    }
+
+    if (arg === 'all-accessible-spaces') {
+      return new QueryClass({
+        type: 'from',
+        query: this.ast,
+        from: {
+          _tag: 'scope',
+          scope: {
+            ...(options?.includeFeeds ? { allQueuesFromSpaces: true } : {}),
+          },
+        },
+      });
+    }
+
+    if (_isScope(arg)) {
+      return new QueryClass({
+        type: 'from',
+        query: this.ast,
+        from: { _tag: 'scope', scope: arg },
+      });
+    }
+
+    const items = Array.isArray(arg) ? arg : [arg];
+
+    if (items.length > 0 && Database.isDatabase(items[0])) {
+      const databases = items as Database.Database[];
+      return new QueryClass({
+        type: 'from',
+        query: this.ast,
+        from: {
+          _tag: 'scope',
+          scope: {
+            spaceIds: databases.map((db) => db.spaceId),
+            ...(options?.includeFeeds ? { allQueuesFromSpaces: true } : {}),
+          },
+        },
+      });
+    }
+
+    if (items.length > 0) {
+      const typename = Obj.getTypename(items[0] as Obj.Unknown);
+      // TODO(dmaretskyi): Support querying from views.
+      if (typename === 'org.dxos.type.view') {
+        throw new Error('Query.from(view) is not yet supported.');
+      }
+      // TODO(dmaretskyi): Support querying from collections.
+      if (typename === 'org.dxos.type.collection') {
+        throw new Error('Query.from(collection) is not yet supported.');
+      }
+      // Validate that the items are Feed.Feed instances.
+      for (const item of items) {
+        if (!Obj.instanceOf(Feed.Feed, item)) {
+          throw new TypeError(
+            `Query.from() expects Feed objects (org.dxos.type.feed), but received an object with typename '${typename ?? 'unknown'}'.`,
+          );
+        }
+      }
+    }
+
+    const feeds = items as Feed.Feed[];
+    const queueDxns = feeds.flatMap((feed) => {
+      const dxn = Feed.getQueueDxn(feed);
+      return dxn ? [dxn.toString()] : [];
+    });
+    return new QueryClass({
+      type: 'from',
+      query: this.ast,
+      from: {
+        _tag: 'scope',
+        scope: {
+          queues: queueDxns,
+        },
+      },
+    });
+  }
+
+  options(options: QueryAST.QueryOptions): Any {
+    return new QueryClass({
+      type: 'options',
+      query: this.ast,
+      options,
+    });
+  }
+
+  debugLabel(label: string): Any {
+    if (this.ast.type === 'options') {
+      return new QueryClass({
+        type: 'options',
+        query: this.ast.query,
+        options: { ...this.ast.options, debugLabel: label },
+      });
+    }
+    return new QueryClass({
+      type: 'options',
+      query: this.ast,
+      options: { debugLabel: label },
+    });
+  }
+}
+
+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: {
+  <S extends Schema.Schema.All>(
+    schema: S,
+    predicates?: Filter.Props<Schema.Schema.Type<S>>,
+  ): Query<Schema.Schema.Type<S>>;
+  (schema: string, predicates?: Filter.Props<unknown>): Query<any>;
+} = (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,
+  });
+};
+
+/**
+ * Create a query scoped to a data source.
+ * The returned query selects everything from the source; chain `.select()` to narrow results.
+ *
+ * @param source - Data source: database, feed, 'all-accessible-spaces', or another query.
+ * @returns Query scoped to the given source.
+ */
+export const from = (
+  source:
+    | Database.Database
+    | Database.Database[]
+    | Feed.Feed
+    | Feed.Feed[]
+    | Any
+    | QueryAST.Scope
+    | 'all-accessible-spaces',
+  options?: { includeFeeds?: boolean },
+): Any => {
+  const baseQuery: QueryAST.Query = {
+    type: 'select',
+    filter: Filter.everything().ast,
+  };
+  const wrapper = new QueryClass(baseQuery);
+  return wrapper.from(source as any, options);
+};
+
+const SCOPE_KEYS = new Set(['spaceIds', 'queues', 'allQueuesFromSpaces']);
+
+/** Detect a raw Scope object (plain object with only Scope-valid keys). */
+const _isScope = (value: unknown): value is QueryAST.Scope => {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return false;
+  }
+  return Object.keys(value).every((key) => SCOPE_KEYS.has(key));
+};
+
+/**
+ * Returns a human-readable string representation of a Query AST.
+ */
+export const pretty = (query: Any): string => internal.prettyQuery(query.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;
+}