@dxos/echo 0.8.4-main.5ea62a8 → 0.8.4-main.66e292d

package/src/query/query.test.ts

@@ -0,0 +1,334 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import { describe, expect, test } from 'vitest';
+
+import { QueryAST } from '@dxos/echo-protocol';
+import { DXN } from '@dxos/keys';
+import { log } from '@dxos/log';
+
+import * as Obj from '../Obj';
+import * as Ref from '../Ref';
+
+import { Filter } from './filter';
+import { Order } from './order';
+import { Query } from './query';
+import * as Test from './testing';
+
+describe('query api', () => {
+  describe('Query', () => {
+    test('get all people', () => {
+      const getAllPeople = Query.type(Test.Person);
+
+      log('query', { ast: getAllPeople.ast });
+      Schema.validateSync(QueryAST.Query)(getAllPeople.ast);
+      log('getAllPeople', { ast: getAllPeople.ast });
+    });
+
+    test('get all people ordered by name', () => {
+      const getAllPeopleOrderedByName = Query.type(Test.Person).orderBy(Order.property('name', 'asc'));
+
+      log('query', { ast: getAllPeopleOrderedByName.ast });
+      Schema.validateSync(QueryAST.Query)(getAllPeopleOrderedByName.ast);
+      log('getAllPeopleOrderedByName', { ast: getAllPeopleOrderedByName.ast });
+    });
+
+    test('get all people named Fred', () => {
+      const PeopleNamedFred = Query.select(Filter.type(Test.Person, { name: 'Fred' }));
+
+      log('query', { ast: PeopleNamedFred.ast });
+      Schema.validateSync(QueryAST.Query)(PeopleNamedFred.ast);
+      log('PeopleNamedFred', { ast: PeopleNamedFred.ast });
+    });
+
+    test('get all people with field of "label" set to "Research"', () => {
+      const PeopleWithFieldLabelSetToResearch = Query.select(
+        Filter.type(Test.Person, { fields: Filter.contains({ label: 'label', value: 'Research' }) }),
+      );
+
+      log('query', { ast: PeopleWithFieldLabelSetToResearch.ast });
+      Schema.validateSync(QueryAST.Query)(PeopleWithFieldLabelSetToResearch.ast);
+      log('PeopleWithFieldLabelSetToResearch', { ast: PeopleWithFieldLabelSetToResearch.ast });
+    });
+
+    test('get all orgs with property "label" set to "Research"', () => {
+      const OrgsWithPropertyLabelSetToResearch = Query.select(
+        Filter.type(Test.Organization, { properties: { label: 'Research' } }),
+      );
+
+      log('query', { ast: OrgsWithPropertyLabelSetToResearch.ast });
+      Schema.validateSync(QueryAST.Query)(OrgsWithPropertyLabelSetToResearch.ast);
+      log('OrgsWithPropertyLabelSetToResearch', { ast: OrgsWithPropertyLabelSetToResearch.ast });
+    });
+
+    test('get all orgs Fred worked for since 2020', () => {
+      const fred = Obj.make(Test.Person, { name: 'Fred' });
+      const OrganizationsFredWorkedForSince2020 = Query.select(Filter.type(Test.Person, { id: fred.id }))
+        .sourceOf(Test.WorksFor, { since: Filter.gt('2020') })
+        .target();
+
+      log('query', { ast: OrganizationsFredWorkedForSince2020.ast });
+      Schema.validateSync(QueryAST.Query)(OrganizationsFredWorkedForSince2020.ast);
+      log('OrganizationsFredWorkedForSince2020', { ast: OrganizationsFredWorkedForSince2020.ast });
+    });
+
+    test('get all tasks for Fred', () => {
+      const fred = Obj.make(Test.Person, { name: 'Fred' });
+      const TasksForFred = Query.select(Filter.type(Test.Person, { id: fred.id })).referencedBy(Test.Task, 'assignee');
+
+      log('query', { ast: TasksForFred.ast });
+      Schema.validateSync(QueryAST.Query)(TasksForFred.ast);
+      log('TasksForFred', { ast: TasksForFred.ast });
+    });
+
+    test('get all tasks for employees of Cyberdyne', () => {
+      const TasksForEmployeesOfCyberdyne = Query.select(Filter.type(Test.Organization, { name: 'Cyberdyne' }))
+        .targetOf(Test.WorksFor)
+        .source()
+        .referencedBy(Test.Task, 'assignee');
+
+      log('query', { ast: TasksForEmployeesOfCyberdyne.ast });
+      Schema.validateSync(QueryAST.Query)(TasksForEmployeesOfCyberdyne.ast);
+      log('TasksForEmployeesOfCyberdyne', { ast: TasksForEmployeesOfCyberdyne.ast });
+    });
+
+    test('get all people or orgs', () => {
+      const PeopleOrOrganizations = Query.all(
+        Query.select(Filter.type(Test.Person)),
+        Query.select(Filter.type(Test.Organization)),
+      );
+
+      log('query', { ast: PeopleOrOrganizations.ast });
+      Schema.validateSync(QueryAST.Query)(PeopleOrOrganizations.ast);
+      log('PeopleOrOrganizations', { ast: PeopleOrOrganizations.ast });
+    });
+
+    test('get all people not in orgs', () => {
+      const PeopleNotInOrganizations = Query.without(
+        Query.select(Filter.type(Test.Person)),
+        Query.select(Filter.type(Test.Person)).sourceOf(Test.WorksFor).source(),
+      );
+
+      log('query', { ast: PeopleNotInOrganizations.ast });
+      Schema.validateSync(QueryAST.Query)(PeopleNotInOrganizations.ast);
+      log('PeopleNotInOrganizations', { ast: PeopleNotInOrganizations.ast });
+    });
+
+    test('get assignees of all tasks created after 2020', () => {
+      const AssigneesOfAllTasksCreatedAfter2020 = Query.select(
+        Filter.type(Test.Task, { createdAt: Filter.gt('2020') }),
+      ).reference('assignee');
+
+      log('query', { ast: AssigneesOfAllTasksCreatedAfter2020.ast });
+      Schema.validateSync(QueryAST.Query)(AssigneesOfAllTasksCreatedAfter2020.ast);
+      log('AssigneesOfAllTasksCreatedAfter2020', { ast: AssigneesOfAllTasksCreatedAfter2020.ast });
+    });
+
+    test('untyped full-text search', () => {
+      const contactFullTextSearch = Query.select(Filter.text('Bill'));
+
+      log('query', { ast: contactFullTextSearch.ast });
+      Schema.validateSync(QueryAST.Query)(contactFullTextSearch.ast);
+      expect(contactFullTextSearch.ast).toMatchInlineSnapshot(`
+      {
+        "filter": {
+          "searchKind": undefined,
+          "text": "Bill",
+          "type": "text-search",
+        },
+        "type": "select",
+      }
+    `);
+    });
+
+    test('typed full-text search', () => {
+      const contactFullTextSearch = Query.select(Filter.type(Test.Person)).select(Filter.text('Bill'));
+
+      log('query', { ast: contactFullTextSearch.ast });
+      Schema.validateSync(QueryAST.Query)(contactFullTextSearch.ast);
+      expect(contactFullTextSearch.ast).toMatchInlineSnapshot(`
+      {
+        "filter": {
+          "searchKind": undefined,
+          "text": "Bill",
+          "type": "text-search",
+        },
+        "selection": {
+          "filter": {
+            "id": undefined,
+            "props": {},
+            "type": "object",
+            "typename": "dxn:type:dxos.org/type/Person:0.1.0",
+          },
+          "type": "select",
+        },
+        "type": "filter",
+      }
+    `);
+    });
+
+    test('filter by ref', () => {
+      const fred = Obj.make(Test.Person, { name: 'Fred' });
+      const tasksByFred = Filter.type(Test.Task, { assignee: Ref.make(fred) });
+      expect(tasksByFred.ast).toEqual({
+        props: {
+          assignee: {
+            operator: 'eq',
+            type: 'compare',
+            value: {
+              '/': DXN.fromLocalObjectId(fred.id).toString(),
+            },
+          },
+        },
+        type: 'object',
+        typename: 'dxn:type:dxos.org/type/Task:0.1.0',
+      });
+      log('tasksByFred', { ast: tasksByFred.ast });
+    });
+
+    test('select orgs and people', () => {
+      const orgsAndPeople = Query.select(Filter.or(Filter.type(Test.Organization), Filter.type(Test.Person)));
+
+      Schema.validateSync(QueryAST.Query)(orgsAndPeople.ast);
+      expect(orgsAndPeople.ast).toMatchInlineSnapshot(`
+      {
+        "filter": {
+          "filters": [
+            {
+              "id": undefined,
+              "props": {},
+              "type": "object",
+              "typename": "dxn:type:dxos.org/type/Organization:0.1.0",
+            },
+            {
+              "id": undefined,
+              "props": {},
+              "type": "object",
+              "typename": "dxn:type:dxos.org/type/Person:0.1.0",
+            },
+          ],
+          "type": "or",
+        },
+        "type": "select",
+      }
+    `);
+    });
+
+    test('select everything but orgs and people', () => {
+      const everythingButOrgsAndPeople = Query.select(
+        Filter.not(Filter.or(Filter.type(Test.Organization), Filter.type(Test.Person))),
+      );
+
+      Schema.validateSync(QueryAST.Query)(everythingButOrgsAndPeople.ast);
+      expect(everythingButOrgsAndPeople.ast).toMatchInlineSnapshot(`
+      {
+        "filter": {
+          "filter": {
+            "filters": [
+              {
+                "id": undefined,
+                "props": {},
+                "type": "object",
+                "typename": "dxn:type:dxos.org/type/Organization:0.1.0",
+              },
+              {
+                "id": undefined,
+                "props": {},
+                "type": "object",
+                "typename": "dxn:type:dxos.org/type/Person:0.1.0",
+              },
+            ],
+            "type": "or",
+          },
+          "type": "not",
+        },
+        "type": "select",
+      }
+    `);
+    });
+
+    test('select deleted tasks', () => {
+      const deletedTasks = Query.select(Filter.type(Test.Task)).options({
+        deleted: 'only',
+      });
+
+      Schema.validateSync(QueryAST.Query)(deletedTasks.ast);
+      expect(deletedTasks.ast).toMatchInlineSnapshot(`
+      {
+        "options": {
+          "deleted": "only",
+        },
+        "query": {
+          "filter": {
+            "id": undefined,
+            "props": {},
+            "type": "object",
+            "typename": "dxn:type:dxos.org/type/Task:0.1.0",
+          },
+          "type": "select",
+        },
+        "type": "options",
+      }
+    `);
+    });
+
+    test('filter by tags', () => {
+      const query = Query.select(Filter.type(Test.Task)).select(Filter.tag('important'));
+      Schema.validateSync(QueryAST.Query)(query.ast);
+      expect(query.ast).toMatchInlineSnapshot(`
+        {
+          "filter": {
+            "tag": "important",
+            "type": "tag",
+          },
+          "selection": {
+            "filter": {
+              "id": undefined,
+              "props": {},
+              "type": "object",
+              "typename": "dxn:type:dxos.org/type/Task:0.1.0",
+            },
+            "type": "select",
+          },
+          "type": "filter",
+        }
+      `);
+    });
+
+    test.skip('chain', () => {
+      // NOTE: Can't support props without type since they can't be inferred.
+      // const f1: Filter<Person> = Filter.props({ name: 'Fred' });
+
+      // const x = Query.select(Filter.props({ id: '123' }));
+      const y = Query.select(Filter.type(Test.Person));
+
+      const or = Filter.or(Filter.type(Test.Person, { id: Filter.in('1', '2', '3') }), Filter.type(Test.Organization));
+
+      const and = Filter.and(
+        Filter.type(Test.Person, { id: Filter.in('1', '2', '3') }),
+        Filter.type(Test.Person, { name: 'Fred' }),
+      );
+
+      const q = Query
+        //
+        // NOTE: Can't support functions since they can't be serialized (to server).
+        // .filter((object) => Math.random() > 0.5)
+        .select(Filter.type(Test.Person))
+        .select(Filter.type(Test.Person, { name: 'Fred' }))
+        .select({ age: Filter.between(20, 40) })
+        .select(Filter.and(Filter.type(Test.Person), Filter.type(Test.Person, { name: Filter.in('bob', 'bill') })));
+
+      log('stuff', { fOr: or, fAnd: and, q, y });
+    });
+  });
+
+  describe('Filter', () => {
+    test('Filter.or(Filter.typename(...))', () => {
+      const filter = Filter.or(Filter.typename('dxos.org/type/Person'));
+      // TODO(dmaretskyi): Give vitest type-tests a try.
+      const _isAssignable: Obj.Any = null as any as Filter.Type<typeof filter>;
+    });
+  });
+});

