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

package/src/query/query.ts

@@ -3,52 +3,29 @@
 //
 
 import type * as EffectArray from 'effect/Array';
-import * as Match from 'effect/Match';
-import * as Schema from 'effect/Schema';
+import type * as Schema from 'effect/Schema';
 
-import { raise } from '@dxos/debug';
-import { type ForeignKey, type QueryAST } from '@dxos/echo-protocol';
-import { assertArgument } from '@dxos/invariant';
-import { DXN, ObjectId } from '@dxos/keys';
+import { type QueryAST } from '@dxos/echo-protocol';
 
-import { getTypeReference } from '../internal';
-import type * as Obj from '../Obj';
-import * as Ref from '../Ref';
+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.
 
-export interface Order<T> {
-  // TODO(dmaretskyi): See new effect-schema approach to variance.
-  '~Order': { value: T };
-
-  ast: QueryAST.Order;
-}
-
-class OrderClass implements Order<any> {
-  private static variance: Order<any>['~Order'] = {} as Order<any>['~Order'];
-
-  static is(value: unknown): value is Order<any> {
-    return typeof value === 'object' && value !== null && '~Order' in value;
-  }
-
-  constructor(public readonly ast: QueryAST.Order) {}
-
-  '~Order' = OrderClass.variance;
-}
-
-export namespace Order {
-  export const natural: Order<any> = new OrderClass({ kind: 'natural' });
-  export const property = <T>(property: keyof T & string, direction: QueryAST.OrderDirection): Order<T> =>
-    new OrderClass({
-      kind: 'property',
-      property,
-      direction,
-    });
-}
+/**
+ * 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 };
@@ -186,453 +163,9 @@ export declare namespace Query {
   export type Any = Query<any>;
 
   export type Type<Q extends Any> = Q extends Query<infer T> ? T : never;
-
-  export type TextSearchOptions = {
-    // TODO(dmaretskyi): Hybrid search.
-    type?: 'full-text' | 'vector';
-  };
-}
-
-export interface Filter<T> {
-  // TODO(dmaretskyi): See new effect-schema approach to variance.
-  '~Filter': { value: T };
-
-  ast: QueryAST.Filter;
-}
-
-type Intersection<Types extends readonly unknown[]> = Types extends [infer First, ...infer Rest]
-  ? First & Intersection<Rest>
-  : unknown;
-
-interface FilterAPI {
-  is(value: unknown): value is Filter<any>;
-
-  /** Construct a filter from an ast. */
-  fromAst(ast: QueryAST.Filter): Filter<any>;
-
-  /**
-   * Filter that matches all objects.
-   */
-  everything(): Filter<any>;
-
-  /**
-   * Filter that matches no objects.
-   */
-  nothing(): Filter<any>;
-
-  /**
-   * Filter by object IDs.
-   */
-  // TODO(dmaretskyi): Rename to `Filter.id`.
-  ids(...id: ObjectId[]): Filter<any>;
-
-  /**
-   * Filter by type.
-   */
-  type<S extends Schema.Schema.All>(
-    schema: S | string,
-    props?: Filter.Props<Schema.Schema.Type<S>>,
-  ): Filter<Schema.Schema.Type<S>>;
-
-  /**
-   * Filter by non-qualified typename.
-   */
-  typename(typename: string): Filter<any>;
-
-  /**
-   * Filter by fully qualified type DXN.
-   */
-  typeDXN(dxn: DXN): Filter<any>;
-
-  /**
-   * Filter by tag.
-   */
-  tag(tag: string): Filter<Obj.Any>;
-
-  /**
-   * Filter by properties.
-   */
-  props<T>(props: Filter.Props<T>): Filter<T>;
-
-  /**
-   * Full-text or vector search.
-   */
-  text(
-    // TODO(dmaretskyi): Consider passing a vector here, but really the embedding should be done on the query-executor side.
-    text: string,
-    options?: Query.TextSearchOptions,
-  ): Filter<any>;
-
-  /**
-   * Filter by foreign keys.
-   */
-  foreignKeys<S extends Schema.Schema.All>(schema: S, keys: ForeignKey[]): Filter<Schema.Schema.Type<S>>;
-
-  /**
-   * Predicate for property to be equal to the provided value.
-   */
-  eq<T>(value: T): Filter<T>;
-
-  /**
-   * Predicate for property to be not equal to the provided value.
-   */
-  neq<T>(value: T): Filter<T>;
-
-  /**
-   * Predicate for property to be greater than the provided value.
-   */
-  gt<T>(value: T): Filter<T>;
-
-  /**
-   * Predicate for property to be greater than the provided value.
-   */
-  gt<T>(value: T): Filter<T>;
-
-  /**
-   * Predicate for property to be greater than or equal to the provided value.
-   */
-  gte<T>(value: T): Filter<T>;
-
-  /**
-   * Predicate for property to be less than the provided value.
-   */
-  lt<T>(value: T): Filter<T>;
-
-  /**
-   * Predicate for property to be less than or equal to the provided value.
-   */
-  lte<T>(value: T): Filter<T>;
-
-  /**
-   * Predicate for property to be in the provided array.
-   * @param values - Values to check against.
-   */
-  in<T>(...values: T[]): Filter<T>;
-
-  /**
-   * Predicate for an array property to contain the provided value.
-   * @param value - Value to check against.
-   */
-  contains<T>(value: T): Filter<T[]>;
-
-  /**
-   * Predicate for property to be in the provided range.
-   * @param from - Start of the range (inclusive).
-   * @param to - End of the range (exclusive).
-   */
-  between<T>(from: T, to: T): Filter<T>;
-
-  /**
-   * Negate the filter.
-   */
-  not<F extends Filter.Any>(filter: F): Filter<Filter.Type<F>>;
-
-  /**
-   * Combine filters with a logical AND.
-   */
-  and<FS extends Filter.Any[]>(...filters: FS): Filter<Filter.And<FS>>;
-
-  /**
-   * Combine filters with a logical OR.
-   */
-  or<FS extends Filter.Any[]>(...filters: FS): Filter<Filter.Or<FS>>;
-
-  // TODO(dmaretskyi): Add `Filter.match` to support pattern matching on string props.
 }
 
