@nebutra/collab 0.2.1 → 0.2.3

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"],
-});