package/src/query/query.ts

@@ -0,0 +1,303 @@
+//
+// 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 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.
+
+/**
+ * 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<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.Any
+      ? Ref.Target<T[K]>
+      : T[K] extends Ref.Any | 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.
+   * @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>>;
+
+  /**
+   * 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<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>>;
+
+  /**
+   * Combine results of multiple queries.
+   * @param queries - Queries to combine.
+   * @returns Query for the combined results.
+   */
+  // TODO(dmaretskyi): Rename to `combine` or `union`.
+  all<T>(...queries: Query<T>[]): 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.
+   */
+  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;
+}
+
+// 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'];
+
+  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);
+  }
+
+  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,
+    });
+  }
+
+  constructor(public readonly ast: QueryAST.Query) {}
+
+  '~Query' = QueryClass.variance;
+
+  select(filter: Filter.Any | Filter.Props<any>): Query.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: FilterClass.props(filter).ast,
+      });
+    }
+  }
+
+  reference(key: string): Query.Any {
+    return new QueryClass({
+      type: 'reference-traversal',
+      anchor: this.ast,
+      property: key,
+    });
+  }
+
+  referencedBy(target: Schema.Schema.All | string, key: string): Query.Any {
+    const dxn = getTypeDXNFromSpecifier(target);
+    return new QueryClass({
+      type: 'incoming-references',
+      anchor: this.ast,
+      property: key,
+      typename: dxn.toString(),
+    });
+  }
+
+  sourceOf(relation: Schema.Schema.All | string, predicates?: Filter.Props<unknown> | undefined): Query.Any {
+    return new QueryClass({
+      type: 'relation',
+      anchor: this.ast,
+      direction: 'outgoing',
+      filter: FilterClass.type(relation, predicates).ast,
+    });
+  }
+
+  targetOf(relation: Schema.Schema.All | string, predicates?: Filter.Props<unknown> | undefined): Query.Any {
+    return new QueryClass({
+      type: 'relation',
+      anchor: this.ast,
+      direction: 'incoming',
+      filter: FilterClass.type(relation, predicates).ast,
+    });
+  }
+
+  source(): Query.Any {
+    return new QueryClass({
+      type: 'relation-traversal',
+      anchor: this.ast,
+      direction: 'source',
+    });
+  }
+
+  target(): Query.Any {
+    return new QueryClass({
+      type: 'relation-traversal',
+      anchor: this.ast,
+      direction: 'target',
+    });
+  }
+
+  orderBy(...order: Order<any>[]): Query.Any {
+    return new QueryClass({
+      type: 'order',
+      query: this.ast,
+      order: order.map((o) => o.ast),
+    });
+  }
+
+  options(options: QueryAST.QueryOptions): Query.Any {
+    return new QueryClass({
+      type: 'options',
+      query: this.ast,
+      options,
+    });
+  }
+}
+
+export const Query: QueryAPI = QueryClass;

