@dxos/echo 0.8.2-main.5885341 → 0.8.2-main.5ca3450

package/src/query/api.ts

@@ -0,0 +1,291 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Schema } from 'effect';
+
+import { raise } from '@dxos/debug';
+import { getSchemaDXN, type Ref } from '@dxos/echo-schema';
+
+import type * as QueryAST from './ast';
+import type { Relation } from '..';
+
+// TODO(dmaretskyi): Split up into interfaces for objects and relations so they can have separate verbs.
+// TODO(dmaretskyi): Undirected relation traversals.
+
+export interface Query<T> {
+  // TODO(dmaretskyi): See new effect-schema approach to variance.
+  '~Query': { value: T };
+
+  ast: QueryAST.AST;
+
+  /**
+   * Traverse an outgoing reference.
+   * @param key - Property path inside T that is a reference.
+   * @returns Query for the target of the reference.
+   */
+  reference<K extends RefPropKey<T>>(key: K): Query<Ref.Target<T[K]>>;
+
+  /**
+   * 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`?
+  referencedBy<S extends Schema.Schema.All>(
+    target: S,
+    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,
+    predicates?: PredicateSet<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,
+    predicates?: PredicateSet<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.Source<T>>;
+
+  /**
+   * For a query for relations, get the target objects.
+   * @returns Query for the target objects.
+   */
+  target(): Query<Relation.Target<T>>;
+}
+
+interface QueryAPI {
+  /**
+   * 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.
+   */
+  type<S extends Schema.Schema.All>(
+    schema: S,
+    predicates?: PredicateSet<Schema.Schema.Type<S>>,
+  ): Query<Schema.Schema.Type<S>>;
+
+  /**
+   * Full-text or vector search.
+   */
+  text<S extends Schema.Schema.All>(
+    // TODO(dmaretskyi): Allow passing an array of schema here.
+    schema: S,
+    // TODO(dmaretskyi): Consider passing a vector here, but really the embedding should be done on the query-executor side.
+    text: string,
+    options?: Query.TextSearchOptions,
+  ): Query<Schema.Schema.Type<S>>;
+
+  /**
+   * Combine results of multiple queries.
+   * @param queries - Queries to combine.
+   * @returns Query for the combined results.
+   */
+  all<T>(...queries: Query<T>[]): Query<T>;
+
+  /**
+   * Predicate for property to be greater than the provided value.
+   */
+  gt<T>(value: T): Predicate<T>;
+
+  /**
+   * Predicate for property to be greater than or equal to the provided value.
+   */
+  gte<T>(value: T): Predicate<T>;
+
+  /**
+   * Predicate for property to be less than the provided value.
+   */
+  lt<T>(value: T): Predicate<T>;
+
+  /**
+   * Predicate for property to be less than or equal to the provided value.
+   */
+  lte<T>(value: T): Predicate<T>;
+
+  /**
+   * Predicate for property to be in the provided array.
+   * @param values - Values to check against.
+   */
+  in<T>(...values: T[]): Predicate<T>;
+
+  /**
+   * Predicate for property to be in the provided range.
+   * @param from - Start of the range (inclusive).
+   * @param to - End of the range (exclusive).
+   */
+  range<T>(from: T, to: T): Predicate<T>;
+
+  // TODO(dmaretskyi): Add `Query.match` to support pattern matching on string props.
+}
+
+export declare namespace Query {
+  export type TextSearchOptions = {
+    type?: 'full-text' | 'vector';
+  };
+}
+
+export interface Predicate<T> {
+  // TODO(dmaretskyi): See new effect-schema approach to variance.
+  '~Predicate': { value: T };
+
+  ast: QueryAST.Predicate;
+}
+
+const Predicate = {
+  variance: {} as Predicate<any>['~Predicate'],
+
+  make: <T>(ast: QueryAST.Predicate): Predicate<T> => ({ ast, '~Predicate': Predicate.variance }) as Predicate<T>,
+};
+
+type PredicateSet<T> = {
+  // Predicate or a value as a shorthand for `eq`.
+  [K in keyof T & string]?: Predicate<T[K]> | T[K];
+};
+
+/**
+ * All property paths inside T that are references.
+ */
+type RefPropKey<T> = { [K in keyof T]: T[K] extends Ref<infer _U> ? K : never }[keyof T] & string;
+
+const predicateSetToAst = (predicates: PredicateSet<any>): QueryAST.PredicateSet => {
+  return Object.fromEntries(
+    Object.entries(predicates).map(([key, predicate]) => [key, predicate.ast]),
+  ) as QueryAST.PredicateSet;
+};
+
+class QueryClass implements Query<any> {
+  private static variance: Query<any>['~Query'] = {} as Query<any>['~Query'];
+
+  static type(schema: Schema.Schema.All, predicates?: PredicateSet<unknown>): Query<any> {
+    const dxn = getSchemaDXN(schema) ?? raise(new TypeError('Schema has no DXN'));
+    return new QueryClass({
+      type: 'type',
+      typename: dxn.toString(),
+      predicates: predicates ? predicateSetToAst(predicates) : undefined,
+    });
+  }
+
+  static text(schema: Schema.Schema.All, text: string, options?: Query.TextSearchOptions): Query<any> {
+    const dxn = getSchemaDXN(schema) ?? raise(new TypeError('Schema has no DXN'));
+    return new QueryClass({
+      type: 'text-search',
+      typename: dxn.toString(),
+      text,
+      searchKind: options?.type,
+    });
+  }
+
+  static all(...queries: Query<any>[]): Query<any> {
+    return new QueryClass({
+      type: 'union',
+      queries: queries.map((q) => q.ast),
+    });
+  }
+
+  static gt(value: unknown): Predicate<any> {
+    return Predicate.make({ type: 'gt', value });
+  }
+
+  static gte(value: unknown): Predicate<any> {
+    return Predicate.make({ type: 'gte', value });
+  }
+
+  static lt(value: unknown): Predicate<any> {
+    return Predicate.make({ type: 'lt', value });
+  }
+
+  static lte(value: unknown): Predicate<any> {
+    return Predicate.make({ type: 'lte', value });
+  }
+
+  static in(...values: unknown[]): Predicate<any> {
+    return Predicate.make({ type: 'in', values });
+  }
+
+  static range(from: unknown, to: unknown): Predicate<any> {
+    return Predicate.make({ type: 'range', from, to });
+  }
+
+  constructor(public readonly ast: QueryAST.AST) {}
+
+  '~Query' = QueryClass.variance;
+
+  reference(key: string): Query<any> {
+    return new QueryClass({
+      type: 'reference-traversal',
+      anchor: this.ast,
+      property: key,
+    });
+  }
+
+  referencedBy(target: Schema.Schema.All, key: string): Query<any> {
+    const dxn = getSchemaDXN(target) ?? raise(new TypeError('Target schema has no DXN'));
+    return new QueryClass({
+      type: 'incoming-references',
+      anchor: this.ast,
+      property: key,
+      typename: dxn.toString(),
+    });
+  }
+
+  sourceOf(relation: Schema.Schema.All, predicates?: PredicateSet<unknown> | undefined): Query<any> {
+    const dxn = getSchemaDXN(relation) ?? raise(new TypeError('Relation schema has no DXN'));
+    return new QueryClass({
+      type: 'relation',
+      anchor: this.ast,
+      direction: 'outgoing',
+      typename: dxn.toString(),
+      predicates: predicates ? predicateSetToAst(predicates) : undefined,
+    });
+  }
+
+  targetOf(relation: Schema.Schema.All, predicates?: PredicateSet<unknown> | undefined): Query<any> {
+    const dxn = getSchemaDXN(relation) ?? raise(new TypeError('Relation schema has no DXN'));
+    return new QueryClass({
+      type: 'relation',
+      anchor: this.ast,
+      direction: 'incoming',
+      typename: dxn.toString(),
+      predicates: predicates ? predicateSetToAst(predicates) : undefined,
+    });
+  }
+
+  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',
+    });
+  }
+}
+
+export const Query: QueryAPI = QueryClass;