-export declare namespace Filter {
-  type Props<T> = {
-    // Predicate or a value as a shorthand for `eq`.
-    [K in keyof T & string]?: Filter<T[K]> | T[K];
-  };
-
-  type Any = Filter<any>;
-
-  type Type<F extends Any> = F extends Filter<infer T> ? T : never;
-
-  type And<FS extends readonly Any[]> = Schema.Simplify<Intersection<{ [K in keyof FS]: Type<FS[K]> }>>;
-
-  type Or<FS extends readonly Any[]> = Schema.Simplify<{ [K in keyof FS]: Type<FS[K]> }[number]>;
-}
-
-class FilterClass implements Filter<any> {
-  private static variance: Filter<any>['~Filter'] = {} as Filter<any>['~Filter'];
-
-  static is(value: unknown): value is Filter<any> {
-    return typeof value === 'object' && value !== null && '~Filter' in value;
-  }
-
-  static fromAst(ast: QueryAST.Filter): Filter<any> {
-    return new FilterClass(ast);
-  }
-
-  static everything(): FilterClass {
-    return new FilterClass({
-      type: 'object',
-      typename: null,
-      props: {},
-    });
-  }
-
-  static nothing(): FilterClass {
-    return new FilterClass({
-      type: 'not',
-      filter: {
-        type: 'object',
-        typename: null,
-        props: {},
-      },
-    });
-  }
-
-  static relation() {
-    return new FilterClass({
-      type: 'object',
-      typename: null,
-      props: {},
-    });
-  }
-
-  static ids(...ids: ObjectId[]): Filter<any> {
-    assertArgument(
-      ids.every((id) => ObjectId.isValid(id)),
-      'ids',
-      'ids must be valid',
-    );
-
-    if (ids.length === 0) {
-      return Filter.nothing();
-    }
-
-    return new FilterClass({
-      type: 'object',
-      typename: null,
-      id: ids,
-      props: {},
-    });
-  }
-
-  static type<S extends Schema.Schema.All>(
-    schema: S | string,
-    props?: Filter.Props<Schema.Schema.Type<S>>,
-  ): Filter<Schema.Schema.Type<S>> {
-    const dxn = getTypeDXNFromSpecifier(schema);
-    return new FilterClass({
-      type: 'object',
-      typename: dxn.toString(),
-      ...propsFilterToAst(props ?? {}),
-    });
-  }
-
-  static typename(typename: string): Filter<any> {
-    assertArgument(!typename.startsWith('dxn:'), 'typename', 'Typename must no be qualified');
-    return new FilterClass({
-      type: 'object',
-      typename: DXN.fromTypename(typename).toString(),
-      props: {},
-    });
-  }
-
-  static typeDXN(dxn: DXN): Filter<any> {
-    return new FilterClass({
-      type: 'object',
-      typename: dxn.toString(),
-      props: {},
-    });
-  }
-
-  static tag(tag: string): Filter<any> {
-    return new FilterClass({
-      type: 'tag',
-      tag,
-    });
-  }
-
-  static props<T>(props: Filter.Props<T>): Filter<T> {
-    return new FilterClass({
-      type: 'object',
-      typename: null,
-      ...propsFilterToAst(props),
-    });
-  }
-
-  static text(text: string, options?: Query.TextSearchOptions): Filter<any> {
-    return new FilterClass({
-      type: 'text-search',
-      text,
-      searchKind: options?.type,
-    });
-  }
-
-  static foreignKeys<S extends Schema.Schema.All>(
-    schema: S | string,
-    keys: ForeignKey[],
-  ): Filter<Schema.Schema.Type<S>> {
-    const dxn = getTypeDXNFromSpecifier(schema);
-    return new FilterClass({
-      type: 'object',
-      typename: dxn.toString(),
-      props: {},
-      foreignKeys: keys,
-    });
-  }
-
-  static eq<T>(value: T): Filter<T> {
-    if (!Ref.isRef(value) && typeof value === 'object' && value !== null) {
-      throw new TypeError('Cannot use object as a value for eq filter');
-    }
-
-    return new FilterClass({
-      type: 'compare',
-      operator: 'eq',
-      value: Ref.isRef(value) ? value.noInline().encode() : value,
-    });
-  }
-
-  static neq<T>(value: T): Filter<T> {
-    return new FilterClass({
-      type: 'compare',
-      operator: 'neq',
-      value,
-    });
-  }
-
-  static gt<T>(value: T): Filter<T> {
-    return new FilterClass({
-      type: 'compare',
-      operator: 'gt',
-      value,
-    });
-  }
-
-  static gte<T>(value: T): Filter<T> {
-    return new FilterClass({
-      type: 'compare',
-      operator: 'gte',
-      value,
-    });
-  }
-
-  static lt<T>(value: T): Filter<T> {
-    return new FilterClass({
-      type: 'compare',
-      operator: 'lt',
-      value,
-    });
-  }
-
-  static lte<T>(value: T): Filter<T> {
-    return new FilterClass({
-      type: 'compare',
-      operator: 'lte',
-      value,
-    });
-  }
-
-  static in<T>(...values: T[]): Filter<T> {
-    return new FilterClass({
-      type: 'in',
-      values,
-    });
-  }
-
-  static contains<T>(value: T): Filter<T[]> {
-    return new FilterClass({
-      type: 'contains',
-      value,
-    });
-  }
-
-  static between<T>(from: T, to: T): Filter<T> {
-    return new FilterClass({
-      type: 'range',
-      from,
-      to,
-    });
-  }
-
-  static not<F extends Filter.Any>(filter: F): Filter<Filter.Type<F>> {
-    return new FilterClass({
-      type: 'not',
-      filter: filter.ast,
-    });
-  }
-
-  static and<T>(...filters: Filter<T>[]): Filter<T> {
-    return new FilterClass({
-      type: 'and',
-      filters: filters.map((f) => f.ast),
-    });
-  }
-
-  static or<T>(...filters: Filter<T>[]): Filter<T> {
-    return new FilterClass({
-      type: 'or',
-      filters: filters.map((f) => f.ast),
-    });
-  }
-
-  private constructor(public readonly ast: QueryAST.Filter) {}
-
-  '~Filter' = FilterClass.variance;
-}
-
-export const Filter: FilterAPI = FilterClass;
-
-/**
- * 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;
-
-const propsFilterToAst = (predicates: Filter.Props<any>): Pick<QueryAST.FilterObject, 'id' | 'props'> => {
-  let idFilter: readonly ObjectId[] | undefined;
-  if ('id' in predicates) {
-    assertArgument(
-      typeof predicates.id === 'string' || Array.isArray(predicates.id),
-      'predicates.id',
-      'invalid id filter',
-    );
-    idFilter = typeof predicates.id === 'string' ? [predicates.id] : predicates.id;
-    Schema.Array(ObjectId).pipe(Schema.validateSync)(idFilter);
-  }
-
-  return {
-    id: idFilter,
-    props: Object.fromEntries(
-      Object.entries(predicates)
-        .filter(([prop, _value]) => prop !== 'id')
-        .map(([prop, predicate]) => [prop, processPredicate(predicate)]),
-    ) as Record<string, QueryAST.Filter>,
-  };
-};
-
-const processPredicate = (predicate: any): QueryAST.Filter => {
-  return Match.value(predicate).pipe(
-    Match.withReturnType<QueryAST.Filter>(),
-    Match.when(Filter.is, (predicate) => predicate.ast),
-    // TODO(wittjosiah): Add support for array predicates.
-    Match.when(Array.isArray, (_predicate) => {
-      throw new Error('Array predicates are not yet supported.');
-    }),
-    Match.when(
-      (predicate: any) => !Ref.isRef(predicate) && typeof predicate === 'object' && predicate !== null,
-      (predicate) => {
-        const nestedProps = Object.fromEntries(
-          Object.entries(predicate).map(([key, value]) => [key, processPredicate(value)]),
-        );
-
-        return {
-          type: 'object',
-          typename: null,
-          props: nestedProps,
-        };
-      },
-    ),
-    Match.orElse((value) => Filter.eq(value).ast),
-  );
-};
-
+// 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'];
 
@@ -682,7 +215,7 @@ class QueryClass implements Query<any> {
 
   '~Query' = QueryClass.variance;
 
-  select(filter: Filter<any> | Filter.Props<any>): Query<any> {
+  select(filter: Filter.Any | Filter.Props<any>): Query.Any {
     if (Filter.is(filter)) {
       return new QueryClass({
         type: 'filter',
@@ -698,7 +231,7 @@ class QueryClass implements Query<any> {
     }
   }
 
-  reference(key: string): Query<any> {
+  reference(key: string): Query.Any {
     return new QueryClass({
       type: 'reference-traversal',
       anchor: this.ast,
@@ -706,7 +239,7 @@ class QueryClass implements Query<any> {
     });
   }
 
-  referencedBy(target: Schema.Schema.All | string, key: string): Query<any> {
+  referencedBy(target: Schema.Schema.All | string, key: string): Query.Any {
     const dxn = getTypeDXNFromSpecifier(target);
     return new QueryClass({
       type: 'incoming-references',
@@ -716,7 +249,7 @@ class QueryClass implements Query<any> {
     });
   }
 
-  sourceOf(relation: Schema.Schema.All | string, predicates?: Filter.Props<unknown> | undefined): Query<any> {
+  sourceOf(relation: Schema.Schema.All | string, predicates?: Filter.Props<unknown> | undefined): Query.Any {
     return new QueryClass({
       type: 'relation',
       anchor: this.ast,
@@ -725,7 +258,7 @@ class QueryClass implements Query<any> {
     });
   }
 
-  targetOf(relation: Schema.Schema.All | string, predicates?: Filter.Props<unknown> | undefined): Query<any> {
+  targetOf(relation: Schema.Schema.All | string, predicates?: Filter.Props<unknown> | undefined): Query.Any {
     return new QueryClass({
       type: 'relation',
       anchor: this.ast,
@@ -734,7 +267,7 @@ class QueryClass implements Query<any> {
     });
   }
 
-  source(): Query<any> {
+  source(): Query.Any {
     return new QueryClass({
       type: 'relation-traversal',
       anchor: this.ast,
@@ -742,7 +275,7 @@ class QueryClass implements Query<any> {
     });
   }
 
-  target(): Query<any> {
+  target(): Query.Any {
     return new QueryClass({
       type: 'relation-traversal',
       anchor: this.ast,
@@ -750,7 +283,7 @@ class QueryClass implements Query<any> {
     });
   }
 
-  orderBy(...order: Order<any>[]): Query<any> {
+  orderBy(...order: Order<any>[]): Query.Any {
     return new QueryClass({
       type: 'order',
       query: this.ast,
@@ -758,7 +291,7 @@ class QueryClass implements Query<any> {
     });
   }
 
-  options(options: QueryAST.QueryOptions): Query<any> {
+  options(options: QueryAST.QueryOptions): Query.Any {
     return new QueryClass({
       type: 'options',
       query: this.ast,
@@ -768,17 +301,3 @@ class QueryClass implements Query<any> {
 }
 
 export const Query: QueryAPI = QueryClass;
-
-/**
- * @param input schema or a typename string
- * @return type DXN
- */
-const getTypeDXNFromSpecifier = (input: Schema.Schema.All | string): DXN => {
-  if (Schema.isSchema(input)) {
-    return getTypeReference(input)?.toDXN() ?? raise(new TypeError('Schema has no DXN'));
-  } else {
-    assertArgument(typeof input === 'string', 'input');
-    assertArgument(!input.startsWith('dxn:'), 'input');
-    return DXN.fromTypename(input);
-  }
-};

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> {}

package/src/query/util.ts

@@ -0,0 +1,25 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { raise } from '@dxos/debug';
+import { assertArgument } from '@dxos/invariant';
+import { DXN } from '@dxos/keys';
+
+import { getTypeReference } from '../internal';
+
+/**
+ * @param input schema or a typename string
+ * @return type DXN
+ */
+export const getTypeDXNFromSpecifier = (input: Schema.Schema.All | string): DXN => {
+  if (Schema.isSchema(input)) {
+    return getTypeReference(input)?.toDXN() ?? raise(new TypeError('Schema has no DXN'));
+  } else {
+    assertArgument(typeof input === 'string', 'input');
+    assertArgument(!input.startsWith('dxn:'), 'input');
+    return DXN.fromTypename(input);
+  }
+};