@nebutra/collab 0.2.2 → 0.2.3

package/src/__tests__/collab.test.ts

@@ -1,240 +0,0 @@
-import { _resetTenantLocks } from "@nebutra/tenant-store";
-import { beforeEach, describe, expect, it } from "vitest";
-import * as Y from "yjs";
-import { CollabError, createCollab } from "../index";
-import { InMemorySnapshotStore } from "../store/memory";
-import { LoopbackTransport } from "../transport/loopback";
-
-describe("CRDT convergence", () => {
-  beforeEach(() => _resetTenantLocks());
-
-  it("two clients editing the SAME room converge to identical state", async () => {
-    const hub = createCollab();
-    const a = hub.room("t1", "r1");
-
-    // A separate client doc, simulating a remote peer on the same logical room.
-    const peer = new Y.Doc();
-
-    // Edit on hub side.
-    a.doc.getMap("m").set("from", "a");
-    // Ship A's update to the peer.
-    peer.transact(() => Y.applyUpdate(peer, a.encodeState()));
-
-    // Peer edits concurrently.
-    peer.getMap("m").set("from", "b-peer");
-    peer.getArray("list").push([1, 2, 3]);
-
-    // Exchange peer -> A.
-    a.applyUpdate(Y.encodeStateAsUpdate(peer));
-    // Exchange A -> peer (A may have other state).
-    Y.applyUpdate(peer, a.encodeState());
-
-    // Both sides must converge to identical serialized state.
-    const aState = JSON.stringify(a.doc.getMap("m").toJSON());
-    const peerState = JSON.stringify(peer.getMap("m").toJSON());
-    expect(aState).toBe(peerState);
-    expect(a.doc.getArray("list").toJSON()).toEqual([1, 2, 3]);
-  });
-});
-
-describe("tenant isolation (security-critical)", () => {
-  beforeEach(() => _resetTenantLocks());
-
-  it("room(tenantA) and room(tenantB) with same roomId are independent docs", () => {
-    const hub = createCollab();
-    const a = hub.room("tenantA", "r1");
-    const b = hub.room("tenantB", "r1");
-
-    expect(a.doc).not.toBe(b.doc);
-
-    a.doc.getMap("m").set("secret", "A-only");
-    // B's room must NEVER observe A's update.
-    expect(b.doc.getMap("m").get("secret")).toBeUndefined();
-  });
-
-  it("an update applied to A's room never appears in B's room", () => {
-    const hub = createCollab();
-    const a = hub.room("tenantA", "r1");
-    const b = hub.room("tenantB", "r1");
-
-    const seenByB: Uint8Array[] = [];
-    b.onUpdate((u) => seenByB.push(u));
-
-    a.doc.getMap("m").set("x", 1);
-    a.applyUpdate(Y.encodeStateAsUpdate(a.doc));
-
-    expect(seenByB).toHaveLength(0);
-    expect(b.doc.getMap("m").get("x")).toBeUndefined();
-  });
-
-  it("snapshot store for tenant A never returns tenant B state", async () => {
-    const store = new InMemorySnapshotStore();
-    const hub = createCollab({ store });
-
-    const a = hub.room("tenantA", "shared-room-id");
-    a.doc.getMap("m").set("owner", "A");
-    await a.snapshot();
-
-    // B asks for the SAME roomId — must get nothing from A.
-    const bState = await store.load("tenantB", "shared-room-id");
-    expect(bState).toBeNull();
-
-    const aState = await store.load("tenantA", "shared-room-id");
-    expect(aState).not.toBeNull();
-  });
-
-  it("returns the SAME room instance for repeated (tenant, room) calls", () => {
-    const hub = createCollab();
-    expect(hub.room("t1", "r1")).toBe(hub.room("t1", "r1"));
-    expect(hub.room("t1", "r1")).not.toBe(hub.room("t2", "r1"));
-  });
-});
-
-describe("transport-driven convergence", () => {
-  beforeEach(() => _resetTenantLocks());
-
-  it("separate hubs sharing a transport converge for the same tenant+room", () => {
-    const transport = new LoopbackTransport();
-    const hubA = createCollab({ transport });
-    const hubB = createCollab({ transport });
-    const ra = hubA.room("t1", "r1");
-    const rb = hubB.room("t1", "r1");
-
-    ra.doc.getMap("m").set("k", "v");
-    expect(rb.doc.getMap("m").get("k")).toBe("v");
-
-    // Reverse direction also converges (origin guard prevents a loop).
-    rb.doc.getArray("l").push([42]);
-    expect(ra.doc.getArray("l").toJSON()).toEqual([42]);
-
-    hubA.destroy();
-    hubB.destroy();
-  });
-
-  it("a destroyed room throws CollabError COLLAB_DESTROYED", () => {
-    const hub = createCollab();
-    const r = hub.room("t1", "r1");
-    r.destroy();
-    try {
-      r.encodeState();
-      throw new Error("should have thrown");
-    } catch (e) {
-      expect(e).toBeInstanceOf(CollabError);
-      expect((e as CollabError).code).toBe("COLLAB_DESTROYED");
-      expect((e as CollabError).suggestion.length).toBeGreaterThan(0);
-    }
-  });
-});
-
-describe("restore / snapshot failure surfaces CollabError", () => {
-  beforeEach(() => _resetTenantLocks());
-
-  it("roomRestored wraps a throwing store load", async () => {
-    const store = {
-      load: async () => {
-        throw new Error("db down");
-      },
-      save: async () => {},
-    };
-    const hub = createCollab({ store });
-    try {
-      await hub.roomRestored("t1", "r1");
-      throw new Error("should have thrown");
-    } catch (e) {
-      expect(e).toBeInstanceOf(CollabError);
-      expect((e as CollabError).code).toBe("COLLAB_RESTORE_FAILED");
-      expect((e as CollabError).suggestion.length).toBeGreaterThan(0);
-    }
-  });
-
-  it("snapshot wraps a throwing store save", async () => {
-    const store = {
-      load: async () => null,
-      save: async () => {
-        throw new Error("disk full");
-      },
-    };
-    const hub = createCollab({ store });
-    const r = hub.room("t1", "r1");
-    r.doc.getMap("m").set("a", 1);
-    try {
-      await r.snapshot();
-      throw new Error("should have thrown");
-    } catch (e) {
-      expect(e).toBeInstanceOf(CollabError);
-      expect((e as CollabError).code).toBe("COLLAB_SNAPSHOT_FAILED");
-      expect((e as CollabError).suggestion.length).toBeGreaterThan(0);
-    }
-  });
-});
-
-describe("snapshot + restore", () => {
-  beforeEach(() => _resetTenantLocks());
-
-  it("snapshot() then reload restores doc state", async () => {
-    const store = new InMemorySnapshotStore();
-    const hub1 = createCollab({ store });
-    const r1 = hub1.room("t1", "doc1");
-    r1.doc.getText("body").insert(0, "hello world");
-    await r1.snapshot();
-
-    // Fresh hub, same store — must hydrate from snapshot.
-    const hub2 = createCollab({ store });
-    const r2 = await hub2.roomRestored("t1", "doc1");
-    expect(r2.doc.getText("body").toString()).toBe("hello world");
-  });
-});
-
-describe("onUpdate subscription", () => {
-  beforeEach(() => _resetTenantLocks());
-
-  it("unsubscribe stops further callbacks", () => {
-    const hub = createCollab();
-    const r = hub.room("t1", "r1");
-    const seen: number[] = [];
-    const off = r.onUpdate(() => seen.push(1));
-
-    r.doc.getMap("m").set("a", 1);
-    expect(seen).toHaveLength(1);
-
-    off();
-    r.doc.getMap("m").set("b", 2);
-    expect(seen).toHaveLength(1);
-  });
-});
-
-describe("CollabError", () => {
-  it("carries a non-empty suggestion and a code", () => {
-    const err = new CollabError("something failed", {
-      code: "COLLAB_TEST",
-      suggestion: "do the thing differently",
-    });
-    expect(err).toBeInstanceOf(Error);
-    expect(err.code).toBe("COLLAB_TEST");
-    expect(err.suggestion.length).toBeGreaterThan(0);
-  });
-
-  it("throws CollabError with suggestion on empty tenantId", () => {
-    const hub = createCollab();
-    try {
-      hub.room("", "r1");
-      throw new Error("should have thrown");
-    } catch (e) {
-      expect(e).toBeInstanceOf(CollabError);
-      expect((e as CollabError).suggestion.length).toBeGreaterThan(0);
-    }
-  });
-});
-
-describe("doctor()", () => {
-  it("returns a structured health report in <3s", async () => {
-    const hub = createCollab();
-    const start = Date.now();
-    const report = await hub.doctor();
-    expect(Date.now() - start).toBeLessThan(3000);
-    expect(report.ok).toBe(true);
-    expect(report.checks.yjs.ok).toBe(true);
-    expect(report.checks.store.ok).toBe(true);
-    expect(report.checks.transport.ok).toBe(true);
-  });
-});