package/src/query/testing.ts

@@ -0,0 +1,64 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import * as Type from '../Type';
+
+// TODO(burdon): Rationalize with ../testing
+
+export const Person = Schema.Struct({
+  name: Schema.String,
+  email: Schema.optional(Schema.String),
+  age: Schema.optional(Schema.Number),
+  fields: Schema.Struct({
+    label: Schema.String,
+    value: Schema.String,
+  }).pipe(Schema.Array, Schema.optional),
+}).pipe(
+  Type.Obj({
+    typename: 'dxos.org/type/Person',
+    version: '0.1.0',
+  }),
+);
+
+export interface Person extends Schema.Schema.Type<typeof Person> {}
+
+export const Organization = Schema.Struct({
+  name: Schema.String,
+  properties: Schema.optional(
+    Schema.Record({
+      key: Schema.String,
+      value: Schema.String,
+    }),
+  ),
+}).pipe(
+  Type.Obj({
+    typename: 'dxos.org/type/Organization',
+    version: '0.1.0',
+  }),
+);
+
+export interface Organization extends Schema.Schema.Type<typeof Organization> {}
+
+export const WorksFor = Schema.Struct({
+  since: Schema.String,
+}).pipe(
+  Type.Relation({
+    typename: 'dxos.org/type/WorksFor',
+    version: '0.1.0',
+    source: Person,
+    target: Organization,
+  }),
+);
+
+export interface WorksFor extends Schema.Schema.Type<typeof WorksFor> {}
+
+export const Task = Schema.Struct({
+  title: Schema.String,
+  createdAt: Schema.String,
+  assignee: Schema.optional(Type.Ref(Person)),
+}).pipe(Type.Obj({ typename: 'dxos.org/type/Task', version: '0.1.0' }));
+
+export interface Task extends Schema.Schema.Type<typeof Task> {}