@dxos/echo 0.8.4-main.c85a9c8dae → 0.8.4-main.cb12b3f963

package/src/Query.test.ts

@@ -6,7 +6,7 @@ import * as Schema from 'effect/Schema';
 import { describe, expect, test } from 'vitest';
 
 import { QueryAST } from '@dxos/echo-protocol';
-import { DXN } from '@dxos/keys';
+import { DXN, ObjectId, SpaceId } from '@dxos/keys';
 import { log } from '@dxos/log';
 
 import * as Dataset from './Dataset';
@@ -98,7 +98,7 @@ describe('query api', () => {
       expect(ObjectsReferencingFred.ast).toMatchObject({
         type: 'incoming-references',
         property: null,
-        typename: 'dxn:type:example.com/type/Task:0.1.0',
+        typename: 'dxn:type:com.example.type.task:0.1.0',
       });
     });
 
@@ -150,17 +150,17 @@ describe('query api', () => {
               {
                 "props": {},
                 "type": "object",
-                "typename": "dxn:type:dxos.org/type/Feed:0.1.0",
+                "typename": "dxn:type:org.dxos.type.feed:0.1.0",
               },
               {
                 "props": {},
                 "type": "object",
-                "typename": "dxn:type:dxos.org/type/Collection:0.1.0",
+                "typename": "dxn:type:org.dxos.type.collection:0.1.0",
               },
               {
                 "props": {},
                 "type": "object",
-                "typename": "dxn:type:dxos.org/type/View:0.5.0",
+                "typename": "dxn:type:org.dxos.type.view:0.1.0",
               },
             ],
             "type": "or",
@@ -183,17 +183,17 @@ describe('query api', () => {
               {
                 "props": {},
                 "type": "object",
-                "typename": "dxn:type:dxos.org/type/Feed:0.1.0",
+                "typename": "dxn:type:org.dxos.type.feed:0.1.0",
               },
               {
                 "props": {},
                 "type": "object",
-                "typename": "dxn:type:dxos.org/type/Collection:0.1.0",
+                "typename": "dxn:type:org.dxos.type.collection:0.1.0",
               },
               {
                 "props": {},
                 "type": "object",
-                "typename": "dxn:type:dxos.org/type/View:0.5.0",
+                "typename": "dxn:type:org.dxos.type.view:0.1.0",
               },
             ],
             "type": "or",
@@ -258,7 +258,7 @@ describe('query api', () => {
             "id": undefined,
             "props": {},
             "type": "object",
-            "typename": "dxn:type:example.com/type/Person:0.1.0",
+            "typename": "dxn:type:com.example.type.person:0.1.0",
           },
           "type": "select",
         },
@@ -281,7 +281,7 @@ describe('query api', () => {
           },
         },
         type: 'object',
-        typename: 'dxn:type:example.com/type/Task:0.1.0',
+        typename: 'dxn:type:com.example.type.task:0.1.0',
       });
       log('tasksByFred', { ast: tasksByFred.ast });
     });
@@ -300,13 +300,13 @@ describe('query api', () => {
               "id": undefined,
               "props": {},
               "type": "object",
-              "typename": "dxn:type:example.com/type/Organization:0.1.0",
+              "typename": "dxn:type:com.example.type.organization:0.1.0",
             },
             {
               "id": undefined,
               "props": {},
               "type": "object",
-              "typename": "dxn:type:example.com/type/Person:0.1.0",
+              "typename": "dxn:type:com.example.type.person:0.1.0",
             },
           ],
           "type": "or",
@@ -331,13 +331,13 @@ describe('query api', () => {
                 "id": undefined,
                 "props": {},
                 "type": "object",
-                "typename": "dxn:type:example.com/type/Organization:0.1.0",
+                "typename": "dxn:type:com.example.type.organization:0.1.0",
               },
               {
                 "id": undefined,
                 "props": {},
                 "type": "object",
-                "typename": "dxn:type:example.com/type/Person:0.1.0",
+                "typename": "dxn:type:com.example.type.person:0.1.0",
               },
             ],
             "type": "or",
@@ -365,7 +365,7 @@ describe('query api', () => {
             "id": undefined,
             "props": {},
             "type": "object",
-            "typename": "dxn:type:example.com/type/Task:0.1.0",
+            "typename": "dxn:type:com.example.type.task:0.1.0",
           },
           "type": "select",
         },
