@dxos/echo 0.8.2-main.5ca3450 → 0.8.2-main.600d381

package/src/query/api.ts

@@ -3,6 +3,7 @@
 //
 
 import { type Schema } from 'effect';
+import type { Simplify } from 'effect/Schema';
 
 import { raise } from '@dxos/debug';
 import { getSchemaDXN, type Ref } from '@dxos/echo-schema';
@@ -17,7 +18,15 @@ export interface Query<T> {
   // TODO(dmaretskyi): See new effect-schema approach to variance.
   '~Query': { value: T };
 
-  ast: QueryAST.AST;
+  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.
@@ -46,7 +55,7 @@ export interface Query<T> {
    */
   sourceOf<S extends Schema.Schema.All>(
     relation: S,
-    predicates?: PredicateSet<Schema.Schema.Type<S>>,
+    predicates?: Filter.Props<Schema.Schema.Type<S>>,
   ): Query<Schema.Schema.Type<S>>;
 
   /**
@@ -57,7 +66,7 @@ export interface Query<T> {
    */
   targetOf<S extends Schema.Schema.All>(
     relation: S,
-    predicates?: PredicateSet<Schema.Schema.Type<S>>,
+    predicates?: Filter.Props<Schema.Schema.Type<S>>,
   ): Query<Schema.Schema.Type<S>>;
 
   /**
@@ -74,17 +83,80 @@ export interface Query<T> {
 }
 
 interface QueryAPI {
+  /**
+   * 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,
-    predicates?: PredicateSet<Schema.Schema.Type<S>>,
+    predicates?: Filter.Props<Schema.Schema.Type<S>>,
   ): Query<Schema.Schema.Type<S>>;
 
+  /**
+   * Full-text or vector search.
+   *
+   * @deprecated Use `Filter`.
+   */
+  // 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>;
+}
+
+export declare namespace Query {
+  export type TextSearchOptions = {
+    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>;
+
+  /**
+   * Filter by type.
+   */
+  type<S extends Schema.Schema.All>(
+    schema: S,
+    props?: Filter.Props<Schema.Schema.Type<S>>,
+  ): Filter<Schema.Schema.Type<S>>;
+
+  /**
+   * Filter by properties.
+   */
+  // props<T>(props: Filter.Props<T>): Filter<T>;
+
   /**
    * Full-text or vector search.
    */
@@ -94,101 +166,126 @@ interface QueryAPI {
     // 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>>;
+  ): Filter<Schema.Schema.Type<S>>;
 
   /**
-   * Combine results of multiple queries.
-   * @param queries - Queries to combine.
-   * @returns Query for the combined results.
+   * Predicate for property to be equal to the provided value.
    */
-  all<T>(...queries: Query<T>[]): Query<T>;
+  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): Predicate<T>;
+  gt<T>(value: T): Filter<T>;
 
   /**
    * Predicate for property to be greater than or equal to the provided value.
    */
-  gte<T>(value: T): Predicate<T>;
+  gte<T>(value: T): Filter<T>;
 
   /**
    * Predicate for property to be less than the provided value.
    */
-  lt<T>(value: T): Predicate<T>;
+  lt<T>(value: T): Filter<T>;
 
   /**
    * Predicate for property to be less than or equal to the provided value.
    */
-  lte<T>(value: T): Predicate<T>;
+  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[]): Predicate<T>;
+  in<T>(...values: 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).
    */
-  range<T>(from: T, to: T): Predicate<T>;
+  between<T>(from: T, to: T): Filter<T>;
 
-  // TODO(dmaretskyi): Add `Query.match` to support pattern matching on string props.
-}
+  /**
+   * Negate the filter.
+   */
+  not<F extends Filter.Any>(filter: F): Filter<F>;
 
-export declare namespace Query {
-  export type TextSearchOptions = {
-    type?: 'full-text' | 'vector';
-  };
-}
+  /**
+   * Combine filters with a logical AND.
+   */
+  and<FS extends Filter.Any[]>(...filters: FS): Filter<Filter.And<FS>>;
 
-export interface Predicate<T> {
-  // TODO(dmaretskyi): See new effect-schema approach to variance.
-  '~Predicate': { value: T };
+  /**
+   * Combine filters with a logical OR.
+   */
+  or<FS extends Filter.Any[]>(...filters: FS): Filter<Filter.Or<FS>>;
 
-  ast: QueryAST.Predicate;
+  // TODO(dmaretskyi): Add `Filter.match` to support pattern matching on string props.
 }
 
-const Predicate = {
-  variance: {} as Predicate<any>['~Predicate'],
+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];
+  };
 
-  make: <T>(ast: QueryAST.Predicate): Predicate<T> => ({ ast, '~Predicate': Predicate.variance }) as Predicate<T>,
-};
+  type Any = Filter<any>;
 
-type PredicateSet<T> = {
-  // Predicate or a value as a shorthand for `eq`.
-  [K in keyof T & string]?: Predicate<T[K]> | T[K];
-};
+  type Type<F extends Any> = F extends Filter<infer T> ? T : never;
 