package/src/query/ast.ts

@@ -0,0 +1,149 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Schema } from 'effect';
+
+import { DXN } from '@dxos/echo-schema';
+
+export const Predicate = Schema.Union(
+  Schema.Struct({
+    type: Schema.Literal('eq'),
+    value: Schema.Any,
+  }),
+  Schema.Struct({
+    type: Schema.Literal('neq'),
+    value: Schema.Any,
+  }),
+  Schema.Struct({
+    type: Schema.Literal('gt'),
+    value: Schema.Any,
+  }),
+  Schema.Struct({
+    type: Schema.Literal('gte'),
+    value: Schema.Any,
+  }),
+  Schema.Struct({
+    type: Schema.Literal('lt'),
+    value: Schema.Any,
+  }),
+  Schema.Struct({
+    type: Schema.Literal('lte'),
+    value: Schema.Any,
+  }),
+  Schema.Struct({
+    type: Schema.Literal('in'),
+    values: Schema.Array(Schema.Any),
+  }),
+  Schema.Struct({
+    type: Schema.Literal('range'),
+    from: Schema.Any,
+    to: Schema.Any,
+  }),
+);
+
+export type Predicate = Schema.Schema.Type<typeof Predicate>;
+
+export const PredicateSet = Schema.Record({
+  key: Schema.String.annotations({ description: 'Property name' }),
+  value: Predicate,
+});
+
+export type PredicateSet = Schema.Schema.Type<typeof PredicateSet>;
+
+const TypenameSpecifier = Schema.Union(DXN, Schema.Null).annotations({
+  description: 'DXN or null. Null means any type will match',
+});
+
+// NOTE: This pattern with 3 definitions per schema is need to make the types opaque, and circular references in AST to not cause compiler errors.
+
+/**
+ * Query objects by type, id, and/or predicates.
+ */
+const ASTTypeClause_ = Schema.Struct({
+  type: Schema.Literal('type'),
+  typename: TypenameSpecifier,
+  id: Schema.optional(Schema.String),
+  predicates: Schema.optional(PredicateSet),
+});
+interface ASTTypeClause extends Schema.Schema.Type<typeof ASTTypeClause_> {}
+const ASTTypeClause: Schema.Schema<ASTTypeClause> = ASTTypeClause_;
+
+const ASTTextSearchClause_ = Schema.Struct({
+  type: Schema.Literal('text-search'),
+  typename: TypenameSpecifier,
+  text: Schema.String,
+  searchKind: Schema.optional(Schema.Literal('full-text', 'vector')),
+});
+interface ASTTextSearchClause extends Schema.Schema.Type<typeof ASTTextSearchClause_> {}
+const ASTTextSearchClause: Schema.Schema<ASTTextSearchClause> = ASTTextSearchClause_;
+
+/**
+ * Traverse references from an anchor object.
+ */
+const ASTReferenceTraversalClause_ = Schema.Struct({
+  type: Schema.Literal('reference-traversal'),
+  anchor: Schema.suspend(() => AST),
+  property: Schema.String,
+});
+interface ASTReferenceTraversalClause extends Schema.Schema.Type<typeof ASTReferenceTraversalClause_> {}
+const ASTReferenceTraversalClause: Schema.Schema<ASTReferenceTraversalClause> = ASTReferenceTraversalClause_;
+
+/**
+ * Traverse incoming references to an anchor object.
+ */
+const ASTIncomingReferencesClause_ = Schema.Struct({
+  type: Schema.Literal('incoming-references'),
+  anchor: Schema.suspend(() => AST),
+  property: Schema.String,
+  typename: TypenameSpecifier,
+});
+interface ASTIncomingReferencesClause extends Schema.Schema.Type<typeof ASTIncomingReferencesClause_> {}
+const ASTIncomingReferencesClause: Schema.Schema<ASTIncomingReferencesClause> = ASTIncomingReferencesClause_;
+
+/**
+ * Traverse relations connecting to an anchor object.
+ */
+const ASTRelationClause_ = Schema.Struct({
+  type: Schema.Literal('relation'),
+  anchor: Schema.suspend(() => AST),
+  direction: Schema.Literal('outgoing', 'incoming', 'both'),
+  typename: TypenameSpecifier,
+  predicates: Schema.optional(PredicateSet),
+});
+interface ASTRelationClause extends Schema.Schema.Type<typeof ASTRelationClause_> {}
+const ASTRelationClause: Schema.Schema<ASTRelationClause> = ASTRelationClause_;
+
+/**
+ * Traverse into the source or target of a relation.
+ */
+const ASTRelationTraversalClause_ = Schema.Struct({
+  type: Schema.Literal('relation-traversal'),
+  anchor: Schema.suspend(() => AST),
+  direction: Schema.Literal('source', 'target', 'both'),
+});
+interface ASTRelationTraversalClause extends Schema.Schema.Type<typeof ASTRelationTraversalClause_> {}
+const ASTRelationTraversalClause: Schema.Schema<ASTRelationTraversalClause> = ASTRelationTraversalClause_;
+
+/**
+ * Union of multiple queries.
+ */
+const ASTUnionClause_ = Schema.Struct({
+  type: Schema.Literal('union'),
+  queries: Schema.Array(Schema.suspend(() => AST)),
+});
+interface ASTUnionClause extends Schema.Schema.Type<typeof ASTUnionClause_> {}
+const ASTUnionClause: Schema.Schema<ASTUnionClause> = ASTUnionClause_;
+
+const AST_ = Schema.Union(
+  ASTTypeClause,
+  ASTTextSearchClause,
+  ASTReferenceTraversalClause,
+  ASTIncomingReferencesClause,
+  ASTRelationClause,
+  ASTRelationTraversalClause,
+  ASTUnionClause,
+);
+
+export type AST = Schema.Schema.Type<typeof AST_>;
+export const AST: Schema.Schema<AST> = AST_;

