@dxos/echo 0.10.0 → 0.11.0

package/src/Database.ts

@@ -2,17 +2,17 @@
 // Copyright 2025 DXOS.org
 //
 
-// @import-as-namespace
-
 import * as Context from 'effect/Context';
 import * as Effect from 'effect/Effect';
 import * as Layer from 'effect/Layer';
 import * as Schema from 'effect/Schema';
+import * as Stream from 'effect/Stream';
 
-import { EffectEx } from '@dxos/effect';
+import type { CleanupFn } from '@dxos/async';
 import { invariant } from '@dxos/invariant';
 import { type SpaceId, type URI } from '@dxos/keys';
 
+import type * as Blob from './Blob';
 import type * as Entity from './Entity';
 import * as Err from './Err';
 import type * as Feed from './Feed';
@@ -62,6 +62,14 @@ export type AddOptions = {
    * @default 'linked-doc'
    */
   placeIn?: ObjectPlacement;
+
+  /**
+   * Append the object to this feed instead of the automerge-backed space database. The object is
+   * returned synchronously (a live feed object) and persisted in the background — confirm the write
+   * completed with {@link Database.flush}. Synchronous alternative to the async
+   * {@link Database.appendToFeed}; `placeIn` is ignored when set.
+   */
+  to?: Feed.Feed;
 };
 
 /**
@@ -94,6 +102,18 @@ export type FlushOptions = {
   updates?: boolean;
 };
 
+/**
+ * A caller-owned, writable **independent instance** of one object bound to one branch: a distinct
+ * object instance (not a UI surface), separate from the device-global canonical object.
+ * @see Database.branch
+ */
+export type BranchBinding<T extends Obj.Unknown = Obj.Unknown> = {
+  /** Live object bound to the branch document (`'main'` -> the canonical live object). */
+  readonly object: T;
+  /** Release the binding (drops the doc-handle listener; never deletes the branch document). */
+  dispose(): void;
+};
+
 /**
  * Identifier denoting an ECHO Database.
  */
