@dxos/echo-query 0.8.4-main.c4373fc → 0.8.4-main.d05673bc65

package/src/query-lite/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './query-lite';

package/src/{query-env/index.ts → query-lite/query-lite.ts}

@@ -4,16 +4,21 @@
 
 import type * as Schema from 'effect/Schema';
 
-import type { Filter, Order, Query, Ref } from '@dxos/echo';
-import type * as Echo from '@dxos/echo';
+import type { Filter as Filter$, Order as Order$, Query as Query$, Ref } from '@dxos/echo';
 import type { ForeignKey, QueryAST } from '@dxos/echo-protocol';
 import { assertArgument } from '@dxos/invariant';
 import type { DXN, ObjectId } from '@dxos/keys';
 
-class OrderClass implements Echo.Order<any> {
-  private static variance: Echo.Order<any>['~Order'] = {} as Echo.Order<any>['~Order'];
+//
+// Light-weight implementation of query execution.
+//
+
+// TODO(wittjosiah): The `export * as ...` syntax causes tsdown to genereate multiple files which breaks the sandbox.
 
-  static is(value: unknown): value is Echo.Order<any> {
+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;
   }
 
@@ -21,27 +26,33 @@ class OrderClass implements Echo.Order<any> {
 
   '~Order' = OrderClass.variance;
 }
+
 namespace Order1 {
-  export const natural: Echo.Order<any> = new OrderClass({ kind: 'natural' });
-  export const property = <T>(property: keyof T & string, direction: QueryAST.OrderDirection): Echo.Order<T> =>
+  export const natural: Order$.Any = new OrderClass({ kind: 'natural' });
+  export const property = <T>(property: keyof T & string, direction: QueryAST.OrderDirection): Order$.Order<T> =>
     new OrderClass({
       kind: 'property',
       property,
       direction,
     });
+  export const rank = <T>(direction: QueryAST.OrderDirection = 'desc'): Order$.Order<T> =>
+    new OrderClass({
+      kind: 'rank',
+      direction,
+    });
 }
 
-const Order2: typeof Echo.Order = Order1;
+const Order2: typeof Order$ = Order1;
 export { Order2 as Order };
 
-class FilterClass implements Echo.Filter<any> {
-  private static variance: Echo.Filter<any>['~Filter'] = {} as Echo.Filter<any>['~Filter'];
+class FilterClass implements Filter$.Any {
+  private static 'variance': Filter$.Any['~Filter'] = {} as Filter$.Any['~Filter'];
 
-  static is(value: unknown): value is Echo.Filter<any> {
+  static is(value: unknown): value is Filter$.Any {
     return typeof value === 'object' && value !== null && '~Filter' in value;
   }
 
-  static fromAst(ast: QueryAST.Filter): Filter<any> {
+  static fromAst(ast: QueryAST.Filter): Filter$.Any {
     return new FilterClass(ast);
   }
 
@@ -72,7 +83,7 @@ class FilterClass implements Echo.Filter<any> {
     });
   }
 
-  static ids(...ids: ObjectId[]): Echo.Filter<any> {
+  static id(...ids: ObjectId[]): Filter$.Any {
     // assertArgument(
     //   ids.every((id) => ObjectId.isValid(id)),
     //   'ids',
@@ -93,8 +104,8 @@ class FilterClass implements Echo.Filter<any> {
 
   static type<S extends Schema.Schema.All>(
     schema: S | string,
-    props?: Echo.Filter.Props<Schema.Schema.Type<S>>,
-  ): Echo.Filter<Schema.Schema.Type<S>> {
+    props?: Filter$.Props<Schema.Schema.Type<S>>,
+  ): Filter$.Filter<Schema.Schema.Type<S>> {
     if (typeof schema !== 'string') {
       throw new TypeError('expected typename as the first paramter');
     }
@@ -105,7 +116,7 @@ class FilterClass implements Echo.Filter<any> {
     });
   }
 
-  static typename(typename: string): Echo.Filter<any> {
+  static typename(typename: string): Filter$.Any {
     return new FilterClass({
       type: 'object',
       typename: makeTypeDxn(typename),
@@ -113,7 +124,7 @@ class FilterClass implements Echo.Filter<any> {
     });
   }
 
-  static typeDXN(dxn: DXN): Echo.Filter<any> {
+  static typeDXN(dxn: DXN): Filter$.Any {
     return new FilterClass({
       type: 'object',
       typename: dxn.toString(),
@@ -121,14 +132,14 @@ class FilterClass implements Echo.Filter<any> {
     });
   }
 
-  static tag(tag: string): Echo.Filter<any> {
+  static tag(tag: string): Filter$.Any {
     return new FilterClass({
       type: 'tag',
       tag,
     });
   }
 
-  static props<T>(props: Echo.Filter.Props<T>): Echo.Filter<T> {
+  static props<T>(props: Filter$.Props<T>): Filter$.Filter<T> {
     return new FilterClass({
       type: 'object',
       typename: null,
@@ -136,7 +147,7 @@ class FilterClass implements Echo.Filter<any> {
     });
   }
 
-  static text(text: string, options?: Echo.Query.TextSearchOptions): Echo.Filter<any> {
+  static text(text: string, options?: Filter$.TextSearchOptions): Filter$.Any {
     return new FilterClass({
       type: 'text-search',
       text,
@@ -147,7 +158,7 @@ class FilterClass implements Echo.Filter<any> {
   static foreignKeys<S extends Schema.Schema.All>(
     schema: S | string,
     keys: ForeignKey[],
-  ): Echo.Filter<Schema.Schema.Type<S>> {
+  ): Filter$.Filter<Schema.Schema.Type<S>> {
     assertArgument(typeof schema === 'string', 'schema');
     assertArgument(!schema.startsWith('dxn:'), 'schema');
     return new FilterClass({
@@ -158,7 +169,7 @@ class FilterClass implements Echo.Filter<any> {
     });
   }
 
-  static eq<T>(value: T): Echo.Filter<T> {
+  static eq<T>(value: T): Filter$.Filter<T | undefined> {
     if (!isRef(value) && typeof value === 'object' && value !== null) {
       throw new TypeError('Cannot use object as a value for eq filter');
     }
@@ -170,7 +181,7 @@ class FilterClass implements Echo.Filter<any> {
     });
   }
 
-  static neq<T>(value: T): Echo.Filter<T> {
+  static neq<T>(value: T): Filter$.Filter<T | undefined> {
     return new FilterClass({
       type: 'compare',
       operator: 'neq',
@@ -178,7 +189,7 @@ class FilterClass implements Echo.Filter<any> {
     });
   }
 
-  static gt<T>(value: T): Echo.Filter<T> {
+  static gt<T>(value: T): Filter$.Filter<T | undefined> {
     return new FilterClass({
       type: 'compare',
       operator: 'gt',
@@ -186,7 +197,7 @@ class FilterClass implements Echo.Filter<any> {
     });
   }
 
-  static gte<T>(value: T): Echo.Filter<T> {
+  static gte<T>(value: T): Filter$.Filter<T | undefined> {
     return new FilterClass({
       type: 'compare',
       operator: 'gte',
@@ -194,7 +205,7 @@ class FilterClass implements Echo.Filter<any> {
     });
   }
 
-  static lt<T>(value: T): Echo.Filter<T> {
+  static lt<T>(value: T): Filter$.Filter<T | undefined> {
     return new FilterClass({
       type: 'compare',
       operator: 'lt',
@@ -202,7 +213,7 @@ class FilterClass implements Echo.Filter<any> {
     });
   }
 
-  static lte<T>(value: T): Echo.Filter<T> {
+  static lte<T>(value: T): Filter$.Filter<T | undefined> {
     return new FilterClass({
       type: 'compare',
       operator: 'lte',
@@ -210,21 +221,21 @@ class FilterClass implements Echo.Filter<any> {
     });
   }
 
-  static in<T>(...values: T[]): Echo.Filter<T> {
+  static in<T>(...values: T[]): Filter$.Filter<T | undefined> {
     return new FilterClass({
       type: 'in',
       values,
     });
   }
 
-  static contains<T>(value: T): Echo.Filter<T[]> {
+  static contains<T>(value: T): Filter$.Filter<readonly T[] | undefined> {
     return new FilterClass({
       type: 'contains',
       value,
     });
   }
 
-  static between<T>(from: T, to: T): Echo.Filter<T> {
+  static between<T>(from: T, to: T): Filter$.Filter<unknown> {
     return new FilterClass({
       type: 'range',
       from,
@@ -232,21 +243,25 @@ class FilterClass implements Echo.Filter<any> {
     });
   }
 
-  static not<F extends Echo.Filter.Any>(filter: F): Echo.Filter<Echo.Filter.Type<F>> {
+  static not<F extends Filter$.Any>(filter: F): Filter$.Filter<Filter$.Type<F>> {
     return new FilterClass({
       type: 'not',
       filter: filter.ast,
     });
   }
 
-  static and<T>(...filters: Echo.Filter<T>[]): Echo.Filter<T> {
+  static and<Filters extends readonly Filter$.Any[]>(
+    ...filters: Filters
+  ): Filter$.Filter<Filter$.Type<Filters[number]>> {
     return new FilterClass({
       type: 'and',
       filters: filters.map((f) => f.ast),
     });
   }
 
-  static or<T>(...filters: Echo.Filter<T>[]): Echo.Filter<T> {
+  static or<Filters extends readonly Filter$.Any[]>(
+    ...filters: Filters
+  ): Filter$.Filter<Filter$.Type<Filters[number]>> {
     return new FilterClass({
       type: 'or',
       filters: filters.map((f) => f.ast),
@@ -258,7 +273,7 @@ class FilterClass implements Echo.Filter<any> {
   '~Filter' = FilterClass.variance;
 }
 
-export const Filter1: typeof Echo.Filter = FilterClass;
+export const Filter1: typeof Filter$ = FilterClass;
 export { Filter1 as Filter };
 
 /**
@@ -267,7 +282,7 @@ export { Filter1 as Filter };
 // 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: Echo.Filter.Props<any>): Pick<QueryAST.FilterObject, 'id' | 'props'> => {
+const propsFilterToAst = (predicates: Filter$.Props<any>): Pick<QueryAST.FilterObject, 'id' | 'props'> => {
   let idFilter: readonly ObjectId[] | undefined;
   if ('id' in predicates) {
     assertArgument(
@@ -312,32 +327,32 @@ const processPredicate = (predicate: any): QueryAST.Filter => {
   return FilterClass.eq(predicate).ast;
 };
 
-class QueryClass implements Echo.Query<any> {
-  private static variance: Echo.Query<any>['~Query'] = {} as Echo.Query<any>['~Query'];
+class QueryClass implements Query$.Any {
+  private static 'variance': Query$.Any['~Query'] = {} as Query$.Any['~Query'];
 
-  static is(value: unknown): value is Echo.Query<any> {
+  static is(value: unknown): value is Query$.Any {
     return typeof value === 'object' && value !== null && '~Query' in value;
   }
 
-  static fromAst(ast: QueryAST.Query): Echo.Query<any> {
+  static fromAst(ast: QueryAST.Query): Query$.Any {
     return new QueryClass(ast);
   }
 
-  static select<F extends Echo.Filter.Any>(filter: F): Echo.Query<Echo.Filter.Type<F>> {
+  static select<F extends Filter$.Any>(filter: F): Query$.Query<Filter$.Type<F>> {
     return new QueryClass({
       type: 'select',
       filter: filter.ast,
     });
   }
 
-  static type(schema: Schema.Schema.All | string, predicates?: Echo.Filter.Props<unknown>): Query<any> {
+  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> {
+  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())',
@@ -349,7 +364,7 @@ class QueryClass implements Echo.Query<any> {
     });
   }
 
-  static without<T>(source: Query<T>, exclude: Query<T>): Query<T> {
+  static without<T>(source: Query$.Query<T>, exclude: Query$.Query<T>): Query$.Query<T> {
     return new QueryClass({
       type: 'set-difference',
       source: source.ast,
@@ -357,11 +372,20 @@ class QueryClass implements Echo.Query<any> {
     });
   }
 
+  static from(source: any, options?: { includeFeeds?: boolean }): Query$.Any {
+    const baseQuery: QueryAST.Query = {
+      type: 'select',
+      filter: FilterClass.everything().ast,
+    };
+    const wrapper = new QueryClass(baseQuery);
+    return wrapper.from(source, options);
+  }
+
   constructor(public readonly ast: QueryAST.Query) {}
 
   '~Query' = QueryClass.variance;
 
-  select(filter: Filter<any> | Filter.Props<any>): Query<any> {
+  select(filter: Filter$.Any | Filter$.Props<any>): Query$.Any {
     if (FilterClass.is(filter)) {
       return new QueryClass({
         type: 'filter',
@@ -377,7 +401,7 @@ class QueryClass implements Echo.Query<any> {
     }
   }
 
-  reference(key: string): Query<any> {
+  reference(key: string): Query$.Any {
     return new QueryClass({
       type: 'reference-traversal',
       anchor: this.ast,
@@ -385,36 +409,40 @@ class QueryClass implements Echo.Query<any> {
     });
   }
 
-  referencedBy(target: Schema.Schema.All | string, key: string): Query<any> {
-    assertArgument(typeof target === 'string', 'target');
-    assertArgument(!target.startsWith('dxn:'), 'target');
+  referencedBy(target?: Schema.Schema.All | string, key?: string): Query$.Any {
+    const typename =
+      target !== undefined
+        ? (assertArgument(typeof target === 'string', 'target'),
+          assertArgument(!target.startsWith('dxn:'), 'target'),
+          target)
+        : null;
     return new QueryClass({
       type: 'incoming-references',
       anchor: this.ast,
-      property: key,
-      typename: target,
+      property: key ?? null,
+      typename,
     });
   }
 
-  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,
       direction: 'outgoing',
-      filter: FilterClass.type(relation, predicates).ast,
+      filter: relation !== undefined ? FilterClass.type(relation, predicates).ast : undefined,
     });
   }
 
-  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,
       direction: 'incoming',
-      filter: FilterClass.type(relation, predicates).ast,
+      filter: relation !== undefined ? FilterClass.type(relation, predicates).ast : undefined,
     });
   }
 
-  source(): Query<any> {
+  source(): Query$.Any {
     return new QueryClass({
       type: 'relation-traversal',
       anchor: this.ast,
@@ -422,7 +450,7 @@ class QueryClass implements Echo.Query<any> {
     });
   }
 
-  target(): Query<any> {
+  target(): Query$.Any {
     return new QueryClass({
       type: 'relation-traversal',
       anchor: this.ast,
@@ -430,7 +458,23 @@ class QueryClass implements Echo.Query<any> {
     });
   }
 
-  orderBy(...order: Order<any>[]): Query<any> {
+  parent(): Query$.Any {
+    return new QueryClass({
+      type: 'hierarchy-traversal',
+      anchor: this.ast,
+      direction: 'to-parent',
+    });
+  }
+
+  children(): Query$.Any {
+    return new QueryClass({
+      type: 'hierarchy-traversal',
+      anchor: this.ast,
+      direction: 'to-children',
+    });
+  }
+
+  orderBy(...order: Order$.Any[]): Query$.Any {
     return new QueryClass({
       type: 'order',
       query: this.ast,
@@ -438,7 +482,40 @@ class QueryClass implements Echo.Query<any> {
     });
   }
 
-  options(options: QueryAST.QueryOptions): Query<any> {
+  limit(limit: number): Query$.Any {
+    return new QueryClass({
+      type: 'limit',
+      query: this.ast,
+      limit,
+    });
+  }
+
+  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 } : {}),
+          },
+        },
+      });
+    }
+
+    if (_isScopeLike(arg)) {
+      return new QueryClass({
+        type: 'from',
+        query: this.ast,
+        from: { _tag: 'scope', scope: arg },
+      });
+    }
+
+    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,
@@ -447,7 +524,7 @@ class QueryClass implements Echo.Query<any> {
   }
 }
 
-export const Query1: typeof Echo.Query = QueryClass;
+export const Query1: typeof Query$ = QueryClass;
 export { Query1 as Query };
 
 const RefTypeId: unique symbol = Symbol('@dxos/echo-query/Ref');
@@ -460,3 +537,12 @@ const makeTypeDxn = (typename: string) => {
   assertArgument(!typename.startsWith('dxn:'), 'typename');
   return `dxn:type:${typename}`;
 };
+
+const SCOPE_KEYS = new Set(['spaceIds', 'queues', 'allQueuesFromSpaces']);
+
+const _isScopeLike = (value: unknown): value is QueryAST.Scope => {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return false;
+  }
+  return Object.keys(value).every((key) => SCOPE_KEYS.has(key));
+};

package/src/sandbox/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './query-sandbox';

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

@@ -5,6 +5,7 @@
 import { afterAll, beforeAll, describe, expect, test } from 'vitest';
 
 import { Filter, Order, Query } from '@dxos/echo';
+import { trim } from '@dxos/util';
 
 import { QuerySandbox } from './query-sandbox';
 
@@ -14,38 +15,38 @@ describe('QuerySandbox', () => {
   afterAll(() => sandbox.close());
 
   test('works', { timeout: 10_000 }, async () => {
-    const ast = sandbox.eval(`
-      Query.select(Filter.typename('dxos.org/type/Person'))
+    const ast = sandbox.eval(trim`
+      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(`
-      Filter.typename('dxos.org/type/Person')
+    const ast = sandbox.eval(trim`
+      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(`
-      Query.type('dxos.org/type/Person').orderBy(Order.property('name', 'desc'))
+    const ast = sandbox.eval(trim`
+      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(`
-      Query.select(Filter.type('example.com/type/Person', { jobTitle: 'investor' }))
+    const ast = sandbox.eval(trim`
+      Query.select(Filter.type('org.dxos.type.person', { jobTitle: 'investor' }))
         .reference('organization')
-        .targetOf('example.com/relation/ResearchOn')
+        .targetOf('org.dxos.relation.has-subject')
         .source()
     `);
 
     expect(ast).toEqual(
-      Query.select(Filter.type('example.com/type/Person', { jobTitle: 'investor' }))
+      Query.select(Filter.type('org.dxos.type.person', { jobTitle: 'investor' }))
         .reference('organization')
-        .targetOf('example.com/relation/ResearchOn')
+        .targetOf('org.dxos.relation.has-subject')
         .source().ast,
     );
   });

package/src/sandbox/query-sandbox.ts

@@ -7,7 +7,7 @@ import { Query, type QueryAST } from '@dxos/echo';
 import { trim } from '@dxos/util';
 import { type QuickJSRuntime, type QuickJSWASMModule, createQuickJS } from '@dxos/vendor-quickjs';
 
-import envCode from '#query-env?raw';
+import envCode from '#query-lite?raw';
 
 import { unwrapResult } from './quickjs';
 
@@ -34,7 +34,7 @@ export class QuerySandbox extends Resource {
     this.#runtime = quickJS.newRuntime({
       moduleLoader: (moduleName, _context) => {
         switch (moduleName) {
-          case 'dxos:query-env':
+          case 'dxos:query-lite':
             return envCode;
           default:
             throw new Error(`Module not found: ${moduleName}`);
@@ -49,12 +49,12 @@ 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();
     const globals = trim`
-      import { Filter, Order, Query } from 'dxos:query-env';
+      import { Filter, Order, Query } from 'dxos:query-lite';
       globalThis.Filter = Filter;
       globalThis.Order = Order;
       globalThis.Query = Query;

package/src/sandbox/quickjs.ts

@@ -17,8 +17,7 @@ export const unwrapResult = <T>(context: QuickJSContext, result: SuccessOrFail<T
     if (
       typeof contextError === 'object' &&
       typeof contextError.name === 'string' &&
-      typeof contextError.message === 'string' &&
-      typeof contextError.stack === 'string'
+      typeof contextError.message === 'string'
     ) {
       const error = new Error(contextError.message);
       Object.defineProperty(error, 'name', { value: contextError.name });