package/src/query/query.test.ts

@@ -0,0 +1,135 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Schema } from 'effect';
+import { describe, test } from 'vitest';
+
+import { create } from '@dxos/echo-schema';
+import { log } from '@dxos/log';
+
+import { Query } from './api';
+import { Type, Relation } from '..';
+
+//
+// Example schema
+//
+
+const Person = Schema.Struct({
+  name: Schema.String,
+  email: Schema.optional(Schema.String),
+}).pipe(Type.def({ typename: 'dxos.org/type/Person', version: '0.1.0' }));
+interface Person extends Schema.Schema.Type<typeof Person> {}
+
+const Org = Schema.Struct({
+  name: Schema.String,
+}).pipe(Type.def({ typename: 'dxos.org/type/Org', version: '0.1.0' }));
+interface Org extends Schema.Schema.Type<typeof Org> {}
+
+const WorksFor = Schema.Struct({
+  since: Schema.String,
+}).pipe(Relation.def({ typename: 'dxos.org/type/WorksFor', version: '0.1.0', source: Person, target: Org }));
+interface WorksFor extends Schema.Schema.Type<typeof WorksFor> {}
+
+const Task = Schema.Struct({
+  title: Schema.String,
+  createdAt: Schema.String,
+  assignee: Type.Ref(Person),
+}).pipe(Type.def({ typename: 'dxos.org/type/Task', version: '0.1.0' }));
+interface Task extends Schema.Schema.Type<typeof Task> {}
+
+//
+// Example queries
+//
+
+describe('query api', () => {
+  test('get all people', () => {
+    // Query<Person>
+    const getAllPeople = Query.type(Person);
+
+    log.info('query', { ast: getAllPeople.ast });
+  });
+
+  test('get all people named Fred', () => {
+    // Query<Person>
+    const getAllPeopleNamedFred = Query.type(Person, { name: 'Fred' });
+
+    log.info('query', { ast: getAllPeopleNamedFred.ast });
+  });
+
+  test('get all orgs Fred worked for since 2020', () => {
+    // Query<Org>
+    const fred = create(Person, { name: 'Fred' });
+    const getAllOrgsFredWorkedForSince2020 = Query.type(Person, { id: fred.id })
+      .sourceOf(WorksFor, { since: Query.gt('2020') })
+      .target();
+
+    log.info('query', { ast: getAllOrgsFredWorkedForSince2020.ast });
+  });
+
+  test('get all tasks for Fred', () => {
+    // Query<Task>
+    const fred = create(Person, { name: 'Fred' });
+    const getAllTasksForFred = Query.type(Person, { id: fred.id }).referencedBy(Task, 'assignee');
+
+    log.info('query', { ast: getAllTasksForFred.ast });
+  });
+
+  test('get all tasks for employees of Cyberdyne', () => {
+    // Query<Task>
+    const allTasksForEmployeesOfCyberdyne = Query.type(Org, { name: 'Cyberdyne' })
+      .targetOf(WorksFor)
+      .source()
+      .referencedBy(Task, 'assignee');
+
+    log.info('query', { ast: allTasksForEmployeesOfCyberdyne.ast });
+  });
+
+  test('get all people or orgs', () => {
+    // Query<Person | Org>
+    const allPeopleOrOrgs = Query.all(Query.type(Person), Query.type(Org));
+
+    log.info('query', { ast: allPeopleOrOrgs.ast });
+  });
+
+  test('get assignees of all tasks created after 2020', () => {
+    // Query<Person>
+    const assigneesOfAllTasksCreatedAfter2020 = Query.type(Task, { createdAt: Query.gt('2020') }).reference('assignee');
+
+    log.info('query', { ast: assigneesOfAllTasksCreatedAfter2020.ast });
+  });
+
+  test('contact full-text search', () => {
+    // Query<Person>
+    const contactFullTextSearch = Query.text(Person, 'Bill');
+
+    log.info('query', { ast: contactFullTextSearch.ast });
+  });
+
+  // TODO(burdon): Experimental.
+  test.skip('chain', () => {
+    const db: any = null;
+    const Query: any = null;
+    const Filter: any = null;
+
+    const x = db.exec(Query.select({ id: '123' })).first();
+    const y = db.exec(Query.select(Filter.type(Person)).first());
+
+    const q = Query
+      //
+      .selectAll()
+      .select({ id: '123' })
+      // NOTE: Can't support functions since they can't be serialized (to server).
+      // .filter((object) => Math.random() > 0.5)
+      .select(Filter.type(Person))
+      .select(Filter.props({ name: 'Fred' }))
+      .select({ age: Filter.gt(40) })
+      .select({ date: Filter.between(Date.now(), Date.now() + 1000 * 60 * 60 * 24) })
+      .select({ id: Filter.in(['1', '2', '3']) })
+      .select(Filter.and(Filter.type(Person), Filter.props({ id: Filter.in(['1', '2', '3']) })))
+      .target()
+      .select();
+
+    log.info('stuff', { x, y, q });
+  });
+});

