@dxos/echo-query 0.8.4-main.c85a9c8dae → 0.8.4-main.d05539e30a

package/src/query-lite/query-lite.ts

@@ -111,7 +111,7 @@ class FilterClass implements Filter$.Any {
     }
     return new FilterClass({
       type: 'object',
-      typename: makeTypeDxn(schema),
+      typename: makeTypeDXN(schema),
       ...propsFilterToAst(props ?? {}),
     });
   }
@@ -119,7 +119,7 @@ class FilterClass implements Filter$.Any {
   static typename(typename: string): Filter$.Any {
     return new FilterClass({
       type: 'object',
-      typename: makeTypeDxn(typename),
+      typename: makeTypeDXN(typename),
       props: {},
     });
   }
@@ -139,6 +139,16 @@ class FilterClass implements Filter$.Any {
     });
   }
 
+  static key(key: string, options?: Filter$.KeyFilterOptions): Filter$.Any {
+    return new FilterClass({
+      type: 'object',
+      typename: null,
+      props: {},
+      metaKey: key,
+      metaVersion: options?.version,
+    });
+  }
+
   static props<T>(props: Filter$.Props<T>): Filter$.Filter<T> {
     return new FilterClass({
       type: 'object',
@@ -221,7 +231,7 @@ class FilterClass implements Filter$.Any {
     });
   }
 
-  static in<T>(...values: T[]): Filter$.Filter<T | undefined> {
+  static in<T>(...values: T[]): Filter$.Filter<T> {
     return new FilterClass({
       type: 'in',
       values,
@@ -235,7 +245,7 @@ class FilterClass implements Filter$.Any {
     });
   }
 
-  static between<T>(from: T, to: T): Filter$.Filter<unknown> {
+  static between<T>(from: T, to: T): Filter$.Filter<T> {
     return new FilterClass({
       type: 'range',
       from,
@@ -243,6 +253,47 @@ class FilterClass implements Filter$.Any {
     });
   }
 
+  static updated(range: { after?: Date | number; before?: Date | number }): Filter$.Any {
+    return FilterClass._timeRangeFilter('updatedAt', range);
+  }
+
+  static created(range: { after?: Date | number; before?: Date | number }): Filter$.Any {
+    return FilterClass._timeRangeFilter('createdAt', range);
+  }
+
+  static childOf(parents: unknown | DXN | (unknown | DXN)[], options?: { transitive?: boolean }): Filter$.Any {
+    const items = Array.isArray(parents) ? parents : [parents];
+    const dxns = items.map((item) => {
+      if (isDxnLike(item)) {
+        return item.toString();
+      }
+      throw new TypeError('childOf requires DXN values in query-lite');
+    });
+    return new FilterClass({
+      type: 'child-of',
+      parents: dxns,
+      transitive: options?.transitive ?? true,
+    });
+  }
+
+  private static _timeRangeFilter(
+    field: 'updatedAt' | 'createdAt',
+    range: { after?: Date | number; before?: Date | number },
+  ): Filter$.Any {
+    const toMs = (d: Date | number) => (typeof d === 'number' ? d : d.getTime());
+    const filters: Filter$.Any[] = [];
+    if (range.after != null) {
+      filters.push(new FilterClass({ type: 'timestamp', field, operator: 'gte', value: toMs(range.after) }));
+    }
+    if (range.before != null) {
+      filters.push(new FilterClass({ type: 'timestamp', field, operator: 'lte', value: toMs(range.before) }));
+    }
+    if (filters.length === 0) {
+      return FilterClass.everything();
+    }
+    return filters.length === 1 ? filters[0] : FilterClass.and(...filters);
+  }
+
   static not<F extends Filter$.Any>(filter: F): Filter$.Filter<Filter$.Type<F>> {
     return new FilterClass({
       type: 'not',
@@ -268,6 +319,11 @@ class FilterClass implements Filter$.Any {
     });
   }
 
+  /** Returns a human-readable string representation of a Filter AST. */
+  static pretty(filter: Filter$.Any): string {
+    return prettyFilter(filter.ast);
+  }
+
   private constructor(public readonly ast: QueryAST.Filter) {}
 
   '~Filter' = FilterClass.variance;
@@ -345,6 +401,22 @@ class QueryClass implements Query$.Any {
     });
   }
 
+  select(filter: Filter$.Any | Filter$.Props<any>): Query$.Any {
+    if (FilterClass.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,
+      });
+    }
+  }
+
   static type(schema: Schema.Schema.All | string, predicates?: Filter$.Props<unknown>): Query$.Any {
     return new QueryClass({
       type: 'select',
@@ -381,26 +453,40 @@ class QueryClass implements Query$.Any {
     return wrapper.from(source, options);
   }
 
-  constructor(public readonly ast: QueryAST.Query) {}
-
-  '~Query' = QueryClass.variance;
-
-  select(filter: Filter$.Any | Filter$.Props<any>): Query$.Any {
-    if (FilterClass.is(filter)) {
+  from(arg: any, options?: { includeFeeds?: boolean }): Query$.Any {
+    if (arg === 'all-accessible-spaces') {
       return new QueryClass({
-        type: 'filter',
-        selection: this.ast,
-        filter: filter.ast,
+        type: 'from',
+        query: this.ast,
+        from: {
+          _tag: 'scope',
+          scope: {
+            ...(options?.includeFeeds ? { allFeedsFromSpaces: true } : {}),
+          },
+        },
       });
-    } else {
+    }
+
+    if (_isScopeLike(arg)) {
       return new QueryClass({
-        type: 'filter',
-        selection: this.ast,
-        filter: FilterClass.props(filter).ast,
+        type: 'from',
+        query: this.ast,
+        from: { _tag: 'scope', scope: arg },
       });
     }
+
+    throw new TypeError('Database and Feed objects are not supported in query-lite sandbox');
+  }
+
+  /** Returns a human-readable string representation of a Query AST. */
+  static pretty(query: Query$.Any): string {
+    return prettyQuery(query.ast);
   }
 
+  constructor(public readonly ast: QueryAST.Query) {}
+
+  '~Query' = QueryClass.variance;
+
   reference(key: string): Query$.Any {
     return new QueryClass({
       type: 'reference-traversal',
@@ -490,36 +576,26 @@ class QueryClass implements Query$.Any {
     });
   }
 
-  from(arg: any, options?: { includeFeeds?: boolean }): Query$.Any {
-    if (arg === 'all-accessible-spaces') {
-      return new QueryClass({
-        type: 'from',
-        query: this.ast,
-        from: {
-          _tag: 'scope',
-          scope: {
-            ...(options?.includeFeeds ? { allQueuesFromSpaces: true } : {}),
-          },
-        },
-      });
-    }
+  options(options: QueryAST.QueryOptions): Query$.Any {
+    return new QueryClass({
+      type: 'options',
+      query: this.ast,
+      options,
+    });
+  }
 
-    if (_isScopeLike(arg)) {
+  debugLabel(label: string): Query$.Any {
+    if (this.ast.type === 'options') {
       return new QueryClass({
-        type: 'from',
-        query: this.ast,
-        from: { _tag: 'scope', scope: arg },
+        type: 'options',
+        query: this.ast.query,
+        options: { ...this.ast.options, debugLabel: label },
       });
     }
-
-    throw new TypeError('Database and Feed objects are not supported in query-lite sandbox');
-  }
-
-  options(options: QueryAST.QueryOptions): Query$.Any {
     return new QueryClass({
       type: 'options',
       query: this.ast,
-      options,
+      options: { debugLabel: label },
     });
   }
 }
@@ -532,13 +608,23 @@ const isRef = (obj: any): obj is Ref.Ref<any> => {
   return obj && typeof obj === 'object' && RefTypeId in obj;
 };
 
-const makeTypeDxn = (typename: string) => {
+const makeTypeDXN = (typename: string) => {
   assertArgument(typeof typename === 'string', 'typename');
   assertArgument(!typename.startsWith('dxn:'), 'typename');
   return `dxn:type:${typename}`;
 };
 
-const SCOPE_KEYS = new Set(['spaceIds', 'queues', 'allQueuesFromSpaces']);
+const isDxnLike = (value: unknown): value is DXN => {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'toString' in value &&
+    typeof value.toString === 'function' &&
+    value.toString().startsWith('dxn:')
+  );
+};
+
+const SCOPE_KEYS = new Set(['spaceIds', 'feeds', 'allFeedsFromSpaces']);
 
 const _isScopeLike = (value: unknown): value is QueryAST.Scope => {
   if (typeof value !== 'object' || value === null || Array.isArray(value)) {
@@ -546,3 +632,123 @@ const _isScopeLike = (value: unknown): value is QueryAST.Scope => {
   }
   return Object.keys(value).every((key) => SCOPE_KEYS.has(key));
 };
+
+const prettyFilter = (filter: QueryAST.Filter): string => {
+  switch (filter.type) {
+    case 'object': {
+      const parts: string[] = [];
+      if (filter.typename !== null) {
+        parts.push(JSON.stringify(filter.typename));
+      }
+      const propEntries = Object.entries(filter.props);
+      if (propEntries.length > 0) {
+        const propsStr = propEntries.map(([k, v]) => `${k}: ${prettyFilter(v)}`).join(', ');
+        parts.push(`{ ${propsStr} }`);
+      }
+      if (filter.id !== undefined) {
+        parts.push(`id: [${filter.id.join(', ')}]`);
+      }
+      return parts.length > 0 ? `Filter.type(${parts.join(', ')})` : 'Filter.everything()';
+    }
+    case 'compare':
+      return `Filter.${filter.operator}(${JSON.stringify(filter.value)})`;
+    case 'in':
+      return `Filter.in(${filter.values.map((v) => JSON.stringify(v)).join(', ')})`;
+    case 'contains':
+      return `Filter.contains(${JSON.stringify(filter.value)})`;
+    case 'range':
+      return `Filter.between(${JSON.stringify(filter.from)}, ${JSON.stringify(filter.to)})`;
+    case 'text-search':
+      return `Filter.text(${JSON.stringify(filter.text)})`;
+    case 'tag':
+      return `Filter.tag(${JSON.stringify(filter.tag)})`;
+    case 'child-of':
+      return `Filter.childOf([${filter.parents.map((parent) => JSON.stringify(parent)).join(', ')}], { transitive: ${filter.transitive} })`;
+    case 'timestamp':
+      return `Filter.${filter.field}.${filter.operator}(${filter.value})`;
+    case 'not':
+      return `Filter.not(${prettyFilter(filter.filter)})`;
+    case 'and':
+      return `Filter.and(${filter.filters.map(prettyFilter).join(', ')})`;
+    case 'or':
+      return `Filter.or(${filter.filters.map(prettyFilter).join(', ')})`;
+  }
+};
+
+const prettyQuery = (query: QueryAST.Query): string => {
+  switch (query.type) {
+    case 'select':
+      return `Query.select(${prettyFilter(query.filter)})`;
+    case 'filter':
+      return `${prettyQuery(query.selection)}.select(${prettyFilter(query.filter)})`;
+    case 'reference-traversal':
+      return `${prettyQuery(query.anchor)}.reference(${JSON.stringify(query.property)})`;
+    case 'incoming-references': {
+      const args: string[] = [];
+      if (query.typename !== null) {
+        args.push(JSON.stringify(query.typename));
+      }
+      if (query.property !== null) {
+        args.push(JSON.stringify(query.property));
+      }
+      return `${prettyQuery(query.anchor)}.referencedBy(${args.join(', ')})`;
+    }
+    case 'relation': {
+      const method =
+        query.direction === 'outgoing' ? 'sourceOf' : query.direction === 'incoming' ? 'targetOf' : 'relationOf';
+      const filterStr = query.filter !== undefined ? prettyFilter(query.filter) : '';
+      return `${prettyQuery(query.anchor)}.${method}(${filterStr})`;
+    }
+    case 'relation-traversal':
+      return `${prettyQuery(query.anchor)}.${query.direction}()`;
+    case 'hierarchy-traversal':
+      return query.direction === 'to-parent'
+        ? `${prettyQuery(query.anchor)}.parent()`
+        : `${prettyQuery(query.anchor)}.children()`;
+    case 'union':
+      return `Query.all(${query.queries.map(prettyQuery).join(', ')})`;
+    case 'set-difference':
+      return `Query.without(${prettyQuery(query.source)}, ${prettyQuery(query.exclude)})`;
+    case 'order': {
+      const orders = query.order.map((o) => {
+        if (o.kind === 'natural') {
+          return 'Order.natural';
+        }
+        if (o.kind === 'rank') {
+          return `Order.rank(${JSON.stringify(o.direction)})`;
+        }
+        return `Order.property(${JSON.stringify(o.property)}, ${JSON.stringify(o.direction)})`;
+      });
+      return `${prettyQuery(query.query)}.orderBy(${orders.join(', ')})`;
+    }
+    case 'options': {
+      const parts: string[] = [];
+      if (query.options.deleted !== undefined) {
+        parts.push(`deleted: ${JSON.stringify(query.options.deleted)}`);
+      }
+      if (query.options.debugLabel !== undefined) {
+        parts.push(`debugLabel: ${JSON.stringify(query.options.debugLabel)}`);
+      }
+      return `${prettyQuery(query.query)}.options({ ${parts.join(', ')} })`;
+    }
+    case 'from': {
+      if (query.from._tag === 'scope') {
+        const scope = query.from.scope;
+        const parts: string[] = [];
+        if (scope.spaceIds !== undefined) {
+          parts.push(`spaceIds: [${scope.spaceIds.join(', ')}]`);
+        }
+        if (scope.feeds !== undefined) {
+          parts.push(`feeds: [${scope.feeds.join(', ')}]`);
+        }
+        if (scope.allFeedsFromSpaces !== undefined) {
+          parts.push(`allFeedsFromSpaces: ${scope.allFeedsFromSpaces}`);
+        }
+        return `${prettyQuery(query.query)}.from({ ${parts.join(', ')} })`;
+      }
+      return `${prettyQuery(query.query)}.from(${prettyQuery(query.from.query)})`;
+    }
+    case 'limit':
+      return `${prettyQuery(query.query)}.limit(${query.limit})`;
+  }
+};

package/src/sandbox/query-sandbox.test.ts

@@ -16,37 +16,37 @@ describe('QuerySandbox', () => {
 
   test('works', { timeout: 10_000 }, async () => {
     const ast = sandbox.eval(trim`
-      Query.select(Filter.typename('dxos.org/type/Person'))
+      Query.select(Filter.typename('org.dxos.type.person'))
     `);
-    expect(ast).toEqual(Query.select(Filter.typename('dxos.org/type/Person')).ast);
+    expect(ast).toEqual(Query.select(Filter.typename('org.dxos.type.person')).ast);
   });
 
   test('works with just Filter passed in', () => {
     const ast = sandbox.eval(trim`
-      Filter.typename('dxos.org/type/Person')
+      Filter.typename('org.dxos.type.person')
     `);
-    expect(ast).toEqual(Query.select(Filter.typename('dxos.org/type/Person')).ast);
+    expect(ast).toEqual(Query.select(Filter.typename('org.dxos.type.person')).ast);
   });
 
   test('Order', () => {
     const ast = sandbox.eval(trim`
-      Query.type('dxos.org/type/Person').orderBy(Order.property('name', 'desc'))
+      Query.type('org.dxos.type.person').orderBy(Order.property('name', 'desc'))
     `);
-    expect(ast).toEqual(Query.type('dxos.org/type/Person').orderBy(Order.property('name', 'desc')).ast);
+    expect(ast).toEqual(Query.type('org.dxos.type.person').orderBy(Order.property('name', 'desc')).ast);
   });
 
   test('traversal', () => {
     const ast = sandbox.eval(trim`
-      Query.select(Filter.type('dxos.org/type/Person', { jobTitle: 'investor' }))
+      Query.select(Filter.type('org.dxos.type.person', { jobTitle: 'investor' }))
         .reference('organization')
-        .targetOf('dxos.org/relation/HasSubject')
+        .targetOf('org.dxos.relation.hasSubject')
         .source()
     `);
 
     expect(ast).toEqual(
-      Query.select(Filter.type('dxos.org/type/Person', { jobTitle: 'investor' }))
+      Query.select(Filter.type('org.dxos.type.person', { jobTitle: 'investor' }))
         .reference('organization')
-        .targetOf('dxos.org/relation/HasSubject')
+        .targetOf('org.dxos.relation.hasSubject')
         .source().ast,
     );
   });

package/src/sandbox/query-sandbox.ts

@@ -49,7 +49,7 @@ export class QuerySandbox extends Resource {
 
   /**
    * Evaluates the query code.
-   * @param queryCode Example: `Query.select(Filter.typename('dxos.org/type/Person'))`
+   * @param queryCode Example: `Query.select(Filter.typename('org.dxos.type.person'))`
    */
   eval(queryCode: string): QueryAST.Query {
     using context = this.#runtime.newContext();