package/src/cli.ts

@@ -1,27 +0,0 @@
-/**
- * collab CLI — `doctor` (Yjs/store/transport health) and `debug <roomId>`
- * (open a real zero-config room, apply an update, report convergence state).
- * The doctor/debug argv switch is the shared `@nebutra/capability-kit`
- * runner; only the collab-specific probes live here.
- */
-
-import { runCapabilityCli } from "@nebutra/capability-kit";
-import { getCollab } from "./index";
-
-const hub = await getCollab();
-
-await runCapabilityCli({
-  capability: "collab",
-  doctor: () => hub.doctor(),
-  debug: (roomId?: string) => {
-    const tenantId = "debug-tenant";
-    const id = roomId ?? "debug-room";
-    const room = hub.room(tenantId, id);
-    const before = room.encodeState().length;
-    room.doc.getText("debug").insert(0, "hello canvas");
-    const after = room.encodeState().length;
-    const text = room.doc.getText("debug").toString();
-    room.destroy();
-    return { tenantId, roomId: id, encodedBytes: { before, after }, text };
-  },
-});

package/src/errors.ts

@@ -1,42 +0,0 @@
-/**
- * Every failure surfaced by this package is a `CollabError`. The contract is
- * deliberately strict: a machine-stable `code` and a human-actionable
- * `suggestion` are MANDATORY, so no code path can throw a bare `Error` that
- * leaves a caller without a remediation hint.
- *
- * Mechanics (code/suggestion/toJSON/empty-suggestion fallback) are inherited
- * from the shared `@nebutra/capability-kit` `CapabilityError`; this subclass
- * only pins collab's error name + its package-specific fallback wording, so
- * the observable contract is unchanged.
- */
-
-import { CapabilityError } from "@nebutra/capability-kit";
-
-export type CollabErrorCode =
-  | "COLLAB_INVALID_TENANT"
-  | "COLLAB_INVALID_ROOM"
-  | "COLLAB_SNAPSHOT_FAILED"
-  | "COLLAB_RESTORE_FAILED"
-  | "COLLAB_DESTROYED"
-  | "COLLAB_TEST"
-  | (string & {});
-
-export interface CollabErrorInit {
-  readonly code: CollabErrorCode;
-  /** A non-empty, actionable remediation hint. */
-  readonly suggestion: string;
-  readonly cause?: unknown;
-}
-
-export class CollabError extends CapabilityError {
-  declare readonly code: CollabErrorCode;
-
-  constructor(message: string, init: CollabErrorInit) {
-    super(message, init, {
-      name: "CollabError",
-      emptySuggestionFallback:
-        "No suggestion was provided. This is a bug in @nebutra/collab — " +
-        "report it with the failing operation.",
-    });
-  }
-}