@@ -148,6 +168,8 @@ export interface Database extends Queryable {
    *
    * Only Object and Relation entities are accepted. To persist a Type definition use
    * {@link addType} — passing a Type entity is rejected at compile time (and at runtime).
+   *
+   * Pass `{ to: feed }` to append to a feed instead (synchronous; confirm with {@link flush}).
    */
   add<T extends Entity.Unknown = Entity.Unknown>(obj: T & RejectTypeEntity<T>, opts?: AddOptions): T;
 
@@ -185,15 +207,64 @@ export interface Database extends Queryable {
    */
   flush(opts?: FlushOptions): Promise<void>;
 
+  //
+  // Branching. A branch is a writable alternate timeline of an object subtree (same object ids,
+  // shared automerge history, true CRDT merge-back). The registry is synced on the space root;
+  // the currently-viewed branch stays device-local.
+  //
+
   /**
-   * Removes feed items by ID.
+   * The device-global current branch for an object id (`'main'` by default).
+   * @deprecated Prefer `Obj.getBranch(obj)` — it takes the object and reports the branch of that
+   * specific instance (including `db.branch()` independent instances), not just the device selection.
    */
-  removeFeedItemsByIds(feed: Feed.Feed, ids: string[]): Promise<void>;
+  getCurrentBranch(objectId: string): string;
+
+  /**
+   * An immutable snapshot of the object at the given historical heads — a detached instance, not a
+   * pin on the live object. Prefer `Obj.getVersion(obj, heads)`.
+   */
+  getVersion<T extends Obj.Unknown>(obj: T, heads: readonly string[]): Obj.Snapshot<T>;
+
+  /** All branch names available for an object, including the implicit `'main'` (always first). */
+  listBranches(objectId: string): string[];
+
+  /**
+   * Fork the object and its referenced subtree into a new branch (does not switch to it).
+   * @param opts.fromHeads Fork from a historical frontier instead of the tip (a bare heads array
+   *   applies to the root only; a map forks each member from its own frontier).
+   */
+  createBranch(
+    rootObjectId: string,
+    name: string,
+    opts?: { fromHeads?: readonly string[] | Record<string, readonly string[]> },
+  ): Promise<void>;
+
+  /** Switch the object's subtree to a branch (or back to `'main'`). Device-local; cascades to children. */
+  switchBranch(rootObjectId: string, name: string): Promise<void>;
+
+  /** Merge a branch back into main across the subtree, then switch back to main. */
+  mergeBranch(rootObjectId: string, name: string, opts?: { deleteAfter?: boolean }): Promise<void>;
+
+  /** Fold main's changes into a branch across the subtree (the reverse of {@link mergeBranch}). */
+  syncBranch(rootObjectId: string, name: string): Promise<void>;
+
+  /** Delete a branch (its documents lose their sync reference). Cannot delete `'main'`. */
+  deleteBranch(rootObjectId: string, name: string): void;
+
+  /**
+   * Create a caller-owned, writable binding to one branch of one object — a live object whose reads
+   * resolve the branch document and whose writes land on the branch document only. Multiple bindings
+   * to different branches of the same object may coexist; the device-global current branch and other
+   * bindings are unaffected. Binding to `'main'` returns the canonical live object. Bindings are
+   * ephemeral and never persisted — the caller must `dispose()`.
+   */
+  branch<T extends Obj.Unknown>(obj: T, name: string): Promise<BranchBinding<T>>;
 
   /**
-   * Queries items in a feed associated with this database.
+   * Removes feed items by ID.
    */
-  queryFeed(feed: Feed.Feed, queryOrFilter: Query.Any | Filter.Any): QueryResult.QueryResult<any>;
+  removeFeedItemsByIds(feed: Feed.Feed, ids: string[]): Promise<void>;
 
   /**
    * Syncs a feed with the server.
@@ -204,6 +275,49 @@ export interface Database extends Queryable {
    * Returns queue replication backlog for the feed's namespace.
    */
   getFeedSyncState(feed: Feed.Feed): Promise<Feed.SyncState>;
+
+  /**
+   * Disposes and drops the in-memory handle (live working-set / core cache) for a feed, so the next
+   * access re-reads it cold. Advanced cache-control; primarily used by tests to model a spawned
+   * process reading the feed with an empty in-memory cache. Public (not `_`-prefixed) so it survives
+   * declaration stripping for cross-package test use.
+   */
+  evictFeedHandle(feed: Feed.Feed): Promise<void>;
+
+  /**
+   * Hashes and uploads `bytes` via the chosen storage backend, returning an un-added Blob object.
+   * Rejects with `Err.BlobTooLargeError` (over inline storage's fixed cap, or the backend's own
+   * `maxSize`), `Err.BlobWriteError` (backend upload failure), or `Err.BlobNotAvailableError`
+   * (`reason: 'backend-not-registered'` — the requested storage name has no registered backend).
+   */
+  createBlob(bytes: Uint8Array, options?: { type?: string; storage?: string }): Promise<Blob.Blob>;
+
+  /**
+   * Loads a blob's bytes. Rejects with `Err.BlobNotAvailableError` if the backend for the blob's
+   * storage scheme is not registered, offline, or cannot find the bytes.
+   */
+  readBlob(blob: Blob.Blob): Promise<Uint8Array>;
+
+  /**
+   * Checks whether a blob's bytes are currently available.
+   */
+  blobExists(blob: Blob.Blob): Promise<boolean>;
+
+  /**
+   * Returns a renderable URL for the blob, if one can be produced.
+   */
+  getBlobUrl(blob: Blob.Blob): Promise<string | undefined>;
+
+  /**
+   * Get the current combined (automerge documents + feed blocks) sync state, reported against a
+   * single remote peer.
+   */
+  getSyncState(options?: GetSyncStateOptions): Promise<SyncState>;
+
+  /**
+   * Subscribe to combined sync state changes.
+   */
+  subscribeToSyncState(cb: (state: SyncState) => void, options?: GetSyncStateOptions): CleanupFn;
 }
 
 export const isDatabase = (obj: unknown): obj is Database => {
@@ -276,7 +390,7 @@ export const resolve: {
   Effect.gen(function* () {
     const { db } = yield* Service;
     const dxn = typeof ref === 'string' ? ref : ref.uri;
-    const object = yield* EffectEx.promiseWithCauseCapture(() =>
+    const object = yield* Effect.promise(() =>
       db.graph
         .createRefResolver({
           context: {
@@ -307,7 +421,7 @@ export const resolve: {
  */
 export const load: <T>(ref: Ref<T>) => Effect.Effect<T, Err.EntityNotFoundError, never> = Effect.fn('Database.load')(
   function* (ref) {
-    const object = yield* EffectEx.promiseWithCauseCapture(() => ref.tryLoad());
+    const object = yield* Effect.promise(() => ref.tryLoad());
     if (!object) {
       return yield* Effect.fail(new Err.EntityNotFoundError(ref.uri));
     }
@@ -319,6 +433,9 @@ export const load: <T>(ref: Ref<T>) => Effect.Effect<T, Err.EntityNotFoundError,
  * Adds an object or relation to the database.
  * @see {@link Database.add}
  */
+// The Effect wrapper intentionally omits the method's `opts` (e.g. `{ to: feed }`): it is applied
+// point-free (`Effect.forEach(Database.add)`), where a second parameter would collide with the
+// iteratee index. Effect-style feed appends go through `Database.appendToFeed` / `Feed.append`.
 export const add = <T extends Entity.Unknown>(obj: T & RejectTypeEntity<T>): Effect.Effect<T, never, Service> =>
   Service.pipe(Effect.map(({ db }) => db.add<T>(obj))).pipe(Effect.withSpan('Database.add'));
 
@@ -327,7 +444,7 @@ export const add = <T extends Entity.Unknown>(obj: T & RejectTypeEntity<T>): Eff
  * @see {@link Database.addType}
  */
 export const addType = <T extends Type.AnyEntity>(type: T): Effect.Effect<T, never, Service> =>
-  Service.pipe(Effect.flatMap(({ db }) => EffectEx.promiseWithCauseCapture(() => db.addType(type)))).pipe(
+  Service.pipe(Effect.flatMap(({ db }) => Effect.promise(() => db.addType(type)))).pipe(
     Effect.withSpan('Database.addType'),
   );
 
@@ -343,25 +460,25 @@ export const remove = <T extends Entity.Unknown>(obj: T): Effect.Effect<void, ne
  * @see {@link Database.appendToFeed}
  */
 export const appendToFeed = (feed: Feed.Feed, entities: Entity.Unknown[]): Effect.Effect<void, never, Service> =>
-  Service.pipe(
-    Effect.flatMap(({ db }) => EffectEx.promiseWithCauseCapture(() => db.appendToFeed(feed, entities))),
-  ).pipe(Effect.withSpan('Database.appendToFeed'));
+  Service.pipe(Effect.flatMap(({ db }) => Effect.promise(() => db.appendToFeed(feed, entities)))).pipe(
+    Effect.withSpan('Database.appendToFeed'),
+  );
 
 /**
  * Removes entities from a feed.
  * @see {@link Database.deleteFromFeed}
  */
 export const deleteFromFeed = (feed: Feed.Feed, entities: Entity.Unknown[]): Effect.Effect<void, never, Service> =>
-  Service.pipe(
-    Effect.flatMap(({ db }) => EffectEx.promiseWithCauseCapture(() => db.deleteFromFeed(feed, entities))),
-  ).pipe(Effect.withSpan('Database.deleteFromFeed'));
+  Service.pipe(Effect.flatMap(({ db }) => Effect.promise(() => db.deleteFromFeed(feed, entities)))).pipe(
+    Effect.withSpan('Database.deleteFromFeed'),
+  );
 
 /**
  * Flushes pending changes to disk.
  * @see {@link Database.flush}
  */
 export const flush = (opts?: FlushOptions) =>
-  Service.pipe(Effect.flatMap(({ db }) => EffectEx.promiseWithCauseCapture(() => db.flush(opts)))).pipe(
+  Service.pipe(Effect.flatMap(({ db }) => Effect.promise(() => db.flush(opts)))).pipe(
     Effect.withSpan('Database.flush'),
   );
 
@@ -377,3 +494,76 @@ export const query: {
     Effect.withSpan('Database.query'),
     queryInternal.makeQueryResultEffect,
   );
+
+/**
+ * Sync state of the database in relation to EDGE.
+ */
+export interface SyncState {
+  //
+  // Automerge
+  //
+
+  /**
+   * Total number of documents locally.
+   */
+  readonly localDocumentCount: number;
+  /**
+   * Total number of documents on the remote peer.
+   */
+  readonly remoteDocumentCount: number;
+  /**
+   * Total number of documents across this peer and the remote peer.
+   */
+  readonly totalDocumentCount: number;
+  /**
+   * Total number of documents that are not synced.
+   * Includes documents that are present only locally, only on the remote peer, or whether the peers have different versions.
+   */
+  readonly unsyncedDocumentCount: number;
+
+  //
+  // Feeds.
+  //
+
+  /**
+   * Blocks still to pull from remote. 0 when caught up.
+   */
+  readonly blocksToPull: string;
+  /**
+   * Unpositioned blocks still to push to remote. 0 when caught up.
+   */
+  readonly blocksToPush: string;
+  /**
+   * Total blocks stored locally for this namespace in the space.
+   */
+  readonly totalBlocks: string;
+}
+
+/**
+ * Options for reading combined sync state.
+ */
+export interface GetSyncStateOptions {
+  /**
+   * Peer to report the automerge document backlog against. Defaults to the EDGE peer.
+   * Provide explicitly in local/test topologies where there is no EDGE peer.
+   */
+  readonly peerId?: string;
+}
+
+/**
+ * Get the current sync state.
+ */
+export const getSyncState = (options?: GetSyncStateOptions): Effect.Effect<SyncState, never, Service> =>
+  Service.pipe(Effect.flatMap(({ db }) => Effect.promise(() => db.getSyncState(options))));
+
+/**
+ * Subscribe to sync state changes.
+ */
+export const subscribeToSyncState = (options?: GetSyncStateOptions): Stream.Stream<SyncState, never, Service> =>
+  Stream.asyncScoped((emit) =>
+    Effect.gen(function* () {
+      const { db } = yield* Service;
+      const cleanup = db.subscribeToSyncState((state) => emit.single(state), options);
+      yield* Effect.addFinalizer(() => Effect.sync(cleanup));
+    }),
+  );

package/src/Err.ts

@@ -41,6 +41,42 @@ export class TextEditNotFoundError extends BaseError.extend('TextEditNotFoundErr
   }
 }
 
+/**
+ * Thrown when a blob's bytes exceed the size limit of the storage backend writing them (inline
+ * storage's fixed cap, or a registered backend's own `maxSize`).
+ */
+export class BlobTooLargeError extends BaseError.extend('BlobTooLargeError', 'Blob is too large for its backend') {
+  constructor(context: { size: number; limit: number }, options?: BaseErrorOptions) {
+    super({ context, ...options });
+  }
+}
+
+/**
+ * Reason why a blob's bytes could not be read.
+ * - `offline`: The backend's transport failed (e.g. network unavailable).
+ * - `not-found`: The backend could not locate the bytes for the given URI.
+ * - `backend-not-registered`: No backend is registered for the URI's scheme.
+ */
+export type BlobNotAvailableReason = 'offline' | 'not-found' | 'backend-not-registered';
+
+/**
+ * Thrown when a blob's bytes cannot be read from its backend.
+ */
+export class BlobNotAvailableError extends BaseError.extend('BlobNotAvailableError', 'Blob is not available') {
+  constructor(context: { backend: string; key: string; reason: BlobNotAvailableReason }, options?: BaseErrorOptions) {
+    super({ context, ...options });
+  }
+}
+
+/**
+ * Thrown when a blob's bytes fail to upload to its backend.
+ */
+export class BlobWriteError extends BaseError.extend('BlobWriteError', 'Failed to write blob') {
+  constructor(context: { backend: string }, options?: BaseErrorOptions) {
+    super({ context, ...options });
+  }
+}
+
 /**
  * Reason why getting a reactive object from a snapshot failed.
  * - `no-database`: The snapshot is not associated with a database.

package/src/Feed.test.ts

@@ -0,0 +1,188 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import * as Feed from './Feed';
+import * as Obj from './Obj';
+import { TestSchema } from './testing';
+
+describe('Feed', () => {
+  describe('getParent / setParent', () => {
+    test('an item has no explicit parent by default', ({ expect }) => {
+      expect(Feed.getParent(message('m1'))).toBeUndefined();
+    });
+
+    test('round-trips a parent set from an item', ({ expect }) => {
+      const m1 = message('m1');
+      const m2 = message('m2');
+      Feed.setParent(m2, m1);
+      expect(Feed.getParent(m2)).toBe(m1.id);
+    });
+
+    test('round-trips a parent set from an id', ({ expect }) => {
+      const m1 = message('m1');
+      const m2 = message('m2');
+      Feed.setParent(m2, m1.id);
+      expect(Feed.getParent(m2)).toBe(m1.id);
+    });
+
+    test('re-setting replaces rather than accumulates', ({ expect }) => {
+      const m1 = message('m1');
+      const m2 = message('m2');
+      const m3 = message('m3');
+      Feed.setParent(m3, m1);
+      Feed.setParent(m3, m2);
+      expect(Feed.getParent(m3)).toBe(m2.id);
+      expect(Obj.getKeys(m3, Feed.PARENT_KEY)).toHaveLength(1);
+    });
+
+    test('undefined clears the parent', ({ expect }) => {
+      const m1 = message('m1');
+      const m2 = message('m2');
+      Feed.setParent(m2, m1);
+      Feed.setParent(m2, undefined);
+      expect(Feed.getParent(m2)).toBeUndefined();
+    });
+  });
+
+  describe('history', () => {
+    test('a feed with no lineage resolves to itself', ({ expect }) => {
+      const items = [message('m1'), message('m2'), message('m3')];
+      const history = Feed.history(items);
+      expect(titles(history)).toEqual(['m1', 'm2', 'm3']);
+      expect(history.shallow).toBe(false);
+    });
+
+    test('an empty feed resolves to nothing', ({ expect }) => {
+      const history = Feed.history([]);
+      expect(history.items).toEqual([]);
+      expect(history.shallow).toBe(false);
+    });
+
+    // The worked example: forking from m3 abandons m4 without removing it from the log.
+    test('a fork discards the items appended between the parent and the fork', ({ expect }) => {
+      const [m1, m2, m3, m4, m5] = [message('m1'), message('m2'), message('m3'), message('m4'), message('m5')];
+      Feed.setParent(m5, m3);
+      const history = Feed.history([m1, m2, m3, m4, m5]);
+      expect(titles(history)).toEqual(['m1', 'm2', 'm3', 'm5']);
+      expect(history.shallow).toBe(false);
+    });
+
+    // Latest-wins: a second fork from m4 makes m4's branch live again and hides m5.
+    test('the most recently appended branch wins', ({ expect }) => {
+      const [m1, m2, m3, m4, m5, m6] = [
+        message('m1'),
+        message('m2'),
+        message('m3'),
+        message('m4'),
+        message('m5'),
+        message('m6'),
+      ];
+      Feed.setParent(m5, m3);
+      Feed.setParent(m6, m4);
+      const history = Feed.history([m1, m2, m3, m4, m5, m6]);
+      expect(titles(history)).toEqual(['m1', 'm2', 'm3', 'm4', 'm6']);
+      expect(history.shallow).toBe(false);
+    });
+
+    test('items appended after a fork chain onto it implicitly', ({ expect }) => {
+      const [m1, m2, m3, m4, m5, m6] = [
+        message('m1'),
+        message('m2'),
+        message('m3'),
+        message('m4'),
+        message('m5'),
+        message('m6'),
+      ];
+      Feed.setParent(m5, m3);
+      const history = Feed.history([m1, m2, m3, m4, m5, m6]);
+      expect(titles(history)).toEqual(['m1', 'm2', 'm3', 'm5', 'm6']);
+    });
+
+    test('consecutive forks from the same parent keep only the last', ({ expect }) => {
+      const [m1, m2, m3, m4] = [message('m1'), message('m2'), message('m3'), message('m4')];
+      Feed.setParent(m3, m1);
+      Feed.setParent(m4, m1);
+      const history = Feed.history([m1, m2, m3, m4]);
+      expect(titles(history)).toEqual(['m1', 'm4']);
+    });
+
+    describe('head', () => {
+      test('resolves an abandoned branch when given its leaf', ({ expect }) => {
+        const [m1, m2, m3, m4, m5] = [message('m1'), message('m2'), message('m3'), message('m4'), message('m5')];
+        Feed.setParent(m5, m3);
+        const history = Feed.history([m1, m2, m3, m4, m5], { head: m4 });
+        expect(titles(history)).toEqual(['m1', 'm2', 'm3', 'm4']);
+        expect(history.shallow).toBe(false);
+      });
+
+      test('accepts an id', ({ expect }) => {
+        const [m1, m2, m3] = [message('m1'), message('m2'), message('m3')];
+        const history = Feed.history([m1, m2, m3], { head: m2.id });
+        expect(titles(history)).toEqual(['m1', 'm2']);
+      });
+
+      test('an unknown head resolves to nothing and reports truncation', ({ expect }) => {
+        const history = Feed.history([message('m1')], { head: message('absent') });
+        expect(history.items).toEqual([]);
+        expect(history.shallow).toBe(true);
+      });
+    });
+
+    describe('truncation', () => {
+      // A parent may legitimately be missing under partial replication, or because the caller's
+      // filter excluded it.
+      test('an absent parent stops the walk', ({ expect }) => {
+        const [m1, m2] = [message('m1'), message('m2')];
+        Feed.setParent(m2, message('unreplicated'));
+        const history = Feed.history([m1, m2]);
+        expect(titles(history)).toEqual(['m2']);
+        expect(history.shallow).toBe(true);
+      });
+
+      test('a forward reference terminates the walk', ({ expect }) => {
+        const [m1, m2] = [message('m1'), message('m2')];
+        Feed.setParent(m1, m2);
+        const history = Feed.history([m1, m2]);
+        expect(titles(history)).toEqual(['m1', 'm2']);
+        expect(history.shallow).toBe(true);
+      });
+
+      test('a self-reference terminates the walk', ({ expect }) => {
+        const m1 = message('m1');
+        Feed.setParent(m1, m1);
+        const history = Feed.history([m1]);
+        expect(titles(history)).toEqual(['m1']);
+        expect(history.shallow).toBe(true);
+      });
+
+      // A malformed replicated id must not read as "no parent" — that would resolve the fork as an
+      // implicit continuation and resurrect the items it abandoned.
+      test('a malformed parent id truncates rather than falling through to the predecessor', ({ expect }) => {
+        const [m1, m2, m3] = [message('m1'), message('m2'), message('m3')];
+        corruptParent(m3);
+        const history = Feed.history([m1, m2, m3]);
+        expect(titles(history)).toEqual(['m3']);
+        expect(history.shallow).toBe(true);
+      });
+
+      test('getParent reports a malformed parent as undefined', ({ expect }) => {
+        const m1 = message('m1');
+        corruptParent(m1);
+        expect(Feed.getParent(m1)).toBeUndefined();
+      });
+    });
+  });
+});
+
+const message = (title: string) => Obj.make(TestSchema.Task, { title });
+
+const titles = (history: Feed.History<TestSchema.Task>) => history.items.map((item) => item.title);
+
+/** Writes an unparseable lineage id, standing in for a corrupted or future-format replicated block. */
+const corruptParent = (task: TestSchema.Task) =>
+  Obj.update(task, (task) => {
+    Obj.getMeta(task).keys.push({ source: Feed.PARENT_KEY, id: 'not-a-ulid' });
+  });