@dxos/echo 0.8.4-main.ef1bc66f44 → 0.8.4-main.effb148878

package/src/Query.ts

@@ -2,16 +2,27 @@
 // Copyright 2025 DXOS.org
 //
 
+// @import-as-namespace
+
 import type * as EffectArray from 'effect/Array';
 import type * as Schema from 'effect/Schema';
 
 import { type QueryAST } from '@dxos/echo-protocol';
 
+import type * as Collection from './Collection';
+import * as Database from './Database';
+import type * as Dataset from './Dataset';
+import type * as Entity from './Entity';
+import * as Feed from './Feed';
 import * as Filter from './Filter';
-import { getTypeDXNFromSpecifier } from './internal';
+import * as internal from './internal';
+import * as Obj from './Obj';
 import type * as Order from './Order';
 import type * as Ref from './Ref';
+import type * as Relation from './Relation';
+// eslint-disable-next-line @dxos/rules/import-as-namespace
 import type * as Type$ from './Type';
+import type * as View from './View';
 
 // TODO(dmaretskyi): Split up into interfaces for objects and relations so they can have separate verbs.
 // TODO(dmaretskyi): Undirected relation traversals.
@@ -35,15 +46,15 @@ export interface Query<T> {
    * @param filter - Filter to select the objects.
    * @returns Query for the selected objects.
    */
-  select(filter: Filter.Filter<T>): Query<T>;
-  select(props: Filter.Props<T>): Query<T>;
+  'select'(filter: Filter.Filter<T>): Query<T>;
+  'select'(props: Filter.Props<T>): Query<T>;
 
   /**
    * Traverse an outgoing reference.
    * @param key - Property path inside T that is a reference or optional reference.
    * @returns Query for the target of the reference.
    */
-  reference<K extends RefPropKey<T>>(
+  'reference'<K extends RefPropKey<T>>(
     key: K,
   ): Query<
     T[K] extends Ref.Unknown
@@ -61,12 +72,12 @@ export interface Query<T> {
    */
   // TODO(dmaretskyi): any way to enforce `Ref.Target<Schema.Schema.Type<S>[key]> == T`?
   // TODO(dmaretskyi): Ability to go through arrays of references.
-  referencedBy<S extends Schema.Schema.All>(
+  'referencedBy'<S extends Type$.AnyEntity>(
     target: S | string,
-    key: RefPropKey<Schema.Schema.Type<S>>,
-  ): Query<Schema.Schema.Type<S>>;
-  referencedBy<S extends Schema.Schema.All>(target: S | string): Query<Schema.Schema.Type<S>>;
-  referencedBy(): Query<any>;
+    key: RefPropKey<Type$.InstanceType<S>>,
+  ): Query<Type$.InstanceType<S>>;
+  'referencedBy'<S extends Type$.AnyEntity>(target: S | string): Query<Type$.InstanceType<S>>;
+  'referencedBy'(): Query<any>;
 
   /**
    * Find relations where this object is the source.
@@ -74,45 +85,45 @@ export interface Query<T> {
    * @param relation - Schema of the relation.
    * @param predicates - Predicates to filter the relation objects.
    */
-  sourceOf<S extends Schema.Schema.All>(
-    relation: S | string,
-    predicates?: Filter.Props<Schema.Schema.Type<S>>,
-  ): Query<Schema.Schema.Type<S>>;
+  'sourceOf'<R extends Type$.AnyRelation>(
+    relation?: R | string,
+    predicates?: Filter.Props<Type$.InstanceType<R>>,
+  ): Query<Type$.InstanceType<R>>;
 
   /**
    * Find relations where this object is the target.
    * @returns Query for the relation objects.
-   * @param relation - Schema of the relation.
+   * @param relation - Type entity of the relation.
    * @param predicates - Predicates to filter the relation objects.
    */
-  targetOf<S extends Schema.Schema.All>(
-    relation: S | string,
-    predicates?: Filter.Props<Schema.Schema.Type<S>>,
-  ): Query<Schema.Schema.Type<S>>;
+  'targetOf'<R extends Type$.AnyRelation>(
+    relation?: R | string,
+    predicates?: Filter.Props<Type$.InstanceType<R>>,
+  ): Query<Type$.InstanceType<R>>;
 
   /**
    * For a query for relations, get the source objects.
    * @returns Query for the source objects.
    */
-  source(): Query<Type$.Relation.Source<T>>;
+  'source'(): Query<Relation.SourceOf<T>>;
 
   /**
    * For a query for relations, get the target objects.
    * @returns Query for the target objects.
    */
-  target(): Query<Type$.Relation.Target<T>>;
+  'target'(): Query<Relation.TargetOf<T>>;
 
   /**
    * Get the parent object of the current selection.
    * @returns Query for the parent objects.
    */
-  parent(): Query<any>;
+  'parent'(): Query<any>;
 
   /**
    * Get all child objects of the current selection.
    * @returns Query for the child objects.
    */
-  children(): Query<any>;
+  'children'(): Query<any>;
 
   /**
    * Order the query results.
@@ -120,19 +131,90 @@ export interface Query<T> {
    * @param order - Order to sort the results.
    * @returns Query for the ordered results.
    */
-  orderBy(...order: EffectArray.NonEmptyArray<Order.Order<T>>): Query<T>;
+  'orderBy'(...order: EffectArray.NonEmptyArray<Order.Order<T>>): Query<T>;
 
   /**
    * Limit the number of results.
    * @param limit - Maximum number of results to return.
    * @returns Query for the limited results.
    */
-  limit(limit: number): Query<T>;
+  'limit'(limit: number): Query<T>;
+
+  /**
+   * Query from selected databases only.
+   *
+   * Example:
+   *
+   * ```ts
+   * Query.select(Filter.type(Person)).from(db);
+   * ```
+   *
+   * @param options.includeFeeds [false] - Whether to include feeds in the query. Default is to query from automerge documents only.
+   */
+  'from'(database: Database.Database | Database.Database[], options?: { includeFeeds?: boolean }): Query<T>;
+
+  /**
+   * Query from selected feeds only.
+   *
+   * Example:
+   *
+   * ```ts
+   * Query.select(Filter.type(Person)).from(feed);
+   * ```
+   *
+   */
+  'from'(feeds: Feed.Feed | Feed.Feed[]): Query<T>;
+
+  /**
+   * Query from all accessible spaces.
+   *
+   * Example:
+   *
+   * ```ts
+   * Query.select(Filter.type(Person)).from('all-accessible-spaces');
+   * ```
+   *
+   * @param options.includeFeeds [false] - Whether to include feeds in the query. Default is to query from automerge documents only.
+   */
+  'from'(allSpaces: 'all-accessible-spaces', options?: { includeFeeds?: boolean }): Query<T>;
+
+  /**
+   * Query from a dataset.
+   * Currently only feeds are supported.
+   *
+   * Example:
+   *
+   * ```ts
+   * Query.type(Person).from(feed);
+   * ```
+   */
+  'from'(dataset: Dataset.Dataset): Query<T>;
+
+  /**
+   * Query from the results of another query.
+   *
+   * Example:
+   *
+   * ```ts
+   * Query.select(Filter.props({ foo: 'foo' })).from(Query.select(Filter.type(Contact)).reference('org'));
+   * ```
+   */
+  'from'(query: Any): Query<T>;
+
+  /**
+   * Query from a raw scope specification.
+   */
+  'from'(scope: QueryAST.Scope): Query<T>;
 
   /**
    * Add options to a query.
    */
-  options(options: QueryAST.QueryOptions): Query<T>;
+  '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>;
@@ -140,7 +222,7 @@ export type Any = Query<any>;
 export type Type<Q extends Any> = Q extends Query<infer T> ? T : never;
 
 class QueryClass implements Any {
-  private static variance: Any['~Query'] = {} as Any['~Query'];
+  private static 'variance': Any['~Query'] = {} as Any['~Query'];
 
   constructor(public readonly ast: QueryAST.Query) {}
 
@@ -170,31 +252,31 @@ class QueryClass implements Any {
     });
   }
 
-  referencedBy(target?: Schema.Schema.All | string, key?: string): Any {
-    const dxn = target !== undefined ? getTypeDXNFromSpecifier(target) : null;
+  referencedBy(target?: Type$.AnyEntity | string, key?: string): Any {
+    const uri = target !== undefined ? internal.getTypeURIFromSpecifier(target) : null;
     return new QueryClass({
       type: 'incoming-references',
       anchor: this.ast,
       property: key ?? null,
-      typename: dxn?.toString() ?? null,
+      typename: uri ?? null,
     });
   }
 
-  sourceOf(relation: Schema.Schema.All | string, predicates?: Filter.Props<unknown> | undefined): Any {
+  sourceOf(relation?: Type$.AnyRelation | string, predicates?: Filter.Props<unknown> | undefined): Any {
     return new QueryClass({
       type: 'relation',
       anchor: this.ast,
       direction: 'outgoing',
-      filter: Filter.type(relation, predicates).ast,
+      filter: relation !== undefined ? Filter.type(relation, predicates).ast : undefined,
     });
   }
 
-  targetOf(relation: Schema.Schema.All | string, predicates?: Filter.Props<unknown> | undefined): Any {
+  targetOf(relation?: Type$.AnyRelation | string, predicates?: Filter.Props<unknown> | undefined): Any {
     return new QueryClass({
       type: 'relation',
       anchor: this.ast,
       direction: 'incoming',
-      filter: Filter.type(relation, predicates).ast,
+      filter: relation !== undefined ? Filter.type(relation, predicates).ast : undefined,
     });
   }
 
@@ -246,6 +328,113 @@ class QueryClass implements Any {
     });
   }
 
+  from(
+    arg:
+      | Database.Database
+      | Database.Database[]
+      | Feed.Feed
+      | Feed.Feed[]
+      | Collection.Collection
+      | View.View
+      | Any
+      | QueryAST.Scope
+      | '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',
+        query: this.ast,
+        from: { _tag: 'query', query: arg.ast },
+      });
+    }
+
+    if (arg === 'all-accessible-spaces') {
+      return new QueryClass({
+        type: 'from',
+        query: this.ast,
+        from: {
+          _tag: 'scope',
+          scope: {
+            ...(options?.includeFeeds ? { allFeedsFromSpaces: true } : {}),
+          },
+        },
+      });
+    }
+
+    if (_isScope(arg)) {
+      return new QueryClass({
+        type: 'from',
+        query: this.ast,
+        from: { _tag: 'scope', scope: arg },
+      });
+    }
+
+    const items = Array.isArray(arg) ? arg : [arg];
+
+    if (items.length > 0 && Database.isDatabase(items[0])) {
+      const databases = items as Database.Database[];
+      return new QueryClass({
+        type: 'from',
+        query: this.ast,
+        from: {
+          _tag: 'scope',
+          scope: {
+            spaceIds: databases.map((db) => db.spaceId),
+            ...(options?.includeFeeds ? { allFeedsFromSpaces: true } : {}),
+          },
+        },
+      });
+    }
+
+    if (items.length > 0) {
+      const typename = Obj.getTypename(items[0] as Obj.Unknown);
+      // TODO(dmaretskyi): Support querying from views.
+      if (typename === 'org.dxos.type.view') {
+        throw new Error('Query.from(view) is not yet supported.');
+      }
+      // TODO(dmaretskyi): Support querying from collections.
+      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 feedItems = items as Feed.Feed[];
+    const feedUris = feedItems.map((feed) => {
+      const uri = Feed.getQueueUri(feed);
+      if (!uri) {
+        throw new TypeError(
+          `Query.from() expects persisted Feed objects with a queue URI; got feed without a space (id=${Obj.getURI(feed)}).`,
+        );
+      }
+      return uri;
+    });
+    return new QueryClass({
+      type: 'from',
+      query: this.ast,
+      from: {
+        _tag: 'scope',
+        scope: {
+          feeds: feedUris,
+        },
+      },
+    });
+  }
+
   options(options: QueryAST.QueryOptions): Any {
     return new QueryClass({
       type: 'options',
@@ -253,6 +442,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 => {
@@ -284,10 +488,30 @@ 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 => {
+/**
+ * Instance type for a query over `type`. Falls back to `Entity.Unknown` when the
+ * type can't be narrowed — e.g. the caller passes the wide `Type.AnyEntity` — so
+ * results aren't typed as the useless bare `OfKind<...>` union that
+ * `Type.InstanceType<Type.AnyEntity>` produces.
+ */
+type QueryInstance<T extends Type$.AnyEntity> = Type$.AnyEntity extends T ? Entity.Unknown : Type$.InstanceType<T>;
+
+export const type: {
+  <T extends Type$.AnyEntity>(type: T, predicates?: Filter.Props<QueryInstance<T>>): Query<QueryInstance<T>>;
+  // Brand-narrowed schema overload — only well-known unknown schemas pass.
+  <S extends internal.UnknownTypeSchema<any, any>>(
+    schema: S,
+    predicates?: Filter.Props<Schema.Schema.Type<S>>,
+  ): Query<Schema.Schema.Type<S>>;
+  <S extends Schema.Union<readonly Schema.Schema.AnyNoContext[]>>(
+    union: S,
+    predicates?: Filter.Props<Schema.Schema.Type<S>>,
+  ): Query<Schema.Schema.Type<S>>;
+  (schema: string, predicates?: Filter.Props<unknown>): Query<any>;
+} = (type: Type$.AnyEntity | string, predicates?: Filter.Props<unknown>): Any => {
   return new QueryClass({
     type: 'select',
-    filter: Filter.type(schema, predicates).ast,
+    filter: Filter.type(type, predicates).ast,
   });
 };
 
@@ -322,3 +546,44 @@ export const without = <T>(source: Query<T>, exclude: Query<T>): Query<T> => {
     exclude: exclude.ast,
   });
 };
+
+/**
+ * Create a query scoped to a data source.
+ * The returned query selects everything from the source; chain `.select()` to narrow results.
+ *
+ * @param source - Data source: database, feed, 'all-accessible-spaces', or another query.
+ * @returns Query scoped to the given source.
+ */
+export const from = (
+  source:
+    | Database.Database
+    | Database.Database[]
+    | Feed.Feed
+    | Feed.Feed[]
+    | Any
+    | QueryAST.Scope
+    | 'all-accessible-spaces',
+  options?: { includeFeeds?: boolean },
+): Any => {
+  const baseQuery: QueryAST.Query = {
+    type: 'select',
+    filter: Filter.everything().ast,
+  };
+  const wrapper = new QueryClass(baseQuery);
+  return wrapper.from(source as any, options);
+};
+
+const SCOPE_KEYS = new Set(['spaceIds', 'feeds', 'allFeedsFromSpaces']);
+
+/** Detect a raw Scope object (plain object with only Scope-valid keys). */
+const _isScope = (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));
+};
+
+/**
+ * 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,42 +2,113 @@
 // 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 { Ref as Ref$, RefArray, type RefResolver } from './internal';
-import { getSchemaReference } from './internal';
+import { type URI } from '@dxos/keys';
+
+import type * as Entity from './Entity';
+import type * as internal from './internal';
+import * as refInternal from './internal/Ref';
 import type * as JsonSchema from './JsonSchema';
 import type * as Obj from './Obj';
+// eslint-disable-next-line @dxos/rules/import-as-namespace
+import type * as TypeNs from './Type';
 
-export type Ref<T> = Ref$<T>;
-export type Unknown = Ref$<Obj.Unknown>;
+/**
+ * Instance type for a reference.
+ *
+ * Reference can point to any object or relation.
+ * References are lazy loaded.
+ *
+ * `ref.dxn` is the DXN of the referenced object.
+ *
+ * @example
+ * ```ts
+ * const taskRef: Ref<Task> = Ref.make(task);
+ *
+ * await taskRef.load(); // Returns Promise<Task>
+ * yield* Database.load(taskRef); // Effectful version.
+ *
+ * database.makeRef(dxn); // Create a ref from a DXN.
+ * ```
+ */
+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.
+ * Use this in schema definitions to declare reference fields.
+ *
+ * @example
+ * ```ts
+ * const Task = Schema.Struct({
+ *   assignee: Ref.Ref(Person),  // Creates a Ref schema
+ * }).pipe(Type.makeObject(DXN.make('com.example.type.task', '0.1.0')));
+ * ```
+ */
+export const Ref: {
+  <S extends TypeNs.AnyObj | TypeNs.AnyRelation>(type: S): RefSchema<TypeNs.InstanceType<S> & Obj.Unknown>;
 
-export const Array = RefArray;
+  // `Type.Type` entities (the meta-schema kind) can be referenced too — e.g. a
+  // trigger that points to a stored function/workflow definition.
+  <T extends TypeNs.Type<any>>(type: T): RefSchema<TypeNs.InstanceType<T>>;
+
+  // Schema-side overload for the well-known "any object" / "any relation" schemas.
+  // Other raw `Schema.Schema` values are intentionally rejected — callers should
+  // pass a `Type.Type` entity instead.
+  <S extends internal.UnknownTypeSchema<any, any>>(schema: S): RefSchema<Schema.Schema.Type<S> & Obj.Unknown>;
+} = refInternal.Ref as any;
+
+export const Array = refInternal.RefArray;
+
+/**
+ * TypeScript type for a Ref schema.
+ * This is the type of the SCHEMA itself, not the runtime ref instance.
+ * For the instance type, use `Ref.Ref<T>` from the Ref module.
+ *
+ * @example
+ * ```ts
+ * // Schema type annotation (rarely needed, usually inferred):
+ * const refSchema: Ref.RefSchema<typeof Task> = Ref.Ref(Task);
+ *
+ * // Instance type annotation (use Ref.Ref instead):
+ * const refInstance: Ref.Ref<Task> = Ref.make(task);
+ * ```
+ */
+// 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 refInternal.RefSchema<T> {}
 
 /**
  * Extract reference target.
  */
-export type Target<R extends Unknown> = R extends Ref$<infer T> ? T : never;
+export type Target<R extends Unknown> = R extends refInternal.Ref<infer T> ? T : never;
 
 /**
  * Reference resolver.
  */
-export type Resolver = RefResolver;
+export type Resolver = refInternal.RefResolver;
+
+export const isRef: (value: unknown) => value is Unknown = refInternal.Ref.isRef;
 
-export const isRef: (value: unknown) => value is Unknown = Ref$.isRef;
+export const make = refInternal.Ref.make;
 
-export const make = Ref$.make;
+// TODO(dmaretskyi): Consider just allowing `make` to accept URI.
+export const fromURI = (uri: URI.URI): refInternal.Ref<any> => refInternal.Ref.fromURI(uri);
 
-// TODO(dmaretskyi): Consider just allowing `make` to accept DXN.
-export const fromDXN = Ref$.fromDXN;
+export const hasObjectId = refInternal.Ref.hasObjectId;
 
 // 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 } = getSchemaReference(jsonSchema) ?? {};
+      const { typename } = refInternal.getSchemaReference(jsonSchema) ?? {};
       return typename ? Option.some(true) : Option.some(false);
     }),
     Option.getOrElse(() => false),

