@tanstack/browser-db-sqlite-persistence 0.2.21 → 0.2.25

package/README.md

@@ -2,6 +2,8 @@
 
 Browser SQLite persistence for TanStack DB using `wa-sqlite` + OPFS.
 
+Start with the [SQLite Persistence guide](../../docs/guides/sqlite-persistence.md) for Collection setup and lifecycle behavior.
+
 Supports both single-tab (default) and multi-tab usage. Multi-tab coordination
 is opt-in by passing a `BrowserCollectionCoordinator`.
 
@@ -9,6 +11,7 @@ is opt-in by passing a `BrowserCollectionCoordinator`.
 
 - `createBrowserWASQLitePersistence(...)`
 - `openBrowserWASQLiteOPFSDatabase(...)`
+- `BrowserCollectionCoordinator`
 - `persistedCollectionOptions(...)` (re-exported from core)
 
 ## Quick start (single-tab)
@@ -97,13 +100,84 @@ export const todosCollection = createCollection(
 See [`examples/react/offline-transactions`](../../examples/react/offline-transactions/src/db/persisted-todos.ts)
 for a full multi-tab example.
 
+### Committed transaction ownership
+
+The persisted sync wrapper sends every source transaction with durable effects
+through the coordinator's required
+`requestApplyCommittedTx(collectionId, tx)` method.
+`BrowserCollectionCoordinator` routes the complete transaction to the current
+leader for that collection. The leader applies it with the adapter registered
+for the same collection id, including that collection's resolved mode and
+`schemaVersion`.
+
+The route preserves truncation, row changes, row metadata, collection metadata,
+and stream position as one `PersistedTx`. It does not feature-detect a partial
+route or fall back to row-only mutation RPC. A custom coordinator that omits
+`requestApplyCommittedTx` is rejected while the collection is configured,
+before its sync source can publish rows. An effect-free source commit neither
+publishes nor consumes a coordinator sequence.
+
+Single-tab mode uses the same complete transaction contract. Its
+`SingleProcessCoordinator` skips election and channel traffic but still routes
+the transaction to the resolved adapter for that collection.
+
+If a mutating RPC loses its response, Browser coordination replays it only
+while the requester still knows the same non-null leader id and term. An
+unknown initial route or any leader/term change rejects with
+`IndeterminateCommitError`; the application must reconcile the outcome. The
+coordinator does not retry that mutation against an unknown or replacement
+leader.
+
+### Remote subset requests
+
+`BrowserCollectionCoordinator.requestEnsureRemoteSubset(...)` validates and
+projects the request before it chooses the local leader or `BroadcastChannel`
+route. Registered owners receive the exported
+`TransportedLoadSubsetOptions` type. It contains the supported
+structured-clone wire data and excludes live `signal` and `subscription`
+fields. Unsupported nested values fail immediately with
+`RemoteSubsetWireValueError` and the exact value path; no owner callback or
+channel post occurs. See the core package's remote subset wire contract for the
+complete supported domain.
+
+Each accepted request is an explicit lease. Retries of the same request object
+reuse its acquisition identity, while distinct equal request objects remain
+independent. Release is routed to the elected collection owner and unloads the
+exact acquired options once. Leadership loss unloads the retiring owner's live
+leases, and requesters replay still-live acquisitions against the next leader.
+Registering a second owner for one collection throws
+`DuplicateRemoteSubsetOwnerError`; no adapter fallback replaces the owner.
+Remote follower transport/admission failures reject and retain demand for its
+normal retry without entering the follower's local owner lifecycle. Terminal
+release identities expire after the existing RPC dedupe horizon while delayed
+duplicates inside that horizon remain idempotent.
+
 ## Notes
 
 - `openBrowserWASQLiteOPFSDatabase(...)` starts a dedicated Web Worker and
   routes SQL operations through it. OPFS sync access handle APIs are used in
   that worker context.
+- Opening has a 30-second deadline by default. `timeoutMs` changes it; `0`
+  explicitly disables the deadline. A timed-out open rejects with
+  `TimeoutError` and terminates its pending worker, so it cannot acquire the
+  database later. Pass an `AbortSignal` to cancel earlier; the signal applies
+  only while opening, not to the established connection.
+- On `pagehide`, the connection terminates its worker synchronously and rejects
+  pending initialization, queries, and close operations with `AbortError`. This
+  also applies when the document enters the back/forward cache. Applications
+  restored through
+  `pageshow` with `event.persisted` must create fresh database connections and
+  persistence/collection instances (or reload the application).
+- Flush application writes and await `database.close()` before navigating when
+  possible. The `pagehide` cleanup releases resources; it cannot await pending
+  writes or serve as a durability guarantee.
 - Single-tab mode does not require `BroadcastChannel` or Web Locks for
-  correctness.
+  election, but committed transactions still go through the collection's
+  registered persistence owner.
 - Multi-tab mode requires `BroadcastChannel` and the Web Locks API; both are
   available in all modern browsers.
 - OPFS capability failures are surfaced as `PersistenceUnavailableError`.
+- SQLite open failures include the underlying VFS error name and message when
+  wa-sqlite exposes them. Some failures, including native access-handle
+  contention, are not currently exposed by wa-sqlite and retain SQLite's
+  generic open error.

package/dist/assets/{opfs-worker-uyjx5Rus.js → opfs-worker-accoEoax.js}

@@ -5755,11 +5755,22 @@
     sqlite3.vfs_register(opfsVfs, true);
     const openFlags = SQLITE_OPEN_CREATE | SQLITE_OPEN_READWRITE | SQLITE_OPEN_URI;
     const databaseFileUri = `file:${request.databaseName}?vfs=${encodeURIComponent(request.vfsName)}`;
-    const dbHandle = await sqlite3.open_v2(
-      databaseFileUri,
-      openFlags,
-      request.vfsName
-    );
+    let dbHandle;
+    try {
+      dbHandle = await sqlite3.open_v2(
+        databaseFileUri,
+        openFlags,
+        request.vfsName
+      );
+    } catch (error) {
+      const cause = opfsVfs.lastError;
+      if (error instanceof Error && cause instanceof Error) {
+        throw new Error(`${error.message}: ${cause.name}: ${cause.message}`, {
+          cause
+        });
+      }
+      throw error;
+    }
     sqlite3Instance = sqlite3;
     sqliteDatabaseHandle = dbHandle;
     opfsVfsInstance = opfsVfs;
@@ -5876,4 +5887,4 @@
     });
   });
 })();
-//# sourceMappingURL=opfs-worker-uyjx5Rus.js.map
+//# sourceMappingURL=opfs-worker-accoEoax.js.map