package/src/index.ts

@@ -1,42 +0,0 @@
-/**
- * @nebutra/collab — multi-tenant, transport-agnostic real-time collaborative
- * sync layer.
- *
- * Sailor already had Pusher pub/sub (fire-and-forget broadcast) but no
- * conflict-free concurrent editing. This package fills that gap with
- * tenant-partitioned CRDT rooms built on Yjs (MIT). It is generic: a
- * node-graph canvas, a rich-text document, or any shared structure binds to
- * a `CollabRoom` and gets convergence for free.
- *
- * Multi-tenancy is NON-NEGOTIABLE. Rooms are hard-partitioned by `tenantId`:
- * a room handle is only ever produced by passing an explicit tenant, the
- * snapshot store and transport are addressed by (tenantId, roomId), and the
- * composite key uses a NUL separator so partitions cannot collide. See
- * `hub.ts` for the structural argument and `__tests__` for the proof.
- *
- * Zero-config: `getCollab()` with no args yields REAL (non-mock) CRDT
- * behaviour via an in-memory snapshot store (composed from
- * `@nebutra/tenant-store`) and an in-process loopback transport. Production
- * swaps a Prisma/Redis `SnapshotStore` and a Pusher/WebSocket
- * `CollabTransport` through the same interfaces (see README).
- *
- * This package keeps itself in the `active` tier of the three-tier module
- * lifecycle by shipping a real in-package caller of the exported factory —
- * see `examples/zero-config-convergence.ts`.
- */
-
-export type { CollabErrorCode, CollabErrorInit } from "./errors";
-export { CollabError } from "./errors";
-export { createCollab, getCollab } from "./hub";
-export { InMemorySnapshotStore } from "./store/memory";
-export { LoopbackTransport } from "./transport/loopback";
-export type {
-  CollabConfig,
-  CollabHub,
-  CollabRoom,
-  CollabTransport,
-  DoctorCheck,
-  DoctorReport,
-  SnapshotStore,
-  UpdateListener,
-} from "./types";

