@dxos/echo 0.8.4-main.d05539e30a → 0.8.4-main.d9fc60f731

package/src/Query.ts

@@ -19,6 +19,8 @@ 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.
@@ -69,11 +71,11 @@ 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>>;
+    key: RefPropKey<Type$.InstanceType<S>>,
+  ): Query<Type$.InstanceType<S>>;
+  'referencedBy'<S extends Type$.AnyEntity>(target: S | string): Query<Type$.InstanceType<S>>;
   'referencedBy'(): Query<any>;
 
   /**
@@ -82,21 +84,21 @@ 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.
@@ -199,9 +201,20 @@ export interface Query<T> {
   'from'(query: Any): Query<T>;
 
   /**
-   * Query from a raw scope specification.
+   * Query from one or more raw scopes.
+   *
+   * Use the {@link Scope} constructors rather than raw tagged objects:
+   *
+   * ```ts
+   * Query.select(Filter.type(Type.Type)).from(Scope.space(), Scope.registry());
+   * ```
+   */
+  'from'(...scopes: QueryAST.Scope[]): Query<T>;
+
+  /**
+   * Query from a raw scope or array of scopes.
    */
-  'from'(scope: QueryAST.Scope): Query<T>;
+  'from'(scope: QueryAST.Scope | QueryAST.Scope[]): Query<T>;
 
   /**
    * Add options to a query.
@@ -249,17 +262,17 @@ class QueryClass implements Any {
     });
   }
 
-  referencedBy(target?: Schema.Schema.All | string, key?: string): Any {
-    const dxn = target !== undefined ? internal.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,
@@ -268,7 +281,7 @@ class QueryClass implements Any {
     });
   }
 
-  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,
@@ -326,18 +339,48 @@ 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 },
+    ...args:
+      | [
+          (
+            | Database.Database
+            | Database.Database[]
+            | Feed.Feed
+            | Feed.Feed[]
+            | Collection.Collection
+            | View.View
+            | Any
+            | QueryAST.Scope
+            | QueryAST.Scope[]
+            | 'all-accessible-spaces'
+          ),
+          { includeFeeds?: boolean }?,
+        ]
+      | QueryAST.Scope[]
   ): Any {
+    // Variadic raw scopes: `.from(Scope.space(), Scope.registry())`.
+    if (args.length > 1 && args.every(_isRawScope)) {
+      return new QueryClass({
+        type: 'from',
+        query: this.ast,
+        from: { _tag: 'scope', scopes: args as QueryAST.Scope[] },
+      });
+    }
+
+    const [arg, options] = args as [
+      (
+        | Database.Database
+        | Database.Database[]
+        | Feed.Feed
+        | Feed.Feed[]
+        | Collection.Collection
+        | View.View
+        | Any
+        | QueryAST.Scope
+        | QueryAST.Scope[]
+        | 'all-accessible-spaces'
+      ),
+      { includeFeeds?: boolean }?,
+    ];
     if (arg == null) {
       throw new TypeError(
         'Query.from() requires a valid data source argument (database, feed, query, scope, or "all-accessible-spaces").',
@@ -356,20 +399,23 @@ class QueryClass implements Any {
       return new QueryClass({
         type: 'from',
         query: this.ast,
-        from: {
-          _tag: 'scope',
-          scope: {
-            ...(options?.includeFeeds ? { allFeedsFromSpaces: true } : {}),
-          },
-        },
+        from: { _tag: 'scope', scopes: [] },
       });
     }
 
-    if (_isScope(arg)) {
+    // Raw scope(s): tagged union objects with _tag 'space' | 'feed' | 'registry'.
+    if (Array.isArray(arg) && arg.every(_isRawScope)) {
+      return new QueryClass({
+        type: 'from',
+        query: this.ast,
+        from: { _tag: 'scope', scopes: arg as QueryAST.Scope[] },
+      });
+    }
+    if (_isRawScope(arg)) {
       return new QueryClass({
         type: 'from',
         query: this.ast,
-        from: { _tag: 'scope', scope: arg },
+        from: { _tag: 'scope', scopes: [arg] },
       });
     }
 
@@ -382,10 +428,11 @@ class QueryClass implements Any {
         query: this.ast,
         from: {
           _tag: 'scope',
-          scope: {
-            spaceIds: databases.map((db) => db.spaceId),
-            ...(options?.includeFeeds ? { allFeedsFromSpaces: true } : {}),
-          },
+          scopes: databases.map((db) => ({
+            _tag: 'space' as const,
+            spaceId: db.spaceId,
+            ...(options?.includeFeeds ? { includeAllFeeds: true } : {}),
+          })),
         },
       });
     }
@@ -411,24 +458,19 @@ class QueryClass implements Any {
     }
 
     const feedItems = items as Feed.Feed[];
-    const feedDXNs = feedItems.map((feed) => {
-      const dxn = Feed.getQueueDxn(feed);
-      if (!dxn) {
+    const feedScopes = feedItems.map((feed) => {
+      const uri = Feed.getQueueUri(feed);
+      if (!uri) {
         throw new TypeError(
-          `Query.from() expects persisted Feed objects with a queue DXN; got feed without a space (id=${Obj.getDXN(feed).toString()}).`,
+          `Query.from() expects persisted Feed objects with a queue URI; got feed without a space (id=${Obj.getURI(feed)}).`,
         );
       }
-      return dxn.toString();
+      return { _tag: 'feed' as const, feedUri: String(uri) };
     });
     return new QueryClass({
       type: 'from',
       query: this.ast,
-      from: {
-        _tag: 'scope',
-        scope: {
-          feeds: feedDXNs,
-        },
-      },
+      from: { _tag: 'scope', scopes: feedScopes },
     });
   }
 
@@ -486,15 +528,21 @@ export const select = <F extends Filter.Any>(filter: F): Query<Filter.Type<F>> =
  * Shorthand for: `Query.select(Filter.type(schema, predicates))`.
  */
 export const type: {
-  <S extends Schema.Schema.All>(
+  <T extends Type$.AnyEntity>(type: T, predicates?: Filter.Props<Type$.InstanceType<T>>): Query<Type$.InstanceType<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>;
-} = (schema: Schema.Schema.All | string, predicates?: Filter.Props<unknown>): 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,
   });
 };
 
