@fragno-dev/tanstack-db-adapter 0.0.0-stage → 0.0.0

package/LICENSE.md

@@ -0,0 +1,16 @@
+Copyright 2025 - present "ReJot Nederland B.V.", and individual contributors.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the “Software”), to deal in the Software without restriction,
+including without limitation the rights to use, copy, modify, merge, publish, distribute,
+sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
+NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES
+OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,208 @@
-# Temporary Holding Version
+# @fragno-dev/tanstack-db-adapter
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Ingest one Fragno database outbox into a durable, database-level set of eager TanStack DB
+collections.
+
+The adapter is intentionally one-way. It synchronizes server mutations into TanStack DB; client
+mutations, optimistic overlays, command submission, and on-demand subsets are out of scope.
+
+## Collection setup
+
+Create one coordinator for each physical Fragno outbox. Supply every schema represented by that
+outbox, register the tables used by the application, and preload once after registration closes:
+
+```ts
+import { createFragnoOutboxCoordinator } from "@fragno-dev/tanstack-db-adapter";
+
+const coordinator = await createFragnoOutboxCoordinator({
+  baseUrl: "/api/app",
+  fetch: globalThis.fetch,
+  schemas: [appSchema, workflowsSchema] as const,
+});
+
+const users = coordinator.collection(appSchema, "users");
+const posts = coordinator.collection(appSchema, "posts");
+const workflowInstances = coordinator.collection(workflowsSchema, "workflow_instance");
+
+await coordinator.preload();
+```
+
+Collections can only be registered while the coordinator is `"idle"`. `preload()` opens one shared
+stream, applies finite catch-up, and marks collections ready at its explicit `caught-up` frame. Live
+entries continue on the same response. Readiness does not wait for disk persistence; use
+`flushPersistence()` when you need all accepted writes to be durable.
+
+Clean up the database-level resource when it is no longer used:
+
+```ts
+await coordinator.cleanup();
+```
+
+## Authenticated and scoped Fetch
+
+Pass a Fetch implementation that forwards authentication or routes requests to the correct scoped
+backend:
+
+```ts
+const coordinator = await createFragnoOutboxCoordinator({
+  baseUrl: "/api/app-scoped/org/acme",
+  fetch: (input, init) =>
+    fetch(input, {
+      ...init,
+      headers: {
+        ...init?.headers,
+        authorization: `Bearer ${token}`,
+      },
+    }),
+  schemas: [appSchema] as const,
+});
+```
+
+The coordinator derives these routes from `baseUrl`:
+
+- `GET /_internal`
+- `GET /_internal/outbox/stream?protocol=1`
+
+The adapter never requests paginated `/outbox` data. Each stream starts strictly after the exact
+checkpoint. Reloads and rotations with no new commits receive no entry payloads. Catch-up is applied
+in bounded 50-entry batches. The response's `started` frame fixes the target; only `caught-up` makes
+collections ready. Heartbeats are transport liveness, not readiness.
+
+A final `rotate` frame requests immediate reconnection without backoff. Only classified network
+failures and EOF without `rotate` transition through `"retrying"` and `"replaying"` with exponential
+backoff. Request validation, HTTP errors (including 401/404 and 5xx), malformed protocol or
+payloads, and application/callback errors transition to `"failed"` and reject pending `preload()`.
+Only coordinator-owned disposal silently stops the stream loop; an unrelated `AbortError` is a
+failure.
+
+An interrupted partial catch-up batch is discarded and replayed; a planned rotation commits its
+partial batch without marking it ready. Collections already ready remain usable during reconnection.
+Custom Fetch implementations must preserve native Fetch network-error semantics; response parsing
+and collection application are deliberately outside the network-error classification boundary.
+
+To retrieve source metadata without opening browser persistence, use the same typed description
+request:
+
+```ts
+import { fetchFragnoOutboxDescription } from "@fragno-dev/tanstack-db-adapter";
+
+const description = await fetchFragnoOutboxDescription({
+  baseUrl: "/api/app",
+  fetch: authenticatedFetch,
+  signal: request.signal,
+});
+
+console.log(description.adapterIdentity, description.currentVersionstamp);
+```
+
+## Coordinator state
+
+The current lifecycle state is available directly and through the reactive internal collection:
+
+```ts
+coordinator.state;
+coordinator.internal.collection;
+coordinator.internal.getCheckpoint();
+```
+
+Lifecycle states are:
+
+```ts
+"opening" |
+  "idle" |
+  "registering" |
+  "catching-up" |
+  "live" |
+  "rotating" |
+  "retrying" |
+  "replaying" |
+  "failed" |
+  "disposed";
+```
+
+`coordinator.internal.collection` contains one `"coordinator"` row with the state, exact checkpoint,
+and serialized error. It can be consumed by ordinary TanStack live queries.
+
+## Checkpoints and persistence
+
+One physical outbox maps to one local persistence database and one shared exact checkpoint:
+
+```ts
+type FragnoOutboxCheckpoint = {
+  versionstamp: string;
+  uowId: string;
+};
+```
+
+Every resumed request sends `afterVersionstamp` and `afterUowId`. The server verifies that exact
+checkpoint before streaming, without downloading old entries. A missing or different UOW returns
+HTTP 409 and stops synchronization. Adapter identity alone is insufficient because it survives a
+backup restore, even when subsequent commits rewrite previously observed versionstamps. Collection
+checkpoints also reject a changed UOW during partial-commit recovery.
+
+During finite catch-up, each affected collection applies one bounded batch in one TanStack
+transaction. Row changes and that collection's applied-entry checkpoint commit together. The shared
+database checkpoint advances only after every affected collection accepts the page, and ordered
+persistence prevents it from overtaking an earlier failed table write.
+
+Separate TanStack collection commits remain independently observable. The coordinator provides
+ordered, replay-safe convergence, not atomic cross-collection UI visibility.
+
+Browser persistence is opened automatically with TanStack's `BrowserCollectionCoordinator`, so one
+tab owns the SQLite writer. The OPFS database identity includes:
+
+- normalized `baseUrl`;
+- backend adapter identity;
+- `FRAGNO_OUTBOX_LOCAL_SCHEMA_VERSION`.
+
+Changing the backend adapter identity or local schema version opens a fresh local database and
+replays the outbox. Increase `FRAGNO_OUTBOX_LOCAL_SCHEMA_VERSION` whenever a persisted materialized
+row format changes. Local schema version 2 rebuilds version-1 caches that may lack checkpoint UOW
+IDs.
+
+## Row update mode
+
+Fragno update entries contain patches, so collections default to partial-row handling:
+
+```ts
+const users = coordinator.collection(appSchema, "users", {
+  rowUpdateMode: "partial",
+});
+```
+
+Append-only tables that never receive Fragno update operations can use full-row handling:
+
+```ts
+const emissions = coordinator.collection(workflowsSchema, "workflow_step_emission", {
+  rowUpdateMode: "full",
+  skipMissingTruncateDeletes: true,
+});
+```
+
+Do not use `"full"` for tables that receive updates. Their outbox values are patches rather than
+complete rows.
+
+`skipMissingTruncateDeletes` scans persisted rows once per collection synchronization registration
+and skips catch-up truncate-derived deletes for keys that are already absent. The key index is
+maintained by both catch-up and live changes, and cleared by explicit truncation. Stream rotations
+and reconnects reuse it without rescanning; a replacement registration initializes a fresh index.
+Ordinary deletes and live truncate delivery remain unchanged. Skipped deletes still advance the
+collection checkpoint.
+
+## Catch-up progress
+
+Use `onCatchUpProgress` for a loading indicator:
+
+```ts
+const coordinator = await createFragnoOutboxCoordinator({
+  baseUrl: "/api/app",
+  fetch: globalThis.fetch,
+  schemas: [appSchema] as const,
+  onCatchUpProgress(progress) {
+    console.log(progress.completedPages, progress.totalPages, progress.percent);
+  },
+});
+```
+
+The percentage assumes contiguous database versions between the persisted checkpoint and the
+server's current versionstamp.