package/src/room.ts

@@ -1,130 +0,0 @@
-/**
- * A single tenant-scoped CRDT room. One `Y.Doc` per (tenant, room). The hub
- * owns the partitioning; this class assumes its `tenantId`/`roomId` are
- * already the partition it belongs to and never reaches outside them.
- *
- * Snapshot persistence is serialized through `withTenantLock(tenantId,
- * roomId, ...)` borrowed from `@nebutra/tenant-store` rather than a
- * hand-rolled mutex — same primitive used by canvas/reel, so a future swap
- * to a distributed lock changes one place.
- */
-
-import { withTenantLock } from "@nebutra/tenant-store";
-import * as Y from "yjs";
-import { CollabError } from "./errors";
-import type { CollabRoom, CollabTransport, SnapshotStore, UpdateListener } from "./types";
-
-/** Origin tag used when applying remote updates so we don't echo them back. */
-const REMOTE_ORIGIN = Symbol("collab.remote");
-
-export class Room implements CollabRoom {
-  readonly doc: Y.Doc;
-  private readonly listeners = new Set<UpdateListener>();
-  private readonly unsubTransport: () => void;
-  private destroyed = false;
-
-  constructor(
-    readonly tenantId: string,
-    readonly roomId: string,
-    private readonly store: SnapshotStore,
-    private readonly transport: CollabTransport,
-  ) {
-    this.doc = new Y.Doc();
-
-    // Fan local updates out to: registered listeners + the transport. The
-    // transport echo is guarded by origin so a remote-applied update is not
-    // re-broadcast into a loop.
-    this.doc.on("update", (update: Uint8Array, origin: unknown) => {
-      for (const cb of [...this.listeners]) cb(update, origin);
-      if (origin !== REMOTE_ORIGIN) {
-        void Promise.resolve(this.transport.broadcast(this.tenantId, this.roomId, update)).catch(
-          () => {
-            // Transport delivery is best-effort; CRDT state stays correct and
-            // converges on the next exchanged update. Swallowing here avoids
-            // an unhandled rejection from a flaky network adapter.
-          },
-        );
-      }
-    });
-
-    // Remote updates for THIS tenant-scoped channel only.
-    this.unsubTransport = this.transport.subscribe(this.tenantId, this.roomId, (update) => {
-      if (this.destroyed) return;
-      Y.applyUpdate(this.doc, update, REMOTE_ORIGIN);
-    });
-  }
-
-  applyUpdate(update: Uint8Array, origin?: unknown): void {
-    this.assertLive();
-    Y.applyUpdate(this.doc, update, origin);
-  }
-
-  encodeState(): Uint8Array {
-    this.assertLive();
-    return Y.encodeStateAsUpdate(this.doc);
-  }
-
-  onUpdate(cb: UpdateListener): () => void {
-    this.assertLive();
-    this.listeners.add(cb);
-    return () => {
-      this.listeners.delete(cb);
-    };
-  }
-
-  async snapshot(): Promise<void> {
-    this.assertLive();
-    const state = this.encodeState();
-    try {
-      // Serialize concurrent snapshots of the SAME room; different rooms (or
-      // the same room under another tenant) persist in parallel.
-      await withTenantLock(this.tenantId, this.roomId, () =>
-        this.store.save(this.tenantId, this.roomId, state),
-      );
-    } catch (cause) {
-      throw new CollabError(`Failed to persist snapshot for room "${this.roomId}".`, {
-        code: "COLLAB_SNAPSHOT_FAILED",
-        suggestion:
-          "Verify the configured SnapshotStore is reachable (DB/Redis up, " +
-          "credentials valid). The in-memory default never fails; a custom " +
-          "adapter likely threw.",
-        cause,
-      });
-    }
-  }
-
-  /** Hydrate this doc from persisted state, if any. Internal to the hub. */
-  async _restore(): Promise<void> {
-    try {
-      const persisted = await this.store.load(this.tenantId, this.roomId);
-      if (persisted) Y.applyUpdate(this.doc, persisted, REMOTE_ORIGIN);
-    } catch (cause) {
-      throw new CollabError(`Failed to restore room "${this.roomId}" from snapshot store.`, {
-        code: "COLLAB_RESTORE_FAILED",
-        suggestion:
-          "Check the SnapshotStore adapter's load() — it should resolve " +
-          "null (not throw) when no snapshot exists for the tenant+room.",
-        cause,
-      });
-    }
-  }
-
-  destroy(): void {
-    if (this.destroyed) return;
-    this.destroyed = true;
-    this.unsubTransport();
-    this.listeners.clear();
-    this.doc.destroy();
-  }
-
-  private assertLive(): void {
-    if (this.destroyed) {
-      throw new CollabError(`Room "${this.roomId}" was destroyed and can no longer be used.`, {
-        code: "COLLAB_DESTROYED",
-        suggestion:
-          "Acquire a fresh room via hub.room(tenantId, roomId) instead of " +
-          "reusing a destroyed instance.",
-      });
-    }
-  }
-}

