@dxos/echo 0.8.4-main.fffef41 → 0.8.4-staging.60fe92afc8

package/src/QueryResult.ts

@@ -0,0 +1,132 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type * as Atom from '@effect-atom/atom/Atom';
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+
+import { type CleanupFn } from '@dxos/async';
+
+import type * as Entity from './Entity';
+
+/**
+ * Individual query result entry.
+ */
+export type Entry<T> = {
+  id: string;
+
+  /**
+   * May not be present for remote results.
+   */
+  result?: T;
+
+  match?: {
+    // TODO(dmaretskyi): text positional info.
+
+    /**
+     * Higher means better match.
+     */
+    rank: number;
+  };
+
+  /**
+   * Query resolution metadata.
+   */
+  // TODO(dmaretskyi): Rename to meta?
+  resolution?: {
+    // TODO(dmaretskyi): Make this more generic.
+    source: 'remote' | 'local' | 'index';
+
+    /**
+     * Query resolution time in milliseconds.
+     */
+    time: number;
+  };
+};
+
+/**
+ * Invidual query result entry for a database Entity.
+ */
+export type EntityEntry<T extends Entity.Unknown = Entity.Unknown> = Entry<T>;
+
+export type RunOptions = {
+  timeout?: number;
+};
+
+export type SubscriptionOptions = {
+  /**
+   * Fire the callback immediately.
+   */
+  fire?: boolean;
+};
+
+// TODO(burdon): Should T be constrained to Entity.Any?
+export interface QueryResult<T> {
+  /**
+   * Currently available results along with their match metadata.
+   */
+  readonly entries: Entry<T>[];
+
+  /**
+   * Currently available results.
+   */
+  readonly results: T[];
+
+  /**
+   * Returns all known results.
+   */
+  run(opts?: RunOptions): Promise<T[]>;
+
+  /**
+   * Returns all known results along with their match metadata.
+   */
+  runEntries(opts?: RunOptions): Promise<Entry<T>[]>;
+
+  /**
+   * Returns currently available results synchronously.
+   */
+  runSync(): T[];
+
+  /**
+   * Returns currently available results synchronously along with their match metadata.
+   */
+  runSyncEntries(): Entry<T>[];
+
+  /**
+   * Returns first result.
+   */
+  first(opts?: RunOptions): Promise<T>;
+
+  /**
+   * Returns first result if there is one.
+   */
+  firstOrUndefined(opts?: RunOptions): Promise<T | undefined>;
+
+  /**
+   * Subscribes to changes in query results.
+   */
+  subscribe(callback?: (query: QueryResult<T>) => void, opts?: SubscriptionOptions): CleanupFn;
+
+  /**
+   * Self-updating atom. Updates automatically when query results change.
+   *
+   * Memoized per QueryResult instance — repeated accesses on the same instance return the same
+   * Atom. Safe only when the QueryResult is itself held stable across re-renders (e.g. behind a
+   * `useMemo`). It must NOT be used in graph-builder connectors/actions or other atom computes,
+   * where `db.query(...)` is called fresh on each re-evaluation: every run constructs a new
+   * QueryResult and so a new atom + subscription, leaking the previous ones. Use the memoized
+   * {@link atom} family there instead.
+   */
+  readonly atom: Atom.Atom<T[]>;
+}
+
+/**
+ * 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>;
+
+  // TODO(dmaretskyi): Considering adding `atom`, but since `Database.query` is used in imperative code only, I dont think it will be useful.
+}

package/src/Ref.ts

@@ -2,27 +2,115 @@
 // Copyright 2025 DXOS.org
 //
 
-import * as EchoSchema from './internal';
+// @import-as-namespace
+
+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.
+ *
+ * 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>;
 
-export type Ref<T> = EchoSchema.Ref<T>;
-export type Any = EchoSchema.Ref<Obj.Any>;
+/**
+ * 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 = EchoSchema.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 Any> = R extends EchoSchema.Ref<infer T> ? T : never;
+export type Target<R extends Unknown> = R extends refInternal.Ref<infer T> ? T : never;
 
 /**
  * Reference resolver.
  */
-export type Resolver = EchoSchema.RefResolver;
+export type Resolver = refInternal.RefResolver;
+
+export const isRef: (value: unknown) => value is Unknown = refInternal.Ref.isRef;
+
+export const make = refInternal.Ref.make;
 
-export const isRef: (value: unknown) => value is Any = EchoSchema.Ref.isRef;
+// TODO(dmaretskyi): Consider just allowing `make` to accept URI.
+export const fromURI = (uri: URI.URI): refInternal.Ref<any> => refInternal.Ref.fromURI(uri);
 
-export const make = EchoSchema.Ref.make;
+export const hasEntityId = refInternal.Ref.hasEntityId;
 
-// TODO(dmaretskyi): Consider just allowing `make` to accept DXN.
-export const fromDXN = EchoSchema.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 } = refInternal.getSchemaReference(jsonSchema) ?? {};
+      return typename ? Option.some(true) : Option.some(false);
+    }),
+    Option.getOrElse(() => false),
+  );
+};

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-client`; 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-client`).
+ */
+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.query} `.run` 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

@@ -0,0 +1,88 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import * as Entity from './Entity';
+import { SnapshotKindId } from './internal';
+import * as Obj from './Obj';
+import * as Relation from './Relation';
+import { TestSchema } from './testing';
+
+describe('Relation', () => {
+  describe('Snapshot', () => {
+    test('getSnapshot returns an immutable snapshot with SnapshotKindId', ({ expect }) => {
+      const obj1 = Obj.make(TestSchema.Person, { name: 'Alice' });
+      const obj2 = Obj.make(TestSchema.Person, { name: 'Bob' });
+      const rel = Relation.make(TestSchema.HasManager, {
+        [Relation.Source]: obj1,
+        [Relation.Target]: obj2,
+      });
+      const snapshot = Relation.getSnapshot(rel);
+
+      // Snapshot has SnapshotKindId, not KindId.
+      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);
+    });
+
+    test('read-only helpers work with both reactive and snapshot', ({ expect }) => {
+      const obj1 = Obj.make(TestSchema.Person, { name: 'Alice' });
+      const obj2 = Obj.make(TestSchema.Person, { name: 'Bob' });
+      const rel = Relation.make(TestSchema.HasManager, {
+        [Relation.Source]: obj1,
+        [Relation.Target]: obj2,
+      });
+      const snapshot = Relation.getSnapshot(rel);
+
+      // getSourceURI - works with both.
+      expect(Relation.getSourceURI(rel)).toBeDefined();
+      expect(Relation.getSourceURI(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();
+      expect(Relation.getSource(snapshot)).toBeDefined();
+
+      // getTarget - works with both.
+      expect(Relation.getTarget(rel)).toBeDefined();
+      expect(Relation.getTarget(snapshot)).toBeDefined();
+
+      // getDXN - works with both.
+      expect(Relation.getURI(rel)).toBeDefined();
+      expect(Relation.getURI(snapshot)).toBeDefined();
+
+      // getTypename - works with both.
+      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();
+      expect(Relation.getMeta(snapshot)).toBeDefined();
+
+      // isDeleted - works with both.
+      expect(Relation.isDeleted(rel)).toBe(false);
+      expect(Relation.isDeleted(snapshot)).toBe(false);
+
+      // version - works with both.
+      expect(Relation.version(rel)).toBeDefined();
+      expect(Relation.version(snapshot)).toBeDefined();
+
+      // toJSON - works with both.
+      expect(Relation.toJSON(rel)).toBeDefined();
+      expect(Relation.toJSON(snapshot)).toBeDefined();
+    });
+  });
+});