@loro-dev/streams-crdt 0.1.0

package/README.md

@@ -0,0 +1,407 @@
+# `@loro-dev/streams-crdt`
+
+Transport layer for synchronizing CRDT state over
+[Loro Streams](https://loro.dev/docs/streams) (Durable Streams).
+
+## Core Concepts
+
+### Two-class model
+
+| Class | Responsibility |
+| --- | --- |
+| `StreamsCrdt` | Transport runtime bound to **one** stream URL. Handles auth, reconnect, bootstrap, SSE/long-poll, binary framing, and remote cursor persistence. |
+| `CrdtAdapter` | Binding for **one** local CRDT instance. Handles snapshot export/import, version tracking, local update export, and remote update application. |
+
+### Operations
+
+| Method | Purpose |
+| --- | --- |
+| `createStream()` | Creates the stream on the server. Returns `{ created: true }` on first call, `{ created: false }` if it already exists. |
+| `deleteStream()` | Deletes the stream. Closes any active `join()` first. |
+| `sync()` | One-shot bootstrap/catch-up cycle. Syncs remote state into local CRDT and pushes any local changes to the server. Does **not** enter live mode. |
+| `join()` | Initial sync **plus** live subscription. Internally performs the same sync as `sync()`, then enters a persistent SSE/long-poll read loop and starts forwarding local writes. No need to call `sync()` before `join()`. |
+| `close()` | Closes any active join and releases resources. |
+
+> **`join()` includes an initial sync.** You do not need to call `sync()` before
+> `join()`. When `join()` resolves, the local CRDT is already caught up with
+> the server and the live subscription is active.
+
+### Error handling — `Result`, not exceptions
+
+All transport operations return a `Result<T, TransportError>` instead of
+throwing. Callers **must** check `.ok` before accessing the value:
+
+```ts
+const result = await transport.join();
+if (!result.ok) {
+  // result.error is a TransportError with a discriminated `code` field.
+  switch (result.error.code) {
+    case "stream_not_found":
+      // The stream doesn't exist yet — create it first.
+      break;
+    case "auth_failed":
+      // Token expired or unauthorized.
+      break;
+    case "protocol_error":
+    case "internal_error":
+      // Non-retryable: bad server response or local runtime/adapter failure.
+      break;
+    case "network_error":
+    case "timeout":
+      // Transient — safe to retry.
+      break;
+    default:
+      console.error("transport error:", result.error);
+  }
+  return;
+}
+
+const sub = result.value; // TransportSubscription
+```
+
+Every error carries a `retryable` flag so callers can decide whether to retry
+without hard-coding error codes:
+
+```ts
+if (!result.ok && result.error.retryable) {
+  // safe to retry after a delay
+}
+```
+
+> **Why `Result` instead of `throw`?** Transport failures (network errors,
+> auth expiry, missing streams) are expected at runtime, not exceptional.
+> Wrapping them in `Result` makes the error path explicit in the type system
+> so callers cannot accidentally ignore failures with a missing `try/catch`.
+
+## Quick Start (Loro)
+
+```ts
+import { LoroDoc } from "loro-crdt";
+import {
+  createStreamUrl,
+  createLoroDocAdapter,
+  StreamsCrdt,
+} from "@loro-dev/streams-crdt/loro";
+
+const doc = new LoroDoc();
+const transport = new StreamsCrdt({
+  streamUrl: createStreamUrl({
+    bucketId: "my-bucket",
+    streamId: "doc-1",
+  }),
+  auth: async () => "<gateway-jwt>",
+  adapter: createLoroDocAdapter(doc),
+  // Enable automatic snapshot upload so new readers bootstrap faster.
+  snapshotUpload: { canUpload: async () => true },
+});
+
+// Create the stream (idempotent).
+const created = await transport.createStream();
+if (!created.ok) throw created.error;
+
+// Join enters live collaborative editing mode.
+// This performs an initial sync automatically before entering live mode.
+const joined = await transport.join({
+  onStatusChange(status) {
+    console.log("room status:", status);
+  },
+});
+if (!joined.ok) throw joined.error;
+
+const sub = joined.value;
+
+// The doc is now syncing in real time.
+// Call sub.unsubscribe() or transport.close() to leave.
+```
+
+`createLoroDocAdapter(doc)` requires an attached `LoroDoc`. If the document was
+checked out or detached, call `checkoutToLatest()` or `attach()` before passing
+it to `StreamsCrdt`.
+
+## Quick Start (Flock)
+
+```ts
+import { Flock } from "@loro-dev/flock-wasm";
+import {
+  createStreamUrl,
+  createFlockAdapter,
+  StreamsCrdt,
+} from "@loro-dev/streams-crdt/flock";
+
+const flock = new Flock();
+const transport = new StreamsCrdt({
+  streamUrl: createStreamUrl({
+    bucketId: "my-bucket",
+    streamId: "room-1",
+  }),
+  auth: async () => "<gateway-jwt>",
+  adapter: createFlockAdapter(flock),
+});
+
+await transport.createStream();
+const joined = await transport.join();
+if (!joined.ok) throw joined.error;
+
+const sub = joined.value;
+```
+
+## When to Use `sync()` vs `join()`
+
+Use **`sync()`** when you need a one-shot catch-up without entering live mode:
+
+```ts
+// Offline-first: catch up on app start, then work offline.
+const synced = await transport.sync();
+if (!synced.ok) throw synced.error;
+// synced.value.cursor contains the replay progress after sync.
+```
+
+Use **`join()`** for real-time collaboration. It does everything `sync()` does
+and then keeps the connection alive for continuous bidirectional sync:
+
+```ts
+const joined = await transport.join();
+```
+
+## Delete Stream
+
+```ts
+const deleted = await transport.deleteStream();
+if (!deleted.ok) throw deleted.error;
+
+console.log(deleted.value.deleted); // true when deleted now, false when already missing
+```
+
+`deleteStream()` closes any active join first. When the configured
+`remoteCursorStore` implements `delete(streamUrl)` (the built-in stores do),
+the transport also clears the stored replay cursor for that stream.
+
+## Auth
+
+`auth` may be:
+
+- a static string
+- a sync callback returning a string
+- an async callback returning a string
+
+This is intended for refresh-token flows. `StreamsCrdt` asks for a token before
+requests; token refresh itself remains caller-owned.
+
+## Remote Cursor Store
+
+The `RemoteCursorStore` persists **replay progress metadata only** — it does
+**not** store any CRDT update data. A remote cursor contains:
+
+- `nextOffset` — where the transport should resume reading from
+- `serverLowerBoundVersion` — the CRDT version that the server data represents
+- `streamUrl` — identity of the stream
+
+### Important: cursor-only persistence is unsafe
+
+If `RemoteCursorStore.load()` returns a saved cursor, the transport resumes
+from `nextOffset` and assumes the caller has already restored the matching
+local CRDT state represented by `serverLowerBoundVersion`.
+
+**If the local CRDT was reset to empty but the cursor was persisted**, the
+transport will do delta-only catch-up from `nextOffset` — applying those deltas
+against an empty document will fail or produce an invalid state.
+
+### Rule of thumb
+
+| Local CRDT state | Cursor store | Safe? |
+| --- | --- | --- |
+| Not persisted (ephemeral) | `InMemoryRemoteCursorStore` (default) | Yes |
+| Persisted (IndexedDB, SQLite, etc.) | `IndexedDbRemoteCursorStore` + `beforeRemoteCursorSave` hook | Yes |
+| Not persisted | `IndexedDbRemoteCursorStore` | **No — data loss risk** |
+
+If you do not persist the local CRDT payload across reloads, keep the remote
+cursor ephemeral too. The default `InMemoryRemoteCursorStore` is the safe
+choice.
+
+## Hooking Local Durability
+
+Use `beforeRemoteCursorSave` to couple local payload persistence with remote
+cursor advancement. The transport advances the cursor only after:
+
+1. Remote data was applied locally
+2. The durability hook succeeded
+3. The cursor store write succeeded
+
+```ts
+const transport = new StreamsCrdt({
+  streamUrl: createStreamUrl({
+    bucketId: "my-bucket",
+    streamId: "doc-1",
+  }),
+  adapter: createLoroDocAdapter(doc),
+  beforeRemoteCursorSave: async ({ cursor, source }) => {
+    // Persist local CRDT state before cursor advances.
+    // `source` is "local" | "remote" | "bootstrap".
+    await persistLocalPayload(doc);
+    console.log(source, cursor.nextOffset);
+  },
+});
+```
+
+`persistLocalPayload(doc)` must make the local durable state correspond to the
+cursor that is about to be stored. On the next app start, restore that local
+state before calling `sync()` or `join()`.
+
+## Persistent Cursor Example
+
+Only use a persisted `RemoteCursorStore` such as `IndexedDbRemoteCursorStore`
+when you also persist **and restore** the local CRDT state for the same stream.
+
+```ts
+import { LoroDoc } from "loro-crdt";
+import {
+  createStreamUrl,
+  createLoroDocAdapter,
+  IndexedDbRemoteCursorStore,
+  StreamsCrdt,
+} from "@loro-dev/streams-crdt/loro";
+
+// Step 1: restore local CRDT state first.
+const doc = (await restorePersistedDoc("doc-1")) ?? new LoroDoc();
+
+const transport = new StreamsCrdt({
+  streamUrl: createStreamUrl({
+    bucketId: "my-bucket",
+    streamId: "doc-1",
+  }),
+  auth: async () => "<gateway-jwt>",
+  adapter: createLoroDocAdapter(doc),
+  // Step 2: use a persistent cursor store.
+  remoteCursorStore: new IndexedDbRemoteCursorStore({
+    dbName: "my-app-ds-cursors",
+  }),
+  // Step 3: persist local state before cursor advances.
+  beforeRemoteCursorSave: async () => {
+    await persistLocalPayload("doc-1", doc);
+  },
+});
+
+// join() handles initial sync + live mode.
+const joined = await transport.join();
+```
+
+The required ordering is:
+
+1. Restore the local CRDT state first
+2. Let the transport apply remote updates
+3. Persist the updated local CRDT state (via `beforeRemoteCursorSave`)
+4. Only then persist the remote cursor
+
+If you cannot provide steps 1 and 3, do not use a persisted remote cursor
+store.
+
+## Automatic Snapshot Upload
+
+The transport can upload snapshots automatically during `join()` when callers
+opt in with `snapshotUpload`. **This feature is disabled by default** — if you
+do not pass `snapshotUpload`, no snapshots will ever be uploaded.
+
+```ts
+const transport = new StreamsCrdt({
+  streamUrl,
+  adapter: createLoroDocAdapter(doc),
+  // Enable automatic snapshot upload:
+  snapshotUpload: {
+    canUpload: async () => true,
+    // debounceMs: 10_000,                 // default: 10 seconds
+    // minBytesSinceRemoteSnapshot: 102400, // default: 100 KB
+  },
+});
+```
+
+### Configuration
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `canUpload` | *(required)* | Authorization gate called before each upload attempt. Return `false` to skip. |
+| `debounceMs` | `10_000` (10 s) | Debounce window after the last local write before attempting upload. |
+| `minBytesSinceRemoteSnapshot` | `102400` (100 KB) | Minimum byte delta between the last remote snapshot offset and the current stream tail. Upload is skipped when the delta is smaller. |
+
+### Behavior
+
+- Automatic snapshot upload is considered only during `join()`, never `sync()`
+- **The feature is opt-in**: callers must pass `snapshotUpload` with at least
+  `canUpload` to enable it
+- Successful local appends while `join()` is active refresh a debounce window
+  (default 10 s) for a possible snapshot upload check
+- If a remote apply advances the inferred remote version during that window, the
+  transport treats that as another writer becoming active and skips that
+  snapshot attempt
+- At debounce expiry, the transport may enqueue a best-effort
+  `maybeUploadSnapshot` task onto the same serialized operation queue used for
+  local append and remote apply
+- When that task executes, it fetches the latest remote snapshot offset, uses
+  the latest confirmed local `cursor.nextOffset` as the candidate
+  `snapshot_offset`, and uploads only if
+  `current_tail_offset - remote_snapshot_offset` exceeds the configured byte
+  threshold
+
+## Entry Points
+
+| Import path | What it adds |
+| --- | --- |
+| `@loro-dev/streams-crdt` | Transport core, cursor stores, ID helpers, all shared types |
+| `@loro-dev/streams-crdt/loro` | Everything above + `createLoroDocAdapter(doc)` |
+| `@loro-dev/streams-crdt/flock` | Everything above + `createFlockAdapter(flock)` |
+
+## Public API Reference
+
+### Root Entry Point
+
+- `StreamsCrdt` — transport runtime class
+- `StreamsCrdtOptions` — constructor options
+- `CrdtAdapter` — adapter contract interface
+- `CrdtUpdateBatch` — local update batch type
+- `Result` — Rust-style `Ok | Err` result
+- `StreamsAuthProvider` — auth callback type
+- `TransportError` — discriminated error union
+- `TransportCreateStreamSuccess`, `TransportDeleteStreamSuccess`, `TransportSyncSuccess` — result payloads
+- `TransportJoinParams` — `join()` options
+- `TransportSubscription` — active live subscription handle
+- `TransportRoomStatus` — `"joined" | "reconnecting" | "disconnected" | "error"`
+- `SnapshotUploadOptions` — snapshot upload configuration
+- `RemoteCursor` — replay progress metadata
+- `RemoteCursorStore` — abstract cursor storage interface
+- `RemoteCursorSaveSource` — `"local" | "remote" | "bootstrap"`
+- `BeforeRemoteCursorSaveContext`, `BeforeRemoteCursorSaveHook` — durability hook types
+- `InMemoryRemoteCursorStore` — ephemeral cursor store (default, always safe)
+- `IndexedDbRemoteCursorStore` — persistent cursor store (requires local CRDT persistence)
+- `IndexedDbRemoteCursorStoreOptions` — IndexedDB store config
+- `createInitialRemoteCursor(...)` — seed a cursor store
+- `createStreamUrl(...)` — build stream URL from bucket/stream IDs
+- `isValidBucketId(...)`, `isValidRillId(...)` — ID validation helpers
+
+### Loro Entry Point
+
+`@loro-dev/streams-crdt/loro` re-exports everything from the root plus:
+
+- `createLoroDocAdapter(doc)` — creates a `CrdtAdapter` for one `LoroDoc`
+
+### Flock Entry Point
+
+`@loro-dev/streams-crdt/flock` re-exports everything from the root plus:
+
+- `createFlockAdapter(flock)` — creates a `CrdtAdapter` for one `Flock` replica
+- `FlockVersionVector` — Flock-specific version vector type
+
+## Notes
+
+- `createStreamIfMissing` defaults to `false` and only affects the initial sync/join bootstrap
+- `deleteStream()` returns `{ deleted: false }` when the target stream is already missing
+- `sync()` and `join()` return `Result` objects instead of implicitly creating missing streams
+- `join()` resolves only after the initial replay has succeeded; without a stored remote cursor it prefers bootstrap-live SSE and falls back sticky to long-poll
+- One transport instance maps to one DS stream
+- One adapter instance maps to one local CRDT instance
+- Built-in remote cursor stores implement `delete(streamUrl)` so `deleteStream()` can reset replay state cleanly
+
+## Repository-only Scripts
+
+The published package only includes built runtime artifacts under `dist/`.
+For repository verification against the hosted backend, run:
+
+- `pnpm --dir packages/streams-crdt run test:e2e:streams-api`

package/dist/flock.d.ts

@@ -0,0 +1,36 @@
+import { C as IndexedDbRemoteCursorStore, D as RemoteCursorStore, E as RemoteCursorSaveSource, O as createInitialRemoteCursor, S as InMemoryRemoteCursorStore, T as RemoteCursor, _ as TransportRoomStatus, a as CrdtAdapter, b as BeforeRemoteCursorSaveContext, c as JsonValue, d as StreamsAuthProvider, f as StreamsCrdtOptions, g as TransportJoinParams, h as TransportError, i as StreamsCrdt, l as Result, m as TransportDeleteStreamSuccess, n as isValidBucketId, o as CrdtUpdateBatch, p as TransportCreateStreamSuccess, r as isValidRillId, s as JsonObject, t as createStreamUrl, u as SnapshotUploadOptions, v as TransportSubscription, w as IndexedDbRemoteCursorStoreOptions, x as BeforeRemoteCursorSaveHook, y as TransportSyncSuccess } from "./stream-id-1f2mhtmk.js";
+
+//#region src/flock.d.ts
+type FlockVersionEntry = {
+  logicalCounter: number;
+  physicalTime?: number;
+};
+/**
+ * Flock version vector shape used by the built-in Flock adapter.
+ */
+type FlockVersionVector = Record<string, FlockVersionEntry>;
+type FlockExportBundle = {
+  readonly version?: number;
+  readonly entries: Record<string, unknown>;
+};
+type FlockLike = {
+  exportJson(options?: {
+    from?: FlockVersionVector;
+    peerId?: string;
+  }): FlockExportBundle;
+  importJson(bundle: FlockExportBundle): unknown;
+  merge?(replica: unknown): unknown;
+  peerId?(): string;
+  version(): unknown;
+  exportFile?(): Uint8Array;
+  subscribe?(listener: (batch: {
+    source?: string;
+  }) => void): () => void;
+};
+/**
+ * Creates a `CrdtAdapter` for one Flock replica.
+ */
+declare function createFlockAdapter(flock: FlockLike): CrdtAdapter<JsonObject>;
+//#endregion
+export { BeforeRemoteCursorSaveContext, BeforeRemoteCursorSaveHook, CrdtAdapter, CrdtUpdateBatch, FlockVersionVector, InMemoryRemoteCursorStore, IndexedDbRemoteCursorStore, IndexedDbRemoteCursorStoreOptions, JsonObject, JsonValue, RemoteCursor, RemoteCursorSaveSource, RemoteCursorStore, Result, SnapshotUploadOptions, StreamsAuthProvider, StreamsCrdt, StreamsCrdtOptions, TransportCreateStreamSuccess, TransportDeleteStreamSuccess, TransportError, TransportJoinParams, TransportRoomStatus, TransportSubscription, TransportSyncSuccess, createFlockAdapter, createInitialRemoteCursor, createStreamUrl, isValidBucketId, isValidRillId };
+//# sourceMappingURL=flock.d.ts.map

package/dist/flock.js

@@ -0,0 +1,146 @@
+import { a as InMemoryRemoteCursorStore, i as StreamsCrdt, n as isValidBucketId, o as IndexedDbRemoteCursorStore, r as isValidRillId, s as createInitialRemoteCursor, t as createStreamUrl } from "./stream-id-CIhmveJD.js";
+//#region src/flock.ts
+function toVersionVector(version) {
+	const out = {};
+	for (const [peer, raw] of Object.entries(version)) {
+		if (typeof raw !== "object" || raw == null || Array.isArray(raw)) continue;
+		const logicalCounter = typeof raw.logicalCounter === "number" ? raw.logicalCounter : void 0;
+		if (logicalCounter == null || !Number.isFinite(logicalCounter)) continue;
+		out[peer] = typeof raw.physicalTime === "number" && Number.isFinite(raw.physicalTime) ? {
+			logicalCounter,
+			physicalTime: raw.physicalTime
+		} : { logicalCounter };
+	}
+	return out;
+}
+function fromVersionVector(version) {
+	const out = {};
+	for (const [peer, entry] of Object.entries(version)) out[peer] = entry.physicalTime === void 0 ? { logicalCounter: entry.logicalCounter } : {
+		logicalCounter: entry.logicalCounter,
+		physicalTime: entry.physicalTime
+	};
+	return out;
+}
+function mergeVersions(base, incoming) {
+	const merged = { ...base };
+	for (const [peer, entry] of Object.entries(incoming)) {
+		const current = merged[peer];
+		if (current == null || entry.logicalCounter > current.logicalCounter) {
+			merged[peer] = { ...entry };
+			continue;
+		}
+		if (entry.logicalCounter < current.logicalCounter) continue;
+		const physicalTime = Math.max(current.physicalTime ?? Number.NEGATIVE_INFINITY, entry.physicalTime ?? Number.NEGATIVE_INFINITY);
+		merged[peer] = physicalTime === Number.NEGATIVE_INFINITY ? { logicalCounter: current.logicalCounter } : {
+			logicalCounter: current.logicalCounter,
+			physicalTime
+		};
+	}
+	return merged;
+}
+function extractVersionFromBundle(bundle) {
+	const out = {};
+	for (const raw of Object.values(bundle.entries)) {
+		if (typeof raw !== "object" || raw == null || Array.isArray(raw)) continue;
+		const entry = raw;
+		if (typeof entry.peerId !== "string") continue;
+		const logicalCounter = typeof entry.logicalCounter === "number" ? entry.logicalCounter : typeof entry.counter === "number" ? entry.counter : void 0;
+		if (logicalCounter == null || !Number.isFinite(logicalCounter)) continue;
+		out[entry.peerId] = typeof entry.physicalTime === "number" && Number.isFinite(entry.physicalTime) ? {
+			logicalCounter,
+			physicalTime: entry.physicalTime
+		} : { logicalCounter };
+	}
+	return out;
+}
+function hasEntries(bundle) {
+	return Object.keys(bundle.entries).length > 0;
+}
+function tryMergeSnapshotFromFile(flock, snapshot) {
+	if (typeof flock.merge !== "function") return null;
+	const ctor = flock.constructor;
+	if (ctor == null || typeof ctor.fromFile !== "function") return null;
+	try {
+		const peerId = typeof flock.peerId === "function" ? flock.peerId() : void 0;
+		const replica = ctor.fromFile(snapshot, peerId);
+		flock.merge(replica);
+		return toVersionVector(flock.version() ?? {});
+	} catch {
+		return null;
+	}
+}
+/**
+* Creates a `CrdtAdapter` for one Flock replica.
+*/
+function createFlockAdapter(flock) {
+	let lastExportedVersion = {};
+	let localExportQueue = Promise.resolve();
+	const recordExportFrontier = (version) => {
+		lastExportedVersion = mergeVersions(lastExportedVersion, version);
+	};
+	return {
+		emptyVersion: () => ({}),
+		mergeVersions: (base, incoming) => fromVersionVector(mergeVersions(toVersionVector(base), toVersionVector(incoming))),
+		exportSnapshot: () => {
+			if (typeof flock.exportFile === "function") return flock.exportFile();
+			return new TextEncoder().encode(JSON.stringify({
+				version: 0,
+				entries: {}
+			}));
+		},
+		applySnapshot: (snapshot) => {
+			if (snapshot.byteLength === 0) return {};
+			const mergedVersion = tryMergeSnapshotFromFile(flock, snapshot);
+			if (mergedVersion != null) return fromVersionVector(mergedVersion);
+			const bundle = JSON.parse(new TextDecoder().decode(snapshot));
+			if (hasEntries(bundle)) flock.importJson(bundle);
+			return fromVersionVector(extractVersionFromBundle(bundle));
+		},
+		exportUpdates: (fromVersion) => {
+			const from = toVersionVector(fromVersion);
+			const bundle = flock.exportJson({ from });
+			recordExportFrontier(from);
+			if (!hasEntries(bundle)) return;
+			const exportedVersion = extractVersionFromBundle(bundle);
+			recordExportFrontier(exportedVersion);
+			return {
+				updates: [new TextEncoder().encode(JSON.stringify(bundle))],
+				version: fromVersionVector(exportedVersion)
+			};
+		},
+		applyRemoteUpdates: (updates, remoterVersion) => {
+			let merged = toVersionVector(remoterVersion);
+			for (const update of updates) {
+				const bundle = JSON.parse(new TextDecoder().decode(update));
+				if (!hasEntries(bundle)) continue;
+				flock.importJson(bundle);
+				merged = mergeVersions(merged, extractVersionFromBundle(bundle));
+			}
+			return fromVersionVector(merged);
+		},
+		subscribeLocalUpdates: (listener) => {
+			if (typeof flock.subscribe !== "function") return () => void 0;
+			return flock.subscribe((batch) => {
+				if (batch.source !== "local") return;
+				const drain = () => {
+					const peerId = typeof flock.peerId === "function" ? flock.peerId() : void 0;
+					const batchPayload = flock.exportJson({
+						from: lastExportedVersion,
+						peerId
+					});
+					if (!hasEntries(batchPayload)) return;
+					recordExportFrontier(toVersionVector(fromVersionVector(flock.version() ?? {})));
+					listener({
+						updates: [new TextEncoder().encode(JSON.stringify(batchPayload))],
+						version: fromVersionVector(extractVersionFromBundle(batchPayload))
+					});
+				};
+				localExportQueue = localExportQueue.then(drain).catch(() => {});
+			});
+		}
+	};
+}
+//#endregion
+export { InMemoryRemoteCursorStore, IndexedDbRemoteCursorStore, StreamsCrdt, createFlockAdapter, createInitialRemoteCursor, createStreamUrl, isValidBucketId, isValidRillId };
+
+//# sourceMappingURL=flock.js.map

package/dist/flock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flock.js","names":[],"sources":["../src/flock.ts"],"sourcesContent":["import type { JsonObject, CrdtAdapter } from \"./types\";\n\nexport { StreamsCrdt } from \"./transport\";\nexport * from \"./shared\";\n\ntype FlockVersionEntry = {\n  logicalCounter: number;\n  physicalTime?: number;\n};\n\n/**\n * Flock version vector shape used by the built-in Flock adapter.\n */\nexport type FlockVersionVector = Record<string, FlockVersionEntry>;\n\ntype FlockExportBundle = {\n  readonly version?: number;\n  readonly entries: Record<string, unknown>;\n};\n\ntype FlockLike = {\n  exportJson(options?: {\n    from?: FlockVersionVector;\n    peerId?: string;\n  }): FlockExportBundle;\n  importJson(bundle: FlockExportBundle): unknown;\n  merge?(replica: unknown): unknown;\n  peerId?(): string;\n  version(): unknown;\n  exportFile?(): Uint8Array;\n  subscribe?(listener: (batch: { source?: string }) => void): () => void;\n};\n\nfunction toVersionVector(version: JsonObject): FlockVersionVector {\n  const out: FlockVersionVector = {};\n  for (const [peer, raw] of Object.entries(version)) {\n    if (typeof raw !== \"object\" || raw == null || Array.isArray(raw)) {\n      continue;\n    }\n    const logicalCounter =\n      typeof raw.logicalCounter === \"number\" ? raw.logicalCounter : undefined;\n    if (logicalCounter == null || !Number.isFinite(logicalCounter)) {\n      continue;\n    }\n    out[peer] =\n      typeof raw.physicalTime === \"number\" && Number.isFinite(raw.physicalTime)\n        ? { logicalCounter, physicalTime: raw.physicalTime }\n        : { logicalCounter };\n  }\n  return out;\n}\n\nfunction fromVersionVector(version: FlockVersionVector): JsonObject {\n  const out: Record<string, JsonObject> = {};\n  for (const [peer, entry] of Object.entries(version)) {\n    out[peer] =\n      entry.physicalTime === undefined\n        ? { logicalCounter: entry.logicalCounter }\n        : {\n            logicalCounter: entry.logicalCounter,\n            physicalTime: entry.physicalTime,\n          };\n  }\n  return out;\n}\n\nfunction mergeVersions(\n  base: FlockVersionVector,\n  incoming: FlockVersionVector,\n): FlockVersionVector {\n  const merged: FlockVersionVector = { ...base };\n  for (const [peer, entry] of Object.entries(incoming)) {\n    const current = merged[peer];\n    if (current == null || entry.logicalCounter > current.logicalCounter) {\n      merged[peer] = { ...entry };\n      continue;\n    }\n    if (entry.logicalCounter < current.logicalCounter) {\n      continue;\n    }\n    const physicalTime = Math.max(\n      current.physicalTime ?? Number.NEGATIVE_INFINITY,\n      entry.physicalTime ?? Number.NEGATIVE_INFINITY,\n    );\n    merged[peer] =\n      physicalTime === Number.NEGATIVE_INFINITY\n        ? { logicalCounter: current.logicalCounter }\n        : { logicalCounter: current.logicalCounter, physicalTime };\n  }\n  return merged;\n}\n\nfunction extractVersionFromBundle(\n  bundle: FlockExportBundle,\n): FlockVersionVector {\n  const out: FlockVersionVector = {};\n  for (const raw of Object.values(bundle.entries)) {\n    if (typeof raw !== \"object\" || raw == null || Array.isArray(raw)) {\n      continue;\n    }\n    const entry = raw as {\n      peerId?: unknown;\n      logicalCounter?: unknown;\n      counter?: unknown;\n      physicalTime?: unknown;\n    };\n    if (typeof entry.peerId !== \"string\") {\n      continue;\n    }\n    const logicalCounter =\n      typeof entry.logicalCounter === \"number\"\n        ? entry.logicalCounter\n        : typeof entry.counter === \"number\"\n          ? entry.counter\n          : undefined;\n    if (logicalCounter == null || !Number.isFinite(logicalCounter)) {\n      continue;\n    }\n    out[entry.peerId] =\n      typeof entry.physicalTime === \"number\" &&\n      Number.isFinite(entry.physicalTime)\n        ? { logicalCounter, physicalTime: entry.physicalTime }\n        : { logicalCounter };\n  }\n  return out;\n}\n\nfunction hasEntries(bundle: FlockExportBundle): boolean {\n  return Object.keys(bundle.entries).length > 0;\n}\n\nfunction tryMergeSnapshotFromFile(\n  flock: FlockLike,\n  snapshot: Uint8Array,\n): FlockVersionVector | null {\n  if (typeof flock.merge !== \"function\") {\n    return null;\n  }\n  const ctor = (\n    flock as unknown as {\n      readonly constructor?: {\n        fromFile?: (bytes: Uint8Array, peerId?: string) => unknown;\n      };\n    }\n  ).constructor;\n  if (ctor == null || typeof ctor.fromFile !== \"function\") {\n    return null;\n  }\n  try {\n    const peerId =\n      typeof flock.peerId === \"function\" ? flock.peerId() : undefined;\n    const replica = ctor.fromFile(snapshot, peerId);\n    flock.merge(replica);\n    return toVersionVector((flock.version() as JsonObject) ?? {});\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Creates a `CrdtAdapter` for one Flock replica.\n */\nexport function createFlockAdapter(flock: FlockLike): CrdtAdapter<JsonObject> {\n  let lastExportedVersion: FlockVersionVector = {};\n  let localExportQueue = Promise.resolve();\n\n  const recordExportFrontier = (version: FlockVersionVector): void => {\n    lastExportedVersion = mergeVersions(lastExportedVersion, version);\n  };\n\n  return {\n    emptyVersion: () => ({}),\n    mergeVersions: (base, incoming) =>\n      fromVersionVector(\n        mergeVersions(toVersionVector(base), toVersionVector(incoming)),\n      ),\n    exportSnapshot: () => {\n      if (typeof flock.exportFile === \"function\") {\n        return flock.exportFile();\n      }\n      return new TextEncoder().encode(\n        JSON.stringify({ version: 0, entries: {} }),\n      );\n    },\n    applySnapshot: (snapshot) => {\n      if (snapshot.byteLength === 0) {\n        return {};\n      }\n      const mergedVersion = tryMergeSnapshotFromFile(flock, snapshot);\n      if (mergedVersion != null) {\n        return fromVersionVector(mergedVersion);\n      }\n      const bundle = JSON.parse(\n        new TextDecoder().decode(snapshot),\n      ) as FlockExportBundle;\n      if (hasEntries(bundle)) {\n        flock.importJson(bundle);\n      }\n      return fromVersionVector(extractVersionFromBundle(bundle));\n    },\n    exportUpdates: (fromVersion) => {\n      const from = toVersionVector(fromVersion);\n      const bundle = flock.exportJson({ from });\n      recordExportFrontier(from);\n      if (!hasEntries(bundle)) {\n        return undefined;\n      }\n      const exportedVersion = extractVersionFromBundle(bundle);\n      recordExportFrontier(exportedVersion);\n      return {\n        updates: [new TextEncoder().encode(JSON.stringify(bundle))],\n        version: fromVersionVector(exportedVersion),\n      };\n    },\n    applyRemoteUpdates: (updates, remoterVersion) => {\n      let merged = toVersionVector(remoterVersion);\n      for (const update of updates) {\n        const bundle = JSON.parse(\n          new TextDecoder().decode(update),\n        ) as FlockExportBundle;\n        if (!hasEntries(bundle)) {\n          continue;\n        }\n        flock.importJson(bundle);\n        merged = mergeVersions(merged, extractVersionFromBundle(bundle));\n      }\n      return fromVersionVector(merged);\n    },\n    subscribeLocalUpdates: (listener) => {\n      if (typeof flock.subscribe !== \"function\") {\n        return () => undefined;\n      }\n      const unsubscribe = flock.subscribe((batch) => {\n        if (batch.source !== \"local\") {\n          return;\n        }\n        const drain = () => {\n          const peerId =\n            typeof flock.peerId === \"function\" ? flock.peerId() : undefined;\n          const batchPayload = flock.exportJson({\n            from: lastExportedVersion,\n            peerId,\n          });\n          if (!hasEntries(batchPayload)) {\n            return;\n          }\n          const currentVersion = toVersionVector(\n            fromVersionVector((flock.version() as FlockVersionVector) ?? {}),\n          );\n          recordExportFrontier(currentVersion);\n          listener({\n            updates: [new TextEncoder().encode(JSON.stringify(batchPayload))],\n            version: fromVersionVector(extractVersionFromBundle(batchPayload)),\n          });\n        };\n\n        localExportQueue = localExportQueue.then(drain).catch(() => {\n          /* swallow to keep queue alive */\n        });\n      });\n      return unsubscribe;\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import { C as IndexedDbRemoteCursorStore, D as RemoteCursorStore, E as RemoteCursorSaveSource, O as createInitialRemoteCursor, S as InMemoryRemoteCursorStore, T as RemoteCursor, _ as TransportRoomStatus, a as CrdtAdapter, b as BeforeRemoteCursorSaveContext, c as JsonValue, d as StreamsAuthProvider, f as StreamsCrdtOptions, g as TransportJoinParams, h as TransportError, i as StreamsCrdt, l as Result, m as TransportDeleteStreamSuccess, n as isValidBucketId, o as CrdtUpdateBatch, p as TransportCreateStreamSuccess, r as isValidRillId, s as JsonObject, t as createStreamUrl, u as SnapshotUploadOptions, v as TransportSubscription, w as IndexedDbRemoteCursorStoreOptions, x as BeforeRemoteCursorSaveHook, y as TransportSyncSuccess } from "./stream-id-1f2mhtmk.js";
+export { BeforeRemoteCursorSaveContext, BeforeRemoteCursorSaveHook, CrdtAdapter, CrdtUpdateBatch, InMemoryRemoteCursorStore, IndexedDbRemoteCursorStore, IndexedDbRemoteCursorStoreOptions, JsonObject, JsonValue, RemoteCursor, RemoteCursorSaveSource, RemoteCursorStore, Result, SnapshotUploadOptions, StreamsAuthProvider, StreamsCrdt, StreamsCrdtOptions, TransportCreateStreamSuccess, TransportDeleteStreamSuccess, TransportError, TransportJoinParams, TransportRoomStatus, TransportSubscription, TransportSyncSuccess, createInitialRemoteCursor, createStreamUrl, isValidBucketId, isValidRillId };

package/dist/index.js

@@ -0,0 +1,2 @@
+import { a as InMemoryRemoteCursorStore, i as StreamsCrdt, n as isValidBucketId, o as IndexedDbRemoteCursorStore, r as isValidRillId, s as createInitialRemoteCursor, t as createStreamUrl } from "./stream-id-CIhmveJD.js";
+export { InMemoryRemoteCursorStore, IndexedDbRemoteCursorStore, StreamsCrdt, createInitialRemoteCursor, createStreamUrl, isValidBucketId, isValidRillId };

package/dist/loro.d.ts

@@ -0,0 +1,22 @@
+import { C as IndexedDbRemoteCursorStore, D as RemoteCursorStore, E as RemoteCursorSaveSource, O as createInitialRemoteCursor, S as InMemoryRemoteCursorStore, T as RemoteCursor, _ as TransportRoomStatus, a as CrdtAdapter, b as BeforeRemoteCursorSaveContext, c as JsonValue, d as StreamsAuthProvider, f as StreamsCrdtOptions, g as TransportJoinParams, h as TransportError, i as StreamsCrdt, l as Result, m as TransportDeleteStreamSuccess, n as isValidBucketId, o as CrdtUpdateBatch, p as TransportCreateStreamSuccess, r as isValidRillId, s as JsonObject, t as createStreamUrl, u as SnapshotUploadOptions, v as TransportSubscription, w as IndexedDbRemoteCursorStoreOptions, x as BeforeRemoteCursorSaveHook, y as TransportSyncSuccess } from "./stream-id-1f2mhtmk.js";
+import { LoroDoc } from "loro-crdt";
+
+//#region src/loro.d.ts
+/**
+ * Creates a `CrdtAdapter` for one `LoroDoc`.
+ *
+ * The `LoroDoc` must be attached (not detached or checked out to a historical
+ * version). If the document is detached, call `doc.checkoutToLatest()` or
+ * `doc.attach()` before passing it here.
+ *
+ * @example
+ * ```ts
+ * const doc = new LoroDoc();
+ * const adapter = createLoroDocAdapter(doc);
+ * const transport = new StreamsCrdt({ streamUrl, adapter, auth });
+ * ```
+ */
+declare function createLoroDocAdapter(doc: LoroDoc): CrdtAdapter<JsonObject>;
+//#endregion
+export { BeforeRemoteCursorSaveContext, BeforeRemoteCursorSaveHook, CrdtAdapter, CrdtUpdateBatch, InMemoryRemoteCursorStore, IndexedDbRemoteCursorStore, IndexedDbRemoteCursorStoreOptions, JsonObject, JsonValue, RemoteCursor, RemoteCursorSaveSource, RemoteCursorStore, Result, SnapshotUploadOptions, StreamsAuthProvider, StreamsCrdt, StreamsCrdtOptions, TransportCreateStreamSuccess, TransportDeleteStreamSuccess, TransportError, TransportJoinParams, TransportRoomStatus, TransportSubscription, TransportSyncSuccess, createInitialRemoteCursor, createLoroDocAdapter, createStreamUrl, isValidBucketId, isValidRillId };
+//# sourceMappingURL=loro.d.ts.map