package/src/store/memory.ts

@@ -1,43 +0,0 @@
-/**
- * Zero-config default `SnapshotStore`. The storage MECHANICS (composite-key
- * map, never returning rows across tenants) are NOT re-implemented here —
- * they are composed from `@nebutra/tenant-store`'s `InMemoryTenantStore`,
- * which already enforces tenant isolation structurally via its
- * `tenantId:id` key plus a defense-in-depth tenantId equality check.
- *
- * A production deployment swaps this for a Prisma/Redis adapter that
- * implements the same `SnapshotStore` interface; the README documents that
- * shape. The isolation property a Prisma adapter would get from RLS is here
- * provided by the borrowed composite key.
- */
-
-import { InMemoryTenantStore, type TenantOwned } from "@nebutra/tenant-store";
-import type { SnapshotStore } from "../types";
-
-interface SnapshotRow extends TenantOwned {
-  readonly tenantId: string;
-  readonly state: Uint8Array;
-}
-
-export class InMemorySnapshotStore implements SnapshotStore {
-  private readonly inner = new InMemoryTenantStore<SnapshotRow>();
-
-  async load(tenantId: string, roomId: string): Promise<Uint8Array | null> {
-    const row = await this.inner.read(tenantId, roomId);
-    return row ? row.state : null;
-  }
-
-  async save(tenantId: string, roomId: string, state: Uint8Array): Promise<void> {
-    // Copy so a later in-place mutation of the caller's buffer can't
-    // retroactively corrupt persisted state.
-    await this.inner.write(tenantId, roomId, {
-      tenantId,
-      state: Uint8Array.from(state),
-    });
-  }
-
-  /** Test helper. */
-  clear(): void {
-    this.inner.clear();
-  }
-}