package/src/type/Relation.ts

@@ -0,0 +1,17 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { EchoRelation, type RelationSourceTargetRefs } from '@dxos/echo-schema';
+
+export const def = EchoRelation;
+
+/**
+ * Get relation target type.
+ */
+export type Target<A> = A extends RelationSourceTargetRefs<infer T, infer _S> ? T : never;
+
+/**
+ * Get relation source type.
+ */
+export type Source<A> = A extends RelationSourceTargetRefs<infer _T, infer S> ? S : never;

package/src/type/Type.test.ts

@@ -0,0 +1,106 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Schema } from 'effect';
+import { describe, test } from 'vitest';
+
+import { raise } from '@dxos/debug';
+import { FormatEnum, FormatAnnotation } from '@dxos/echo-schema';
+
+import { Type } from './Type';
+
+namespace Testing {
+  export const Organization = Schema.Struct({
+    id: Type.ObjectId,
+    name: Schema.String,
+  }).pipe(
+    Type.def({
+      typename: 'example.com/type/Organization',
+      version: '0.1.0',
+    }),
+  );
+
+  export interface Organization extends Schema.Schema.Type<typeof Organization> {}
+
+  export const Person = Schema.Struct({
+    name: Schema.String,
+    dob: Schema.optional(Schema.String),
+    email: Schema.optional(Schema.String.pipe(FormatAnnotation.set(FormatEnum.Email))),
+    organization: Schema.optional(Type.Ref(Organization)),
+  }).pipe(
+    Type.def({
+      typename: 'example.com/type/Person',
+      version: '0.1.0',
+    }),
+  );
+
+  export interface Person extends Schema.Schema.Type<typeof Person> {}
+
+  export const Message = Schema.Struct({
+    // TODO(burdon): Support S.Date; Custom Timestamp (with defaults).
+    // TODO(burdon): Support defaults (update create and create).
+    timestamp: Schema.String.pipe(
+      Schema.propertySignature,
+      Schema.withConstructorDefault(() => new Date().toISOString()),
+    ),
+  });
+
+  export const WorksFor = Schema.Struct({
+    // id: Type.ObjectId,
+    role: Schema.String,
+  }).pipe(
+    // Relation.def
+    Type.def({
+      typename: 'example.com/type/WorksFor',
+      version: '0.1.0',
+      // source: Person,
+      // target: Organization,
+    }),
+  );
+
+  export interface WorksFor extends Schema.Schema.Type<typeof WorksFor> {}
+
+  // TODO(burdon): Fix (Type.def currently removes TypeLiteral that implements the `make` function)..
+  // }).pipe(
+  //   Type.def({
+  //     typename: 'example.com/type/Message',
+  //     version: '0.1.0',
+  //   }),
+  // );
+
+  export interface Message extends Schema.Schema.Type<typeof Message> {}
+}
+
+describe('Experimental API review', () => {
+  test('type checks', ({ expect }) => {
+    const contact = Type.create(Testing.Person, { name: 'Test' });
+    const type: Schema.Schema<Testing.Person> = Type.getSchema(contact) ?? raise(new Error('No schema found'));
+
+    expect(Type.getDXN(type)?.typename).to.eq(Testing.Person.typename);
+    expect(Type.getTypename(type)).to.eq('example.com/type/Person');
+    expect(Type.getVersion(type)).to.eq('0.1.0');
+    expect(Type.getMeta(type)).to.deep.eq({
+      kind: Type.Kind.Object,
+      typename: 'example.com/type/Person',
+      version: '0.1.0',
+    });
+  });
+
+  test('instance checks', ({ expect }) => {
+    const organization = Type.create(Testing.Organization, { name: 'DXOS' });
+    const contact = Type.create(Testing.Person, { name: 'Test', organization: Type.ref(organization) });
+
+    expect(Schema.is(Testing.Person)(contact)).to.be.true;
+    expect(Testing.Person.instanceOf(contact)).to.be.true;
+    expect(Type.instanceOf(Testing.Person, contact)).to.be.true;
+    expect(Type.instanceOf(Testing.Organization, organization)).to.be.true;
+  });
+
+  test('default props', ({ expect }) => {
+    // TODO(burdon): Doesn't work after pipe(Type.def).
+    // Property 'make' does not exist on type 'EchoObjectSchema<Struct<{ timestamp: PropertySignature<":", string, never, ":", string, true, never>; }>>'.ts(2339)
+    const message = Type.create(Testing.Message, Testing.Message.make({}));
+    expect(message.timestamp).to.exist;
+  });
+});