package/dist/checkpoint.d.ts

@@ -0,0 +1,9 @@
+//#region src/checkpoint.d.ts
+/** The last applied entry identity, including its UOW to detect restored outbox history. */
+type FragnoOutboxCheckpoint = {
+  versionstamp: string;
+  uowId: string;
+};
+//#endregion
+export { FragnoOutboxCheckpoint };
+//# sourceMappingURL=checkpoint.d.ts.map

package/dist/checkpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.d.ts","names":[],"sources":["../src/checkpoint.ts"],"mappings":";;KAIY;EACV;EACA"}

package/dist/checkpoint.js

@@ -0,0 +1,11 @@
+//#region src/checkpoint.ts
+const FRAGNO_OUTBOX_COLLECTION_CHECKPOINT_METADATA_KEY = "fragno.outbox.collection-checkpoint.v1";
+/** Skips collection changes already committed before a shared checkpoint could advance. */
+function shouldApplyOutboxCheckpoint(appliedCheckpoint, incomingCheckpoint) {
+	if (appliedCheckpoint?.versionstamp === incomingCheckpoint.versionstamp && appliedCheckpoint.uowId !== incomingCheckpoint.uowId) throw new Error(`Outbox checkpoint ${incomingCheckpoint.versionstamp} changed unit of work.`);
+	return !appliedCheckpoint || incomingCheckpoint.versionstamp > appliedCheckpoint.versionstamp;
+}
+//#endregion
+export { FRAGNO_OUTBOX_COLLECTION_CHECKPOINT_METADATA_KEY, shouldApplyOutboxCheckpoint };
+
+//# sourceMappingURL=checkpoint.js.map