@@ -388,7 +388,7 @@ describe('query api', () => {
               "id": undefined,
               "props": {},
               "type": "object",
-              "typename": "dxn:type:example.com/type/Task:0.1.0",
+              "typename": "dxn:type:com.example.type.task:0.1.0",
             },
             "type": "select",
           },
@@ -408,7 +408,7 @@ describe('query api', () => {
               "id": undefined,
               "props": {},
               "type": "object",
-              "typename": "dxn:type:example.com/type/Task:0.1.0",
+              "typename": "dxn:type:com.example.type.task:0.1.0",
             },
             "type": "select",
           },
@@ -436,7 +436,7 @@ describe('query api', () => {
                 "id": undefined,
                 "props": {},
                 "type": "object",
-                "typename": "dxn:type:example.com/type/Task:0.1.0",
+                "typename": "dxn:type:com.example.type.task:0.1.0",
               },
               "type": "select",
             },
@@ -463,7 +463,7 @@ describe('query api', () => {
                   "id": undefined,
                   "props": {},
                   "type": "object",
-                  "typename": "dxn:type:example.com/type/Person:0.1.0",
+                  "typename": "dxn:type:com.example.type.person:0.1.0",
                 },
                 "type": "select",
               },
@@ -476,7 +476,7 @@ describe('query api', () => {
                   "id": undefined,
                   "props": {},
                   "type": "object",
-                  "typename": "dxn:type:example.com/type/Organization:0.1.0",
+                  "typename": "dxn:type:com.example.type.organization:0.1.0",
                 },
                 "type": "select",
               },
@@ -503,7 +503,7 @@ describe('query api', () => {
               "id": undefined,
               "props": {},
               "type": "object",
-              "typename": "dxn:type:example.com/type/Person:0.1.0",
+              "typename": "dxn:type:com.example.type.person:0.1.0",
             },
             "type": "select",
           },
@@ -531,7 +531,7 @@ describe('query api', () => {
               "id": undefined,
               "props": {},
               "type": "object",
-              "typename": "dxn:type:example.com/type/Person:0.1.0",
+              "typename": "dxn:type:com.example.type.person:0.1.0",
             },
             "type": "select",
           },
@@ -560,12 +560,20 @@ describe('query api', () => {
       });
     });
 