package/src/types.ts

@@ -1,64 +0,0 @@
-import type { DoctorCheck, DoctorReportBase } from "@nebutra/capability-kit";
-import type * as Y from "yjs";
-
-/**
- * Pluggable persistence for encoded room state. State is an opaque Yjs
- * update (`Uint8Array`); this layer never interprets it. The tenant+room
- * pair is the partition key — adapters MUST scope reads/writes by it and
- * MUST NOT return one tenant's bytes for another's key.
- */
-export interface SnapshotStore {
-  load(tenantId: string, roomId: string): Promise<Uint8Array | null>;
-  save(tenantId: string, roomId: string, state: Uint8Array): Promise<void>;
-}
-
-/**
- * Transport-agnostic fan-out seam. The default is an in-memory loopback;
- * a Pusher / WebSocket adapter implements the same two methods and plugs in
- * via `createCollab({ transport })`. Updates are opaque Yjs update bytes.
- */
-export interface CollabTransport {
-  broadcast(tenantId: string, roomId: string, update: Uint8Array): void | Promise<void>;
-  /** Subscribe to remote updates for one tenant-scoped room; returns unsub. */
-  subscribe(tenantId: string, roomId: string, cb: (update: Uint8Array) => void): () => void;
-}
-
-export type UpdateListener = (update: Uint8Array, origin: unknown) => void;
-
-export interface CollabConfig {
-  store?: SnapshotStore;
-  transport?: CollabTransport;
-}
-
-export interface CollabRoom {
-  readonly tenantId: string;
-  readonly roomId: string;
-  readonly doc: Y.Doc;
-  applyUpdate(update: Uint8Array, origin?: unknown): void;
-  encodeState(): Uint8Array;
-  onUpdate(cb: UpdateListener): () => void;
-  snapshot(): Promise<void>;
-  destroy(): void;
-}
-
-// DoctorCheck + the {ok,durationMs} base come from the shared
-// @nebutra/capability-kit contract; collab only adds its specific probe map.
-export type { DoctorCheck };
-
-export interface DoctorReport extends DoctorReportBase {
-  readonly checks: {
-    readonly yjs: DoctorCheck;
-    readonly store: DoctorCheck;
-    readonly transport: DoctorCheck;
-  };
-}
-
-export interface CollabHub {
-  /** Returns/creates a tenant-scoped CRDT room. Hard-partitioned by tenant. */
-  room(tenantId: string, roomId: string): CollabRoom;
-  /** Like `room`, but first hydrates from the snapshot store if present. */
-  roomRestored(tenantId: string, roomId: string): Promise<CollabRoom>;
-  doctor(): Promise<DoctorReport>;
-  /** Destroy every live room and release resources. */
-  destroy(): void;
-}

package/tsconfig.json

@@ -1,12 +0,0 @@
-{
-  "extends": "../../../tsconfig.base.json",
-  "compilerOptions": {
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "target": "esnext",
-    "types": ["node"],
-    "incremental": false
-  },
-  "include": ["src", "examples"],
-  "exclude": ["node_modules", "dist"]
-}

package/tsup.config.ts

@@ -1,11 +0,0 @@
-import { defineConfig } from "tsup";
-
-export default defineConfig({
-  entry: ["src/index.ts", "src/store/memory.ts", "src/transport/loopback.ts"],
-  format: ["esm"],
-  dts: true,
-  sourcemap: true,
-  clean: true,
-  target: "es2022",
-  external: ["@nebutra/tenant-store"],
-});