-/**
- * 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;
+  type And<FS extends readonly Any[]> = Simplify<Intersection<{ [K in keyof FS]: Type<FS[K]> }>>;
 
-const predicateSetToAst = (predicates: PredicateSet<any>): QueryAST.PredicateSet => {
-  return Object.fromEntries(
-    Object.entries(predicates).map(([key, predicate]) => [key, predicate.ast]),
-  ) as QueryAST.PredicateSet;
-};
+  type Or<FS extends readonly Any[]> = Simplify<{ [K in keyof FS]: Type<FS[K]> }[number]>;
+}
 
-class QueryClass implements Query<any> {
-  private static variance: Query<any>['~Query'] = {} as Query<any>['~Query'];
+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 type(schema: Schema.Schema.All, predicates?: PredicateSet<unknown>): Query<any> {
+  static type<S extends Schema.Schema.All>(
+    schema: S,
+    props?: Filter.Props<Schema.Schema.Type<S>>,
+  ): Filter<Schema.Schema.Type<S>> {
     const dxn = getSchemaDXN(schema) ?? raise(new TypeError('Schema has no DXN'));
-    return new QueryClass({
-      type: 'type',
+    return new FilterClass({
+      type: 'object',
       typename: dxn.toString(),
-      predicates: predicates ? predicateSetToAst(predicates) : undefined,
+      props: props ? propsFilterToAst(props) : {},
+    });
+  }
+
+  /**
+   * @internal
+   */
+  static props<T>(props: Filter.Props<T>): Filter<T> {
+    return new FilterClass({
+      type: 'object',
+      typename: null,
+      props: propsFilterToAst(props),
     });
   }
 
-  static text(schema: Schema.Schema.All, text: string, options?: Query.TextSearchOptions): Query<any> {
+  static text<S extends Schema.Schema.All>(
+    schema: S,
+    text: string,
+    options?: Query.TextSearchOptions,
+  ): Filter<Schema.Schema.Type<S>> {
     const dxn = getSchemaDXN(schema) ?? raise(new TypeError('Schema has no DXN'));
-    return new QueryClass({
+    return new FilterClass({
       type: 'text-search',
       typename: dxn.toString(),
       text,
@@ -196,41 +293,155 @@ class QueryClass implements Query<any> {
     });
   }
 
-  static all(...queries: Query<any>[]): Query<any> {
-    return new QueryClass({
-      type: 'union',
-      queries: queries.map((q) => q.ast),
+  static eq<T>(value: T): Filter<T> {
+    return new FilterClass({
+      type: 'compare',
+      operator: 'eq',
+      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 gt(value: unknown): Predicate<any> {
-    return Predicate.make({ type: 'gt', value });
+  static between<T>(from: T, to: T): Filter<T> {
+    return new FilterClass({
+      type: 'range',
+      from,
+      to,
+    });
   }
 
-  static gte(value: unknown): Predicate<any> {
-    return Predicate.make({ type: 'gte', value });
+  static not<F extends Filter.Any>(filter: F): Filter<F> {
+    return new FilterClass({
+      type: 'not',
+      filter: filter.ast,
+    });
   }
 
-  static lt(value: unknown): Predicate<any> {
-    return Predicate.make({ type: 'lt', value });
+  static and<T>(...filters: Filter<T>[]): Filter<T> {
+    return new FilterClass({
+      type: 'and',
+      filters: filters.map((f) => f.ast),
+    });
   }
 
-  static lte(value: unknown): Predicate<any> {
-    return Predicate.make({ type: 'lte', value });
+  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.
+ */
+type RefPropKey<T> = { [K in keyof T]: T[K] extends Ref<infer _U> ? K : never }[keyof T] & string;
+
+const propsFilterToAst = (predicates: Filter.Props<any>): Record<string, QueryAST.Filter> => {
+  return Object.fromEntries(
+    Object.entries(predicates).map(([key, predicate]) => [
+      key,
+      Filter.is(predicate) ? predicate.ast : Filter.eq(predicate).ast,
+    ]),
+  ) as Record<string, QueryAST.Filter>;
+};
+
+class QueryClass implements Query<any> {
+  private static variance: Query<any>['~Query'] = {} as Query<any>['~Query'];
+
+  static select<F extends Filter.Any>(filter: F): Query<Filter.Type<F>> {
+    return new QueryClass({
+      type: 'select',
+      filter: filter.ast,
+    });
   }
 
-  static in(...values: unknown[]): Predicate<any> {
-    return Predicate.make({ type: 'in', values });
+  static type(schema: Schema.Schema.All, predicates?: Filter.Props<unknown>): Query<any> {
+    return new QueryClass({
+      type: 'select',
+      filter: FilterClass.type(schema, predicates).ast,
+    });
   }
 
-  static range(from: unknown, to: unknown): Predicate<any> {
-    return Predicate.make({ type: 'range', from, to });
+  static all(...queries: Query<any>[]): Query<any> {
+    return new QueryClass({
+      type: 'union',
+      queries: queries.map((q) => q.ast),
+    });
   }
 
-  constructor(public readonly ast: QueryAST.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',
@@ -249,25 +460,21 @@ class QueryClass implements Query<any> {
     });
   }
 
-  sourceOf(relation: Schema.Schema.All, predicates?: PredicateSet<unknown> | undefined): Query<any> {
-    const dxn = getSchemaDXN(relation) ?? raise(new TypeError('Relation schema has no DXN'));
+  sourceOf(relation: Schema.Schema.All, predicates?: Filter.Props<unknown> | undefined): Query<any> {
     return new QueryClass({
       type: 'relation',
       anchor: this.ast,
       direction: 'outgoing',
-      typename: dxn.toString(),
-      predicates: predicates ? predicateSetToAst(predicates) : undefined,
+      filter: FilterClass.type(relation, predicates).ast,
     });
   }
 
-  targetOf(relation: Schema.Schema.All, predicates?: PredicateSet<unknown> | undefined): Query<any> {
-    const dxn = getSchemaDXN(relation) ?? raise(new TypeError('Relation schema has no DXN'));
+  targetOf(relation: Schema.Schema.All, predicates?: Filter.Props<unknown> | undefined): Query<any> {
     return new QueryClass({
       type: 'relation',
       anchor: this.ast,
       direction: 'incoming',
-      typename: dxn.toString(),
-      predicates: predicates ? predicateSetToAst(predicates) : undefined,
+      filter: FilterClass.type(relation, predicates).ast,
     });
   }