-    test('Query.type(...).from(feed) sets queue scope', () => {
-      const feed = Feed.make({ name: 'test-feed' });
-      const queueDxn = DXN.parse('dxn:echo:test-space:test-queue');
-      Obj.change(feed, (mutable) => {
-        Obj.getMeta(mutable).keys.push({ source: Feed.DXN_KEY, id: queueDxn.toString() });
-      });
+    test('Query.type(...).from(feed) sets queue scope', async () => {
+      const spaceId = SpaceId.random();
+      const feedId = ObjectId.random();
+      const feedDxn = DXN.parse(`dxn:echo:${spaceId}:${feedId}`);
+      const feed = (await Obj.fromJSON(
+        {
+          '@type': 'dxn:type:org.dxos.type.feed:0.1.0',
+          id: feedId,
+          name: 'test-feed',
+        },
+        { dxn: feedDxn },
+      )) as Feed.Feed;
+
+      const expectedQueueDxn = new DXN(DXN.kind.QUEUE, ['data', spaceId, feedId]);
 
       const query = Query.type(TestSchema.Person).from(feed);
       Schema.validateSync(QueryAST.Query)(query.ast);
@@ -574,19 +582,73 @@ describe('query api', () => {
         from: {
           _tag: 'scope',
           scope: {
-            queues: [queueDxn.toString()],
+            queues: [expectedQueueDxn.toString()],
           },
         },
         query: {
           type: 'select',
           filter: {
             type: 'object',
-            typename: 'dxn:type:example.com/type/Person:0.1.0',
+            typename: 'dxn:type:com.example.type.person:0.1.0',
           },
         },
       });
     });
 
+    test('Query.from(non-feed) throws TypeError', () => {
+      const person = Obj.make(TestSchema.Person, { name: 'Fred' });
+      expect(() => Query.select(Filter.type(TestSchema.Person)).from(person as any)).toThrow(TypeError);
+      expect(() => Query.select(Filter.type(TestSchema.Person)).from(person as any)).toThrow(
+        /Query\.from\(\) expects Feed objects/,
+      );
+    });
+
+    test('Query.from(undefined) throws TypeError', () => {
+      expect(() => Query.select(Filter.type(TestSchema.Person)).from(undefined as any)).toThrow(TypeError);
+      expect(() => Query.select(Filter.type(TestSchema.Person)).from(undefined as any)).toThrow(
+        /Query\.from\(\) requires a valid data source argument/,
+      );
+    });
+
+    test('Query.from(null) throws TypeError', () => {
+      expect(() => Query.select(Filter.type(TestSchema.Person)).from(null as any)).toThrow(TypeError);
+      expect(() => Query.select(Filter.type(TestSchema.Person)).from(null as any)).toThrow(
+        /Query\.from\(\) requires a valid data source argument/,
+      );
+    });
+
+    test('Query.pretty surfaces debugLabel from options', () => {
+      const query = Query.select(Filter.type(TestSchema.Person)).debugLabel('my-label');
+      expect(Query.pretty(query)).toContain('debugLabel');
+      expect(Query.pretty(query)).toContain('"my-label"');
+    });
+
+    test('Query.debugLabel merges onto existing options clause', () => {
+      const query = Query.select(Filter.type(TestSchema.Person))
+        .options({ deleted: 'exclude' })
+        .debugLabel('timer-probe');
+      const pretty = Query.pretty(query);
+      expect(pretty).toContain('deleted');
+      expect(pretty).toContain('debugLabel');
+      expect(pretty).toContain('"timer-probe"');
+    });
+
+    test('Query.pretty returns human-readable query string', () => {
+      const query = Query.select(Filter.type(TestSchema.Person, { name: 'Fred' }));
+      const pretty = Query.pretty(query);
+      expect(pretty).toContain('Query.select');
+      expect(pretty).toContain('Filter.type');
+      expect(pretty).toContain('com.example.type.person');
+    });
+
+    test('Query.pretty handles complex queries', () => {
+      const query = Query.select(Filter.and(Filter.type(TestSchema.Person), Filter.id(ObjectId.random()))).limit(10);
+      const pretty = Query.pretty(query);
+      expect(pretty).toContain('Query.select');
+      expect(pretty).toContain('Filter.and');
+      expect(pretty).toContain('limit(10)');
+    });
+
     test.skip('chain', () => {
       // NOTE: Can't support props without type since they can't be inferred.
       // const f1: Filter<Person> = Filter.props({ name: 'Fred' });
@@ -622,11 +684,139 @@ describe('query api', () => {
     });
   });
 
+  describe('Filter.childOf', () => {
+    test('childOf with Ref', () => {
+      const parentDxn = DXN.fromSpaceAndObjectId(SpaceId.random(), ObjectId.random());
+      const parentRef = Ref.fromDXN(parentDxn);
+      const filter = Filter.childOf(parentRef);
+
+      expect(filter.ast).toMatchObject({
+        type: 'child-of',
+        parents: [parentDxn.toString()],
+        transitive: true,
+      });
+      Schema.validateSync(QueryAST.Filter)(filter.ast);
+    });
+
+    test('childOf with object', () => {
+      const parent = Obj.make(TestSchema.Person, { name: 'Parent' });
+      const filter = Filter.childOf(parent);
+
+      expect(filter.ast).toMatchObject({
+        type: 'child-of',
+        transitive: true,
+      });
+      expect(filter.ast.type === 'child-of' && filter.ast.parents.length).toBe(1);
+      Schema.validateSync(QueryAST.Filter)(filter.ast);
+    });
+
+    test('childOf with array of Refs', () => {
+      const dxn1 = DXN.fromSpaceAndObjectId(SpaceId.random(), ObjectId.random());
+      const dxn2 = DXN.fromSpaceAndObjectId(SpaceId.random(), ObjectId.random());
+      const filter = Filter.childOf([Ref.fromDXN(dxn1), Ref.fromDXN(dxn2)]);
+
+      expect(filter.ast).toMatchObject({
+        type: 'child-of',
+        parents: [dxn1.toString(), dxn2.toString()],
+        transitive: true,
+      });
+      Schema.validateSync(QueryAST.Filter)(filter.ast);
+    });
+
+    test('childOf with transitive=false', () => {
+      const parentRef = Ref.fromDXN(DXN.fromSpaceAndObjectId(SpaceId.random(), ObjectId.random()));
+      const filter = Filter.childOf(parentRef, { transitive: false });
+
+      expect(filter.ast).toMatchObject({
+        type: 'child-of',
+        parents: [parentRef.dxn.toString()],
+        transitive: false,
+      });
+      Schema.validateSync(QueryAST.Filter)(filter.ast);
+    });
+
+    test('childOf in select query', () => {
+      const parentDxn = DXN.fromSpaceAndObjectId(SpaceId.random(), ObjectId.random());
+      const parentRef = Ref.fromDXN(parentDxn);
+      const query = Query.select(Filter.childOf(parentRef));
+
+      expect(query.ast).toMatchObject({
+        type: 'select',
+        filter: {
+          type: 'child-of',
+          parents: [parentDxn.toString()],
+          transitive: true,
+        },
+      });
+      Schema.validateSync(QueryAST.Query)(query.ast);
+    });
+
+    test('childOf combined with type filter', () => {
+      const parentDxn = DXN.fromSpaceAndObjectId(SpaceId.random(), ObjectId.random());
+      const parentRef = Ref.fromDXN(parentDxn);
+      const query = Query.select(Filter.and(Filter.type(TestSchema.Person), Filter.childOf(parentRef)));
+
+      Schema.validateSync(QueryAST.Query)(query.ast);
+      expect(query.ast).toMatchObject({
+        type: 'select',
+        filter: {
+          type: 'and',
+          filters: [
+            { type: 'object', typename: 'dxn:type:com.example.type.person:0.1.0' },
+            { type: 'child-of', parents: [parentDxn.toString()], transitive: true },
+          ],
+        },
+      });
+    });
+
+    test('childOf pretty-prints correctly', () => {
+      const parentRef = Ref.fromDXN(DXN.fromSpaceAndObjectId(SpaceId.random(), ObjectId.random()));
+      const filter = Filter.childOf(parentRef);
+      const pretty = Filter.pretty(filter);
+      expect(pretty).toContain('Filter.childOf');
+      expect(pretty).toContain('transitive: true');
+    });
+
+    test('childOf with mixed objects and Refs', () => {
+      const parent = Obj.make(TestSchema.Person, { name: 'Parent' });
+      const refDxn = DXN.fromSpaceAndObjectId(SpaceId.random(), ObjectId.random());
+      const parentRef = Ref.fromDXN(refDxn);
+      const filter = Filter.childOf([parent, parentRef]);
+
+      expect(filter.ast).toMatchObject({
+        type: 'child-of',
+        transitive: true,
+      });
+      expect(filter.ast.type === 'child-of' && filter.ast.parents.length).toBe(2);
+      Schema.validateSync(QueryAST.Filter)(filter.ast);
+    });
+  });
+
   describe('Filter', () => {
     test('Filter.or(Filter.typename(...))', () => {
-      const filter = Filter.or(Filter.typename('example.com/type/Person'));
+      const filter = Filter.or(Filter.typename('com.example.type.person'));
       // TODO(dmaretskyi): Give vitest type-tests a try.
       const _isAssignable: Obj.Unknown = null as any as Filter.Type<typeof filter>;
     });
+
+    test('Filter.pretty returns human-readable filter string', () => {
+      const filter = Filter.type(TestSchema.Person, { name: 'Fred' });
+      const pretty = Filter.pretty(filter);
+      expect(pretty).toContain('Filter.type');
+      expect(pretty).toContain('com.example.type.person');
+    });
+
+    test('Filter.pretty handles complex filters', () => {
+      const filter = Filter.and(Filter.type(TestSchema.Person), Filter.id(ObjectId.random()));
+      const pretty = Filter.pretty(filter);
+      expect(pretty).toContain('Filter.and');
+      expect(pretty).toContain('Filter.type');
+    });
+
+    test('Filter.pretty handles or filters', () => {
+      const filter = Filter.or(Filter.type(TestSchema.Person), Filter.type(TestSchema.Organization));
+      const pretty = Filter.pretty(filter);
+      expect(pretty).toContain('Filter.or');
+    });
   });
 });