@@ -538,32 +586,42 @@ export const without = <T>(source: Query<T>, exclude: Query<T>): Query<T> => {
  * @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 },
+  ...args:
+    | [
+        (
+          | Database.Database
+          | Database.Database[]
+          | Feed.Feed
+          | Feed.Feed[]
+          | Any
+          | QueryAST.Scope
+          | QueryAST.Scope[]
+          | 'all-accessible-spaces'
+        ),
+        { includeFeeds?: boolean }?,
+      ]
+    | QueryAST.Scope[]
 ): Any => {
   const baseQuery: QueryAST.Query = {
     type: 'select',
     filter: Filter.everything().ast,
   };
   const wrapper = new QueryClass(baseQuery);
-  return wrapper.from(source as any, options);
+  return (wrapper.from as (...args: unknown[]) => Any)(...args);
 };
 
-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));
+const SCOPE_TAGS = new Set<string>(['space', 'feed', 'registry']);
+
+/** Detect a raw Scope tagged-union object. */
+const _isRawScope = (value: unknown): value is QueryAST.Scope => {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    !Array.isArray(value) &&
+    '_tag' in value &&
+    typeof value._tag === 'string' &&
+    SCOPE_TAGS.has(value._tag)
+  );
 };
 
 /**

package/src/QueryResult.ts

@@ -2,6 +2,9 @@
 // Copyright 2025 DXOS.org
 //
 
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+
 import { type CleanupFn } from '@dxos/async';
 
 import type * as Entity from './Entity';
@@ -104,3 +107,11 @@ export interface QueryResult<T> {
    */
   subscribe(callback?: (query: QueryResult<T>) => void, opts?: SubscriptionOptions): CleanupFn;
 }
+
+/**
+ * Effect that returns a QueryResult when evaluated, but also has shorthand methods for running the query or getting the first result.
+ */
+export interface QueryResultEffect<T, E, R> extends Effect.Effect<QueryResult<T>, E, R> {
+  run: Effect.Effect<T[], E, R>;
+  first: Effect.Effect<Option.Option<T>, E, R>;
+}

