@tanstack/browser-db-sqlite-persistence 0.2.23 → 0.2.26

package/src/browser-persistence.ts

@@ -130,34 +130,42 @@ export function createBrowserWASQLitePersistence(
       ...(schemaVersion === undefined ? {} : { schemaVersion }),
     })
     adapterCache.set(cacheKey, adapter)
-
-    // Wire the adapter into the multi-tab coordinator so it can handle
-    // leader-side RPCs (applyCommittedTx, pullSince, ensureIndex, etc.)
-    if (resolvedCoordinator instanceof BrowserCollectionCoordinator) {
-      resolvedCoordinator.setAdapter(adapter)
-    }
-
     return adapter
   }
 
   const createCollectionPersistence = (
+    collectionId: string | undefined,
     mode: PersistedCollectionMode,
     schemaVersion: number | undefined,
-  ): PersistedCollectionPersistence => ({
-    adapter: getAdapterForCollection(mode, schemaVersion),
-    coordinator: resolvedCoordinator,
-  })
+  ): PersistedCollectionPersistence => {
+    const adapter = getAdapterForCollection(mode, schemaVersion)
+    if (resolvedCoordinator instanceof BrowserCollectionCoordinator) {
+      if (collectionId === undefined) {
+        resolvedCoordinator.setAdapter(adapter)
+      } else {
+        resolvedCoordinator.setAdapterForCollection(collectionId, adapter)
+      }
+    }
+    return {
+      adapter,
+      coordinator: resolvedCoordinator,
+    }
+  }
 
   const defaultPersistence = createCollectionPersistence(
+    undefined,
     `sync-absent`,
     undefined,
   )
+  if (resolvedCoordinator instanceof BrowserCollectionCoordinator) {
+    resolvedCoordinator.setAdapter(defaultPersistence.adapter)
+  }
 
   return {
     ...defaultPersistence,
-    resolvePersistenceForCollection: ({ mode, schemaVersion }) =>
-      createCollectionPersistence(mode, schemaVersion),
+    resolvePersistenceForCollection: ({ collectionId, mode, schemaVersion }) =>
+      createCollectionPersistence(collectionId, mode, schemaVersion),
     resolvePersistenceForMode: (mode) =>
-      createCollectionPersistence(mode, undefined),
+      createCollectionPersistence(undefined, mode, undefined),
   }
 }

package/src/index.ts

@@ -11,9 +11,18 @@ export type { BrowserCollectionCoordinatorOptions } from './browser-coordinator'
 export {
   DEFAULT_APPLIED_TX_PRUNE_MAX_AGE_SECONDS,
   DEFAULT_APPLIED_TX_PRUNE_MAX_ROWS,
+  DuplicateRemoteSubsetOwnerError,
+  IndeterminateCommitError,
+  PersistedCollectionDurabilityError,
+  RemoteSubsetWireValueError,
   persistedCollectionOptions,
 } from '@tanstack/db-sqlite-persistence-core'
 export type {
   PersistedCollectionCoordinator,
   PersistedCollectionPersistence,
+  IndeterminateCommitRequestType,
+  RemoteSubsetOwner,
+  RemoteSubsetWireExpression,
+  RemoteSubsetWireValue,
+  TransportedLoadSubsetOptions,
 } from '@tanstack/db-sqlite-persistence-core'

package/src/opfs-database.ts

@@ -11,6 +11,8 @@ import type {
 } from './opfs-worker-protocol'
 
 const DEFAULT_VFS_NAME = `opfs`