package/src/Query.ts

@@ -2,6 +2,8 @@
 // Copyright 2025 DXOS.org
 //
 
+// @import-as-namespace
+
 import type * as EffectArray from 'effect/Array';
 import type * as Schema from 'effect/Schema';
 
@@ -205,6 +207,11 @@ export interface Query<T> {
    * Add options to a query.
    */
   'options'(options: QueryAST.QueryOptions): Query<T>;
+
+  /**
+   * Attach a diagnostic label for logs and tooling (execution semantics unchanged).
+   */
+  'debugLabel'(label: string): Query<T>;
 }
 
 export type Any = Query<any>;
@@ -331,6 +338,12 @@ class QueryClass implements Any {
       | 'all-accessible-spaces',
     options?: { includeFeeds?: boolean },
   ): Any {
+    if (arg == null) {
+      throw new TypeError(
+        'Query.from() requires a valid data source argument (database, feed, query, scope, or "all-accessible-spaces").',
+      );
+    }
+
     if (is(arg)) {
       return new QueryClass({
         type: 'from',
@@ -380,13 +393,21 @@ class QueryClass implements Any {
     if (items.length > 0) {
       const typename = Obj.getTypename(items[0] as Obj.Unknown);
       // TODO(dmaretskyi): Support querying from views.
-      if (typename === 'dxos.org/type/View') {
+      if (typename === 'org.dxos.type.view') {
         throw new Error('Query.from(view) is not yet supported.');
       }
       // TODO(dmaretskyi): Support querying from collections.
-      if (typename === 'dxos.org/type/Collection') {
+      if (typename === 'org.dxos.type.collection') {
         throw new Error('Query.from(collection) is not yet supported.');
       }
+      // Validate that the items are Feed.Feed instances.
+      for (const item of items) {
+        if (!Obj.instanceOf(Feed.Feed, item)) {
+          throw new TypeError(
+            `Query.from() expects Feed objects (org.dxos.type.feed), but received an object with typename '${typename ?? 'unknown'}'.`,
+          );
+        }
+      }
     }
 
     const feeds = items as Feed.Feed[];
@@ -413,6 +434,21 @@ class QueryClass implements Any {
       options,
     });
   }
+
+  debugLabel(label: string): Any {
+    if (this.ast.type === 'options') {
+      return new QueryClass({
+        type: 'options',
+        query: this.ast.query,
+        options: { ...this.ast.options, debugLabel: label },
+      });
+    }
+    return new QueryClass({
+      type: 'options',
+      query: this.ast,
+      options: { debugLabel: label },
+    });
+  }
 }
 
 export const is = (value: unknown): value is Any => {
@@ -444,7 +480,13 @@ export const select = <F extends Filter.Any>(filter: F): Query<Filter.Type<F>> =
  *
  * Shorthand for: `Query.select(Filter.type(schema, predicates))`.
  */
-export const type = (schema: Schema.Schema.All | string, predicates?: Filter.Props<unknown>): Any => {
+export const type: {
+  <S extends Schema.Schema.All>(
+    schema: S,
+    predicates?: Filter.Props<Schema.Schema.Type<S>>,
+  ): Query<Schema.Schema.Type<S>>;
+  (schema: string, predicates?: Filter.Props<unknown>): Query<any>;
+} = (schema: Schema.Schema.All | string, predicates?: Filter.Props<unknown>): Any => {
   return new QueryClass({
     type: 'select',
     filter: Filter.type(schema, predicates).ast,
@@ -518,3 +560,8 @@ const _isScope = (value: unknown): value is QueryAST.Scope => {
   }
   return Object.keys(value).every((key) => SCOPE_KEYS.has(key));
 };
+
+/**
+ * Returns a human-readable string representation of a Query AST.
+ */
+export const pretty = (query: Any): string => internal.prettyQuery(query.ast);

package/src/Ref.ts

@@ -2,12 +2,14 @@
 // Copyright 2025 DXOS.org
 //
 
+// @import-as-namespace
+
 import * as Option from 'effect/Option';
 import type * as Schema from 'effect/Schema';
 import * as SchemaAST from 'effect/SchemaAST';
 
 import type * as Entity from './Entity';
-import * as internal from './internal';
+import * as refInternal from './internal/Ref';
 import type * as JsonSchema from './JsonSchema';
 import type * as Obj from './Obj';
 
@@ -29,8 +31,8 @@ import type * as Obj from './Obj';
  * database.makeRef(dxn); // Create a ref from a DXN.
  * ```
  */
-export type Ref<T> = internal.Ref<T>;
-export type Unknown = internal.Ref<Obj.Unknown>;
+export type Ref<T> = refInternal.Ref<T>;
+export type Unknown = refInternal.Ref<Obj.Unknown>;
 
 /**
  * Factory function to create a Ref schema for the given target schema.
@@ -43,9 +45,9 @@ export type Unknown = internal.Ref<Obj.Unknown>;
  * }).pipe(Type.object({ typename: 'Task', version: '0.1.0' }));
  * ```
  */
-export const Ref: <S extends Schema.Schema.Any>(schema: S) => RefSchema<Schema.Schema.Type<S>> = internal.Ref;
+export const Ref: <S extends Schema.Schema.Any>(schema: S) => RefSchema<Schema.Schema.Type<S>> = refInternal.Ref;
 
-export const Array = internal.RefArray;
+export const Array = refInternal.RefArray;
 
 /**
  * TypeScript type for a Ref schema.
@@ -64,31 +66,31 @@ export const Array = internal.RefArray;
 // TODO(dmaretskyi): Investigate if we can remove this type.
 //                   Post DX-836 it will become just `Schema.Schema<Ref.Ref<T>>`.
 //                   NOTE: This could be Type.Ref<T> instead, but since it going to be removed, it's better to keep it here, self-contained.
-export interface RefSchema<T extends Entity.Unknown> extends internal.RefSchema<T> {}
+export interface RefSchema<T extends Entity.Unknown> extends refInternal.RefSchema<T> {}
 
 /**
  * Extract reference target.
  */
-export type Target<R extends Unknown> = R extends internal.Ref<infer T> ? T : never;
+export type Target<R extends Unknown> = R extends refInternal.Ref<infer T> ? T : never;
 
 /**
  * Reference resolver.
  */
-export type Resolver = internal.RefResolver;
+export type Resolver = refInternal.RefResolver;
 
-export const isRef: (value: unknown) => value is Unknown = internal.Ref.isRef;
+export const isRef: (value: unknown) => value is Unknown = refInternal.Ref.isRef;
 
-export const make = internal.Ref.make;
+export const make = refInternal.Ref.make;
 
 // TODO(dmaretskyi): Consider just allowing `make` to accept DXN.
-export const fromDXN = internal.Ref.fromDXN;
+export const fromDXN = refInternal.Ref.fromDXN;
 
 // TODO(wittjosiah): Factor out?
 export const isRefType = (ast: SchemaAST.AST): boolean => {
   return SchemaAST.getAnnotation<JsonSchema.JsonSchema>(ast, SchemaAST.JSONSchemaAnnotationId).pipe(
     Option.flatMap((jsonSchema) => ('$id' in jsonSchema ? Option.some(jsonSchema) : Option.none())),
     Option.flatMap((jsonSchema) => {
-      const { typename } = internal.getSchemaReference(jsonSchema) ?? {};
+      const { typename } = refInternal.getSchemaReference(jsonSchema) ?? {};
       return typename ? Option.some(true) : Option.some(false);
     }),
     Option.getOrElse(() => false),

package/src/Relation.test.ts

@@ -65,8 +65,8 @@ describe('Relation', () => {
       expect(Relation.getDXN(snapshot)).toBeDefined();
 
       // getTypename - works with both.
-      expect(Relation.getTypename(rel)).toBe('example.com/type/HasManager');
-      expect(Relation.getTypename(snapshot)).toBe('example.com/type/HasManager');
+      expect(Relation.getTypename(rel)).toBe('com.example.type.has-manager');
+      expect(Relation.getTypename(snapshot)).toBe('com.example.type.has-manager');
 
       // getMeta - works with both.
       expect(Relation.getMeta(rel)).toBeDefined();