package/src/Ref.ts

@@ -8,10 +8,15 @@ import * as Option from 'effect/Option';
 import type * as Schema from 'effect/Schema';
 import * as SchemaAST from 'effect/SchemaAST';
 
+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';
 
 /**
  * Instance type for a reference.
@@ -42,10 +47,21 @@ export type Unknown = refInternal.Ref<Obj.Unknown>;
  * ```ts
  * const Task = Schema.Struct({
  *   assignee: Ref.Ref(Person),  // Creates a Ref schema
- * }).pipe(Type.object({ typename: 'Task', version: '0.1.0' }));
+ * }).pipe(Type.makeObject(DXN.make('com.example.type.task', '0.1.0')));
  * ```
  */
-export const Ref: <S extends Schema.Schema.Any>(schema: S) => RefSchema<Schema.Schema.Type<S>> = refInternal.Ref;
+export const Ref: {
+  <S extends TypeNs.AnyObj | TypeNs.AnyRelation>(type: S): RefSchema<TypeNs.InstanceType<S> & Obj.Unknown>;
+
+  // `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;
 
@@ -82,10 +98,10 @@ export const isRef: (value: unknown) => value is Unknown = refInternal.Ref.isRef
 
 export const make = refInternal.Ref.make;
 
-// TODO(dmaretskyi): Consider just allowing `make` to accept DXN.
-export const fromDXN = refInternal.Ref.fromDXN;
+// TODO(dmaretskyi): Consider just allowing `make` to accept URI.
+export const fromURI = (uri: URI.URI): refInternal.Ref<any> => refInternal.Ref.fromURI(uri);
 
-export const hasObjectId = refInternal.Ref.hasObjectId;
+export const hasEntityId = refInternal.Ref.hasEntityId;
 
 // TODO(wittjosiah): Factor out?
 export const isRefType = (ast: SchemaAST.AST): boolean => {

package/src/Registry.ts

@@ -0,0 +1,155 @@
+// Copyright 2026 DXOS.org
+
+// @import-as-namespace
+
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+
+import { type ReadOnlyEvent } from '@dxos/async';
+
+import type * as Database from './Database';
+import * as Entity from './Entity';
+import type * as Filter from './Filter';
+import type * as Query from './Query';
+
+/**
+ * Identifier denoting an ECHO Registry.
+ */
+export const TypeId = Symbol.for('@dxos/echo/Registry');
+export type TypeId = typeof TypeId;
+
+/**
+ * Composable, in-memory registry of keyed ECHO entities.
+ *
+ * Entities are stored by id and queried via the standard ECHO Query API.
+ * A registry may delegate to an optional upstream registry: results from the local
+ * registry take precedence and upstream results fill in anything not found locally.
+ *
+ * Intended use cases include caches of schemas, operations, blueprints, routines, plugins,
+ * etc., sourced from 3rd-party plugins, local code, or local space objects.
+ *
+ * Types (schema-definition entities produced by `Type.makeObject` / `Type.makeRelation`) are
+ * stored the same way as any other entity — via `add()`. Use `list().filter(Type.isType)` to
+ * retrieve them.
+ *
+ * Scope: a Registry is independent of any ECHO space or Hypergraph — it is a process-local,
+ * in-memory cache. Wire one per space (e.g. as a Layer scoped to the space's Effect runtime)
+ * or share a single instance across spaces depending on the use case.
+ *
+ * The concrete implementation (and the `makeRegistry` / `registryLayer` factories) lives in
+ * `@dxos/echo-db`; this module declares only the interface so that the `@dxos/echo` API surface
+ * stays free of query-matching dependencies.
+ */
+export interface Registry {
+  readonly [TypeId]: TypeId;
+
+  /**
+   * Stable per-instance identifier. Used to key process-local resources (e.g. memoized
+   * reactive atoms) to a specific registry instance, analogous to {@link Database.spaceId}.
+   */
+  readonly id: string;
+
+  /**
+   * Fires whenever local registry contents change (add, remove, or clear).
+   */
+  readonly changed: ReadOnlyEvent<void>;
+
+  /**
+   * All locally-stored entities.
+   * Does not include upstream entities — use {@link list} for that.
+   */
+  readonly local: readonly Entity.Unknown[];
+
+  /**
+   * Add or replace one or more entities in the local registry.
+   * Existing entries with the same id are replaced.
+   * Also indexes type entities by DXN for fast lookup.
+   */
+  add(entities: readonly Entity.Unknown[]): void;
+
+  /**
+   * Remove an entity by id from the local registry.
+   * @returns true if an entity was removed, false if it was not found.
+   */
+  remove(id: string): boolean;
+
+  /**
+   * Remove all locally-stored entities.
+   * Does not affect the upstream registry.
+   */
+  clear(): void;
+
+  /**
+   * Get an entity by id.
+   * Searches the local registry first, then falls back to the upstream registry.
+   */
+  get(id: string): Entity.Unknown | undefined;
+
+  /**
+   * Get an entity by one of its addressing URIs — a type entity by its typename DXN (or, when
+   * persisted, its identifier EID), a keyed entity by its `dxn:<key>[:<version>]`. Accepts legacy
+   * DXN forms (normalized internally). Searches the local registry first, then falls back to the
+   * upstream registry. Narrow the result with `Type.isType` when a type entity is required.
+   */
+  getByURI(uri: string): Entity.Unknown | undefined;
+
+  /**
+   * List all entities.
+   * Local entities take precedence over upstream entities with the same id.
+   */
+  list(): Entity.Unknown[];
+
+  /**
+   * Run an ECHO query against the registry's entities (implements {@link Database.Queryable}).
+   *
+   * Matching happens in-memory over {@link list}. Scope (`from`) clauses are unwrapped and
+   * ignored — a direct registry query always targets the registry's own entities. The primary
+   * way to query registry contents is still through the database (`db.query(...).from(Scope.registry())`),
+   * which fans the database and registry together; this method is for querying a registry directly.
+   *
+   * Only locally-evaluable AST nodes are supported: `select`, `filter`, `limit`, `from`, `options`,
+   * and boolean combinators. Server-side concerns (order, traversal, text/timestamp filters) throw.
+   */
+  query: Database.QueryFn;
+}
+
+/**
+ * Type guard for {@link Registry}.
+ */
+export const isRegistry = (obj: unknown): obj is Registry =>
+  obj != null && typeof obj === 'object' && TypeId in obj && (obj as { [TypeId]?: unknown })[TypeId] === TypeId;
+
+/**
+ * Options for the registry factory (`makeRegistry` in `@dxos/echo-db`).
+ */
+export type Options = {
+  /**
+   * Optional upstream registry. Queries fall back to upstream when an entity
+   * is not present in the local registry.
+   */
+  upstream?: Registry;
+
+  /**
+   * Initial set of entities to seed the local registry with.
+   */
+  initial?: readonly Entity.Unknown[];
+};
+
+/**
+ * Effect Context tag for {@link Registry}.
+ * Use this to inject a registry into Effect-based code.
+ */
+export class Service extends Context.Tag('@dxos/echo/Registry/Service')<Service, Registry>() {}
+
+/**
+ * Executes a query against the registry and returns the results.
+ * Analogous to {@link Database.runQuery} for the in-process registry.
+ */
+export const runQuery: {
+  <Q extends Query.Any>(query: Q): Effect.Effect<Query.Type<Q>[], never, Service>;
+  <F extends Filter.Any>(filter: F): Effect.Effect<Filter.Type<F>[], never, Service>;
+} = (queryOrFilter: Query.Any | Filter.Any) =>
+  Effect.gen(function* () {
+    const registry = yield* Service;
+    return (yield* Effect.promise(() => registry.query(queryOrFilter as any).run())) as any;
+  });

package/src/Relation.test.ts

@@ -44,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();
@@ -61,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('com.example.type.has-manager');
-      expect(Relation.getTypename(snapshot)).toBe('com.example.type.has-manager');
+      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();