package/src/Relation.test.ts

@@ -25,6 +25,12 @@ describe('Relation', () => {
       expect(snapshot[SnapshotKindId]).toBe(Entity.Kind.Relation);
       expect((snapshot as any)[Entity.KindId]).toBeUndefined();
 
+      expect(Relation.isSnapshot(snapshot)).toBe(true);
+      expect(Obj.isSnapshot(snapshot)).toBe(false);
+
+      expect(Relation.getSource(snapshot)).toEqual(obj1);
+      expect(Relation.getTarget(snapshot)).toEqual(obj2);
+
       // Snapshot has same id.
       expect(snapshot.id).toBe(rel.id);
     });
@@ -38,13 +44,13 @@ describe('Relation', () => {
       });
       const snapshot = Relation.getSnapshot(rel);
 
-      // getSourceDXN - works with both.
-      expect(Relation.getSourceDXN(rel)).toBeDefined();
-      expect(Relation.getSourceDXN(snapshot)).toBeDefined();
+      // getSourceURI - works with both.
+      expect(Relation.getSourceURI(rel)).toBeDefined();
+      expect(Relation.getSourceURI(snapshot)).toBeDefined();
 
-      // getTargetDXN - works with both.
-      expect(Relation.getTargetDXN(rel)).toBeDefined();
-      expect(Relation.getTargetDXN(snapshot)).toBeDefined();
+      // getTargetURI - works with both.
+      expect(Relation.getTargetURI(rel)).toBeDefined();
+      expect(Relation.getTargetURI(snapshot)).toBeDefined();
 
       // getSource - works with both.
       expect(Relation.getSource(rel)).toBeDefined();
@@ -55,12 +61,12 @@ describe('Relation', () => {
       expect(Relation.getTarget(snapshot)).toBeDefined();
 
       // getDXN - works with both.
-      expect(Relation.getDXN(rel)).toBeDefined();
-      expect(Relation.getDXN(snapshot)).toBeDefined();
+      expect(Relation.getURI(rel)).toBeDefined();
+      expect(Relation.getURI(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.hasManager');
+      expect(Relation.getTypename(snapshot)).toBe('com.example.type.hasManager');
 
       // getMeta - works with both.
       expect(Relation.getMeta(rel)).toBeDefined();