package/dist/checkpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.js","names":[],"sources":["../src/checkpoint.ts"],"sourcesContent":["export const FRAGNO_OUTBOX_COLLECTION_CHECKPOINT_METADATA_KEY =\n  \"fragno.outbox.collection-checkpoint.v1\";\n\n/** The last applied entry identity, including its UOW to detect restored outbox history. */\nexport type FragnoOutboxCheckpoint = {\n  versionstamp: string;\n  uowId: string;\n};\n\nexport type FragnoOutboxSource = {\n  adapterIdentity: string;\n  namespace: string;\n  table: string;\n};\n\n/** Skips collection changes already committed before a shared checkpoint could advance. */\nexport function shouldApplyOutboxCheckpoint(\n  appliedCheckpoint: FragnoOutboxCheckpoint | undefined,\n  incomingCheckpoint: FragnoOutboxCheckpoint,\n): boolean {\n  if (\n    appliedCheckpoint?.versionstamp === incomingCheckpoint.versionstamp &&\n    appliedCheckpoint.uowId !== incomingCheckpoint.uowId\n  ) {\n    throw new Error(`Outbox checkpoint ${incomingCheckpoint.versionstamp} changed unit of work.`);\n  }\n  return !appliedCheckpoint || incomingCheckpoint.versionstamp > appliedCheckpoint.versionstamp;\n}\n"],"mappings":";AAAA,MAAa,mDACX;;AAeF,SAAgB,4BACd,mBACA,oBACS;CACT,IACE,mBAAmB,iBAAiB,mBAAmB,gBACvD,kBAAkB,UAAU,mBAAmB,OAE/C,MAAM,IAAI,MAAM,qBAAqB,mBAAmB,aAAa,uBAAuB;CAE9F,OAAO,CAAC,qBAAqB,mBAAmB,eAAe,kBAAkB;AACnF"}

package/dist/coordinator/fragno-browser-persistence-startup.d.ts