+const DEFAULT_OPEN_TIMEOUT_MS = 30_000
+const MAX_OPEN_TIMEOUT_MS = 2_147_483_647
 type BrowserOPFSFeatureGlobal = {
   navigator?: {
     storage?: {
@@ -23,6 +25,10 @@ type BrowserOPFSFeatureGlobal = {
 export type OpenBrowserWASQLiteOPFSDatabaseOptions = {
   databaseName: string
   vfsName?: string
+  /** Defaults to 30 seconds. Set to 0 to wait without a deadline. */
+  timeoutMs?: number
+  /** Cancels only the database open, not an established connection. */
+  signal?: AbortSignal
 }
 
 type BrowserOPFSWorkerLike = Pick<
@@ -99,6 +105,16 @@ function createOPFSWorkerInstance(): BrowserOPFSWorkerLike {
   return new (OPFSWorkerConstructor as unknown as new () => BrowserOPFSWorkerLike)()
 }
 
+function getOpenAbortError(signal: AbortSignal): Error {
+  const reason: unknown = signal.reason
+  return reason instanceof Error
+    ? reason
+    : new DOMException(
+        `Opening browser OPFS database was aborted`,
+        `AbortError`,
+      )
+}
+
 /**
  * Creates a browser wa-sqlite database handle backed by OPFS and
  * OPFSCoopSyncVFS.
@@ -113,6 +129,22 @@ export async function openBrowserWASQLiteOPFSDatabase(
     )
   }
 
+  const timeoutMs = options.timeoutMs ?? DEFAULT_OPEN_TIMEOUT_MS
+  if (
+    !Number.isSafeInteger(timeoutMs) ||
+    timeoutMs < 0 ||
+    timeoutMs > MAX_OPEN_TIMEOUT_MS
+  ) {
+    throw new InvalidPersistedCollectionConfigError(
+      `Browser wa-sqlite timeoutMs must be an integer between 0 and ${MAX_OPEN_TIMEOUT_MS}`,
+    )
+  }
+
+  const signal = options.signal
+  if (signal?.aborted) {
+    throw getOpenAbortError(signal)
+  }
+
   if (!hasOPFSBrowserPrerequisites(globalThis)) {
     throw new PersistenceUnavailableError(
       `Browser OPFS prerequisites are not available in this runtime`,
@@ -130,6 +162,7 @@ export async function openBrowserWASQLiteOPFSDatabase(
       return
     }
     disposed = true
+    globalThis.removeEventListener(`pagehide`, onPageHide)
     worker.removeEventListener(`message`, onMessage)
     worker.removeEventListener(`error`, onError)
     worker.removeEventListener(`messageerror`, onMessageError)
@@ -177,9 +210,22 @@ export async function openBrowserWASQLiteOPFSDatabase(
     disposeWorker()
   }
 
+  const onPageHide = (): void => {
+    // A document entering the back/forward cache can be frozen before an
+    // asynchronous close completes, including while initialization is pending.
+    rejectAllPendingRequests(
+      new DOMException(
+        `The page is closing its SQLite connection`,
+        `AbortError`,
+      ),
+    )
+    disposeWorker()
+  }
+
   worker.addEventListener(`message`, onMessage)
   worker.addEventListener(`error`, onError)
   worker.addEventListener(`messageerror`, onMessageError)
+  globalThis.addEventListener(`pagehide`, onPageHide)
 
   const sendWorkerRequest = <T>(
     request: BrowserOPFSWorkerRequestWithoutId,
@@ -217,15 +263,40 @@ export async function openBrowserWASQLiteOPFSDatabase(
     })
   }
 
+  let openTimeout: ReturnType<typeof setTimeout> | undefined
+  const onAbort = (): void => {
+    if (!signal) return
+    rejectAllPendingRequests(getOpenAbortError(signal))
+    disposeWorker()
+  }
+  const onTimeout = (): void => {
+    rejectAllPendingRequests(
+      new DOMException(
+        `Opening browser OPFS database timed out after ${timeoutMs} ms`,
+        `TimeoutError`,
+      ),
+    )
+    disposeWorker()
+  }
+
   try {
-    await sendWorkerRequest<void>({
+    const initialization = sendWorkerRequest<void>({
       type: `init`,
       databaseName,
       vfsName,
     })
+    signal?.addEventListener(`abort`, onAbort, { once: true })
+    if (signal?.aborted) onAbort()
+    if (timeoutMs > 0) {
+      openTimeout = setTimeout(onTimeout, timeoutMs)
+    }
+    await initialization
   } catch (error) {
     disposeWorker()
     throw error
+  } finally {
+    if (openTimeout !== undefined) clearTimeout(openTimeout)
+    signal?.removeEventListener(`abort`, onAbort)
   }
 
   return {
@@ -239,6 +310,10 @@ export async function openBrowserWASQLiteOPFSDatabase(
         params,
       }),
     close: async () => {
+      if (disposed) {
+        return
+      }
+
       let closeError: unknown
       try {
         await sendWorkerRequest<void>({

package/src/opfs-worker.ts

@@ -161,11 +161,22 @@ async function initializeWorkerDatabase(request: {
     SQLite.SQLITE_OPEN_READWRITE |
     SQLite.SQLITE_OPEN_URI
   const databaseFileUri = `file:${request.databaseName}?vfs=${encodeURIComponent(request.vfsName)}`
-  const dbHandle = await sqlite3.open_v2(
-    databaseFileUri,
-    openFlags,
-    request.vfsName,
-  )
+  let dbHandle: number
+  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

package/src/wa-sqlite-driver.ts

@@ -1,4 +1,7 @@
-import { InvalidPersistedCollectionConfigError } from '@tanstack/db-sqlite-persistence-core'
+import {
+  InvalidPersistedCollectionConfigError,
+  SQLITE_DRIVER_SHARED_LOGICAL_SCHEDULING_KEY,
+} from '@tanstack/db-sqlite-persistence-core'
 import type { SQLiteDriver } from '@tanstack/db-sqlite-persistence-core'
 
 export type BrowserWASQLiteDatabase = {
@@ -13,6 +16,32 @@ export type BrowserWASQLiteDriverOptions = {
   database: BrowserWASQLiteDatabase
 }
 
+type DatabaseExecutionState = {
+  queue: Promise<void>
+  nextSavepointId: number
+}
+
+const databaseExecutionStates = new WeakMap<
+  BrowserWASQLiteDatabase,
+  DatabaseExecutionState
+>()
+
+function getDatabaseExecutionState(
+  database: BrowserWASQLiteDatabase,
+): DatabaseExecutionState {
+  const existing = databaseExecutionStates.get(database)
+  if (existing) {
+    return existing
+  }
+
+  const state: DatabaseExecutionState = {
+    queue: Promise.resolve(),
+    nextSavepointId: 1,
+  }
+  databaseExecutionStates.set(database, state)
+  return state
+}
+
 function assertTransactionCallbackHasDriverArg(
   fn: (transactionDriver: SQLiteDriver) => Promise<unknown>,
 ): void {
@@ -36,39 +65,44 @@ function assertDatabaseShape(
 }
 
 export class BrowserWASQLiteDriver implements SQLiteDriver {
+  readonly [SQLITE_DRIVER_SHARED_LOGICAL_SCHEDULING_KEY] = {}
   private readonly database: BrowserWASQLiteDatabase
-  private queue: Promise<void> = Promise.resolve()
-  private nextSavepointId = 1
+  private readonly executionState: DatabaseExecutionState
   private closed = false
 
   constructor(options: BrowserWASQLiteDriverOptions) {
     assertDatabaseShape(options.database)
     this.database = options.database
+    this.executionState = getDatabaseExecutionState(this.database)
   }
 
-  async exec(sql: string): Promise<void> {
-    await this.enqueue(async () => {
+  exec(sql: string): Promise<void> {
+    return this.enqueue(async () => {
       await this.database.execute(sql)
     })
   }
 
-  async query<T>(
+  query<T>(
     sql: string,
     params: ReadonlyArray<unknown> = [],
   ): Promise<ReadonlyArray<T>> {
     return this.enqueue(() => this.database.execute<T>(sql, params))
   }
 
-  async run(sql: string, params: ReadonlyArray<unknown> = []): Promise<void> {
-    await this.enqueue(async () => {
+  run(sql: string, params: ReadonlyArray<unknown> = []): Promise<void> {
+    return this.enqueue(async () => {
       await this.database.execute(sql, params)
     })
   }
 
-  async transaction<T>(
+  transaction<T>(
     fn: (transactionDriver: SQLiteDriver) => Promise<T>,
   ): Promise<T> {
-    assertTransactionCallbackHasDriverArg(fn)
+    try {
+      assertTransactionCallbackHasDriverArg(fn)
+    } catch (error) {
+      return Promise.reject(error)
+    }
 
     return this.enqueue(async () => {
       await this.database.execute(`BEGIN IMMEDIATE`)
@@ -87,7 +121,7 @@ export class BrowserWASQLiteDriver implements SQLiteDriver {
     })
   }
 
-  async transactionWithDriver<T>(
+  transactionWithDriver<T>(
     fn: (transactionDriver: SQLiteDriver) => Promise<T>,
   ): Promise<T> {
     return this.transaction(fn)
@@ -128,8 +162,8 @@ export class BrowserWASQLiteDriver implements SQLiteDriver {
   ): Promise<T> {
     assertTransactionCallbackHasDriverArg(fn)
 
-    const savepointName = `tsdb_sp_${this.nextSavepointId}`
-    this.nextSavepointId++
+    const savepointName = `tsdb_sp_${this.executionState.nextSavepointId}`
+    this.executionState.nextSavepointId++
     await this.database.execute(`SAVEPOINT ${savepointName}`)
     try {
       const result = await fn(this.createTransactionDriver())
@@ -143,8 +177,16 @@ export class BrowserWASQLiteDriver implements SQLiteDriver {
   }
 
   private enqueue<T>(operation: () => Promise<T> | T): Promise<T> {
-    const queuedOperation = this.queue.then(operation, operation)
-    this.queue = queuedOperation.then(
+    const queuedOperation = this.executionState.queue.then(operation, operation)
+    // Brand the exact Promise returned to callers. Transparent wrappers may
+    // preserve this identity for late discovery; wrappers that create a new
+    // Promise must forward the driver key before adapter construction.
+    Object.defineProperty(
+      queuedOperation,
+      SQLITE_DRIVER_SHARED_LOGICAL_SCHEDULING_KEY,
+      { value: this[SQLITE_DRIVER_SHARED_LOGICAL_SCHEDULING_KEY] },
+    )
+    this.executionState.queue = queuedOperation.then(
       () => undefined,
       () => undefined,
     )

package/src/wa-sqlite-examples.d.ts

@@ -5,6 +5,7 @@ declare module '@journeyapps/wa-sqlite/src/examples/OPFSCoopSyncVFS.js' {
       module: unknown,
     ): Promise<{
       close?: () => Promise<void> | void
+      lastError?: unknown
     }>
   }
 }