@@ -0,0 +1,92 @@
+//#region src/coordinator/fragno-browser-persistence-startup.d.ts
+type FragnoBrowserDiagnostic<TValue> = {
+  status: "available";
+  value: TValue;
+} | {
+  status: "unavailable";
+  reason: string;
+} | {
+  status: "failed";
+  error: string;
+};
+type FragnoBrowserLock = {
+  name: string;
+  mode: string;
+  clientId: string | null;
+};
+type FragnoBrowserLockSnapshot = {
+  held: FragnoBrowserLock[];
+  pending: FragnoBrowserLock[];
+  relevantHeld: FragnoBrowserLock[];
+  relevantPending: FragnoBrowserLock[];
+  interpretation: string;
+};
+type FragnoBrowserStorageEstimate = {
+  quota: number | null;
+  usage: number | null;
+  usageDetails: Record<string, number> | null;
+};
+type FragnoBrowserWorkerProbeSnapshot = {
+  status: "unsupported";
+  reason: string;
+} | {
+  status: "starting";
+  elapsedMs: number;
+} | {
+  status: "responsive";
+  responseMs: number;
+  runtime: {
+    timerAvailable: boolean;
+    opfsAvailable: boolean;
+    fileSystemFileHandleGlobalAvailable: boolean;
+    syncAccessHandlePrototypeAvailable: boolean;
+  };
+} | {
+  status: "failed";
+  error: string;
+};
+type FragnoOPFSEntry = {
+  kind: "file";
+  name: string;
+} | {
+  kind: "directory";
+  name: string;
+  entries: Array<{
+    name: string;
+    kind: string;
+  }>;
+  inspectionError: string | null;
+};
+/** Captures worker, runtime, storage, Web Locks, and OPFS state during a stalled browser startup. */
+type FragnoBrowserPersistenceDiagnostics = {
+  databaseName: string;
+  elapsedMs: number;
+  timerDriftMs: number;
+  collectedAt: string;
+  likelyCause: string;
+  workerProbe: FragnoBrowserWorkerProbeSnapshot;
+  runtime: {
+    href: string | null;
+    origin: string | null;
+    userAgent: string | null;
+    visibilityState: DocumentVisibilityState | null;
+    readyState: DocumentReadyState | null;
+    documentHasFocus: boolean | null;
+    isSecureContext: boolean;
+    crossOriginIsolated: boolean;
+    online: boolean | null;
+    hardwareConcurrency: number | null;
+    workerAvailable: boolean;
+    broadcastChannelAvailable: boolean;
+    webLocksAvailable: boolean;
+    opfsAvailable: boolean;
+    fileSystemFileHandleGlobalAvailable: boolean;
+  };
+  webLocks: FragnoBrowserDiagnostic<FragnoBrowserLockSnapshot>;
+  storageEstimate: FragnoBrowserDiagnostic<FragnoBrowserStorageEstimate>;
+  persistedStorage: FragnoBrowserDiagnostic<boolean>;
+  opfsEntries: FragnoBrowserDiagnostic<FragnoOPFSEntry[]>;
+};
+//#endregion
+export { FragnoBrowserPersistenceDiagnostics };
+//# sourceMappingURL=fragno-browser-persistence-startup.d.ts.map

package/dist/coordinator/fragno-browser-persistence-startup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fragno-browser-persistence-startup.d.ts","names":[],"sources":["../../src/coordinator/fragno-browser-persistence-startup.ts"],"mappings":";KAGK,wBAAwB;EACvB;EAAqB,OAAO;;EAC5B;EAAuB;;EACvB;EAAkB;;KAEnB;EACH;EACA;EACA;;KAGG;EACH,MAAM;EACN,SAAS;EACT,cAAc;EACd,iBAAiB;EACjB;;KAGG;EACH;EACA;EACA,cAAc;;KAGX;EACC;EAAuB;;EACvB;EAAoB;;EAEpB;EACA;EACA;IACE;IACA;IACA;IACA;;;EAGF;EAAkB;;KAOnB;EACC;EAAc;;EAEd;EACA;EACA,SAAS;IAAQ;IAAc;;EAC/B;;;KAeM;EACV;EACA;EACA;EACA;EACA;EACA,aAAa;EACb;IACE;IACA;IACA;IACA,iBAAiB;IACjB,YAAY;IACZ;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;;EAEF,UAAU,wBAAwB;EAClC,iBAAiB,wBAAwB;EACzC,kBAAkB;EAClB,aAAa,wBAAwB"}