@livestore/adapter-web 0.4.0-dev.20 → 0.4.0-dev.22

package/src/web-worker/client-session/persisted-adapter.ts

@@ -1,4 +1,4 @@
-import type { Adapter, ClientSession, LockStatus } from '@livestore/common'
+import type { Adapter, BootWarningReason, ClientSession, LockStatus } from '@livestore/common'
 import {
   IntentionalShutdownCause,
   liveStoreVersion,
@@ -12,7 +12,7 @@ import {
 // import LiveStoreSharedWorker from '@livestore/adapter-web/internal-shared-worker?sharedworker'
 import { EventSequenceNumber } from '@livestore/common/schema'
 import { sqliteDbFactory } from '@livestore/sqlite-wasm/browser'
-import { isDevEnv, shouldNeverHappen, tryAsFunctionAndNew } from '@livestore/utils'
+import { isDevEnv, omitUndefineds, shouldNeverHappen, tryAsFunctionAndNew } from '@livestore/utils'
 import {
   Cause,
   Deferred,
@@ -29,8 +29,9 @@ import {
   Worker,
   WorkerError,
 } from '@livestore/utils/effect'
-import { BrowserWorker, Opfs, WebLock } from '@livestore/utils/effect/browser'
+import { BrowserWorker, Opfs, WebError, WebLock } from '@livestore/utils/effect/browser'
 import { nanoid } from '@livestore/utils/nanoid'
+import { makeSingleTabAdapter } from '../../single-tab/single-tab-adapter.ts'
 import {
   readPersistedStateDbFromClientSession,
   resetPersistedDataFromClientSession,
@@ -41,6 +42,16 @@ import * as WorkerSchema from '../common/worker-schema.ts'
 import { connectWebmeshNodeClientSession } from './client-session-devtools.ts'
 import { loadSqlite3 } from './sqlite-loader.ts'
 
+/**
+ * Checks if SharedWorker API is available in the current browser context.
+ *
+ * Returns false on Android Chrome and other browsers without SharedWorker support.
+ *
+ * @see https://github.com/livestorejs/livestore/issues/321
+ * @see https://issues.chromium.org/issues/40290702
+ */
+export const canUseSharedWorker = (): boolean => typeof SharedWorker !== 'undefined'
+
 if (isDevEnv()) {
   globalThis.__debugLiveStoreUtils = {
     ...globalThis.__debugLiveStoreUtils,
@@ -120,6 +131,15 @@ export type WebAdapterOptions = {
  * Creates a web adapter with persistent storage (currently only supports OPFS).
  * Requires both a web worker and a shared worker.
  *
+ * On browsers without SharedWorker support (e.g. Android Chrome), this adapter
+ * automatically falls back to single-tab mode. In single-tab mode:
+ * - Each tab runs independently with its own leader worker
+ * - Multi-tab synchronization is not available
+ * - Devtools are not supported
+ *
+ * @see https://github.com/livestorejs/livestore/issues/321 - SharedWorker tracking issue
+ * @see https://issues.chromium.org/issues/40290702 - Chromium SharedWorker bug
+ *
  * @example
  * ```ts
  * import { makePersistedAdapter } from '@livestore/adapter-web'
@@ -137,6 +157,26 @@ export const makePersistedAdapter =
   (options: WebAdapterOptions): Adapter =>
   (adapterArgs) =>
     Effect.gen(function* () {
+      // Check SharedWorker availability first and fall back to single-tab mode if unavailable
+      if (!canUseSharedWorker()) {
+        yield* Effect.logWarning(
+          '[@livestore/adapter-web] SharedWorker unavailable (e.g. Android Chrome). ' +
+            'Falling back to single-tab mode. Multi-tab synchronization and devtools are disabled. ' +
+            'See: https://github.com/livestorejs/livestore/issues/321',
+        )
+
+        return yield* makeSingleTabAdapter({
+          worker: options.worker,
+          storage: options.storage,
+          ...omitUndefineds({
+            resetPersistence: options.resetPersistence,
+            clientId: options.clientId,
+            sessionId: options.sessionId,
+            experimental: options.experimental,
+          }),
+        })(adapterArgs)
+      }
+
       const {
         schema,
         storeId,
@@ -168,10 +208,21 @@ export const makePersistedAdapter =
 
       const shutdownChannel = yield* makeShutdownChannel(storeId)
 
-      if (options.resetPersistence === true) {
+      // Check OPFS availability early and notify user if storage is unavailable (e.g. private browsing)
+      const opfsWarning = yield* checkOpfsAvailability
+      if (opfsWarning !== undefined) {
+        yield* Effect.logWarning('[@livestore/adapter-web:client-session] OPFS unavailable', opfsWarning)
+      }
+
+      if (options.resetPersistence === true && opfsWarning === undefined) {
         yield* shutdownChannel.send(IntentionalShutdownCause.make({ reason: 'adapter-reset' }))
 
         yield* resetPersistedDataFromClientSession({ storageOptions, storeId })
+      } else if (options.resetPersistence === true) {
+        yield* Effect.logWarning(
+          '[@livestore/adapter-web:client-session] Skipping persistence reset because storage is unavailable',
+          opfsWarning,
+        )
       }
 
       // Note on fast-path booting:
@@ -181,7 +232,7 @@ export const makePersistedAdapter =
       // We need to be extra careful though to not run into any race conditions or inconsistencies.
       // TODO also verify persisted data
       const dataFromFile =
-        options.experimental?.disableFastPath === true
+        options.experimental?.disableFastPath === true || opfsWarning !== undefined
           ? undefined
           : yield* readPersistedStateDbFromClientSession({ storageOptions, storeId, schema }).pipe(
               Effect.tapError((error) =>
@@ -473,9 +524,18 @@ export const makePersistedAdapter =
                 attributes: { batchSize: batch.length },
               }),
             ),
+          stream: (options) =>
+            runInWorkerStream(new WorkerSchema.LeaderWorkerInnerStreamEvents(options)).pipe(
+              Stream.withSpan('@livestore/adapter-web:client-session:streamEvents'),
+              Stream.orDie,
+            ),
         },
 
-        initialState: { leaderHead: initialLeaderHead, migrationsReport },
+        initialState: {
+          leaderHead: initialLeaderHead,
+          migrationsReport,
+          storageMode: opfsWarning === undefined ? 'persisted' : 'in-memory',
+        },
 
         getEventlogData: runInWorker(new WorkerSchema.LeaderWorkerInnerExportEventlog()).pipe(
           Effect.timeout(10_000),
@@ -579,3 +639,29 @@ const ensureBrowserRequirements = Effect.gen(function* () {
     validate(typeof sessionStorage === 'undefined', 'sessionStorage'),
   ])
 })
+
+/**
+ * Attempts to access OPFS and returns a warning if unavailable.
+ *
+ * Common failure scenarios:
+ * - Safari/Firefox private browsing: SecurityError or NotAllowedError
+ * - Permission denied: NotAllowedError
+ * - Quota exceeded: QuotaExceededError
+ */
+const checkOpfsAvailability = Effect.gen(function* () {
+  const opfs = yield* Opfs.Opfs
+  return yield* opfs.getRootDirectoryHandle.pipe(
+    Effect.as(undefined),
+    Effect.catchAll((error) => {
+      const reason: BootWarningReason =
+        Schema.is(WebError.SecurityError)(error) || Schema.is(WebError.NotAllowedError)(error)
+          ? 'private-browsing'
+          : 'storage-unavailable'
+      const message =
+        reason === 'private-browsing'
+          ? 'Storage unavailable in private browsing mode. LiveStore will continue without persistence.'
+          : 'Storage access denied. LiveStore will continue without persistence.'
+      return Effect.succeed({ reason, message } as const)
+    }),
+  )
+})

package/src/web-worker/common/persisted-sqlite.ts

@@ -88,7 +88,7 @@ export const resetPersistedDataFromClientSession = Effect.fn(
 )(
   function* ({ storageOptions, storeId }: { storageOptions: WorkerSchema.StorageType; storeId: string }) {
     const directory = yield* sanitizeOpfsDir(storageOptions.directory, storeId)
-    yield* Opfs.remove(directory).pipe(
+    yield* Opfs.remove(directory, { recursive: true }).pipe(
       // We ignore NotFoundError here as it may not exist or have already been deleted
       Effect.catchTag('@livestore/utils/Web/NotFoundError', () => Effect.void),
     )
@@ -192,8 +192,20 @@ export const cleanupOldStateDbFiles: (options: {
       const archiveFileData = yield* vfs.readFilePayload(fileName)
 
       const archiveFileName = `${Date.now()}-${fileName}`
-
-      yield* Opfs.writeFile(`${opfsDirectory}/archive/${archiveFileName}`, new Uint8Array(archiveFileData))
+      const archivePath = `${opfsDirectory}/archive/${archiveFileName}`
+      const archiveData = new Uint8Array(archiveFileData)
+
+      // Prefer writeFile (atomic) when createWritable is available (Chrome, Firefox, Safari 26+),
+      // fall back to syncWriteFile (non-atomic) for Safari 18.x compatibility.
+      // TODO: Remove feature detection and use writeFile directly when Safari >= 26 is widely available.
+      const supportsCreateWritable =
+        typeof FileSystemFileHandle !== 'undefined' && 'createWritable' in FileSystemFileHandle.prototype
+
+      if (supportsCreateWritable) {
+        yield* Opfs.writeFile(archivePath, archiveData)
+      } else {
+        yield* Opfs.syncWriteFile(archivePath, archiveData)
+      }
     }
 
     const vfsResultCode = yield* Effect.try({

package/src/web-worker/common/worker-schema.ts

@@ -8,6 +8,7 @@ import {
   SyncState,
   UnknownError,
 } from '@livestore/common'
+import { StreamEventsOptionsFields } from '@livestore/common/leader-thread'
 import { EventSequenceNumber, LiveStoreEvent } from '@livestore/common/schema'
 import * as WebmeshWorker from '@livestore/devtools-web-common/worker'
 import { Schema, Transferable } from '@livestore/utils/effect'
@@ -102,6 +103,15 @@ export class LeaderWorkerInnerPullStream extends Schema.TaggedRequest<LeaderWork
   failure: UnknownError,
 }) {}
 
+export class LeaderWorkerInnerStreamEvents extends Schema.TaggedRequest<LeaderWorkerInnerStreamEvents>()(
+  'StreamEvents',
+  {
+    payload: StreamEventsOptionsFields,
+    success: LiveStoreEvent.Client.Encoded,
+    failure: UnknownError,
+  },
+) {}
+
 export class LeaderWorkerInnerExport extends Schema.TaggedRequest<LeaderWorkerInnerExport>()('Export', {
   payload: {},
   success: Transferable.Uint8Array as Schema.Schema<Uint8Array<ArrayBuffer>>,
@@ -196,6 +206,7 @@ export const LeaderWorkerInnerRequest = Schema.Union(
   LeaderWorkerInnerBootStatusStream,
   LeaderWorkerInnerPushToLeader,
   LeaderWorkerInnerPullStream,
+  LeaderWorkerInnerStreamEvents,
   LeaderWorkerInnerExport,
   LeaderWorkerInnerExportEventlog,
   LeaderWorkerInnerGetRecreateSnapshot,
@@ -237,6 +248,7 @@ export class SharedWorkerRequest extends Schema.Union(
   LeaderWorkerInnerBootStatusStream,
   LeaderWorkerInnerPushToLeader,
   LeaderWorkerInnerPullStream,
+  LeaderWorkerInnerStreamEvents,
   LeaderWorkerInnerExport,
   LeaderWorkerInnerGetRecreateSnapshot,
   LeaderWorkerInnerExportEventlog,

package/src/web-worker/leader-worker/make-leader-worker.ts

@@ -1,7 +1,13 @@
-import type { SqliteDb, SyncOptions } from '@livestore/common'
+import type { BootStatus, BootWarningReason, SqliteDb, SyncOptions } from '@livestore/common'
 import { Devtools, LogConfig, UnknownError } from '@livestore/common'
-import type { DevtoolsOptions } from '@livestore/common/leader-thread'
-import { configureConnection, Eventlog, LeaderThreadCtx, makeLeaderThreadLayer } from '@livestore/common/leader-thread'
+import type { DevtoolsOptions, StreamEventsOptions } from '@livestore/common/leader-thread'
+import {
+  configureConnection,
+  Eventlog,
+  LeaderThreadCtx,
+  makeLeaderThreadLayer,
+  streamEventsWithSyncState,
+} from '@livestore/common/leader-thread'
 import type { LiveStoreSchema } from '@livestore/common/schema'
 import { LiveStoreEvent } from '@livestore/common/schema'
 import * as WebmeshWorker from '@livestore/devtools-web-common/worker'
@@ -16,12 +22,12 @@ import {
   Layer,
   OtelTracer,
   Scheduler,
-  type Schema,
+  Schema,
   Stream,
   TaskTracing,
   WorkerRunner,
 } from '@livestore/utils/effect'
-import { BrowserWorkerRunner, Opfs } from '@livestore/utils/effect/browser'
+import { BrowserWorkerRunner, Opfs, WebError } from '@livestore/utils/effect/browser'
 import type * as otel from '@opentelemetry/api'
 
 import { cleanupOldStateDbFiles, getStateDbFileName, sanitizeOpfsDir } from '../common/persisted-sqlite.ts'
@@ -112,13 +118,28 @@ const makeWorkerRunnerInner = ({ schema, sync: syncOptions, syncPayloadSchema }:
       Effect.gen(function* () {
         const sqlite3 = yield* Effect.promise(() => loadSqlite3Wasm())
         const makeSqliteDb = sqliteDbFactory({ sqlite3 })
-        const opfsDirectory = yield* sanitizeOpfsDir(storageOptions.directory, storeId)
         const runtime = yield* Effect.runtime<never>()
 
-        const makeDb = (kind: 'state' | 'eventlog') =>
+        // Check OPFS availability and determine storage mode
+        const opfsCheck = yield* checkOpfsAvailability
+        const useOpfs = opfsCheck === undefined
+
+        // Track boot warning to emit later
+        let bootWarning: BootStatus | undefined
+        if (!useOpfs) {
+          yield* Effect.logWarning(
+            '[@livestore/adapter-web:worker] OPFS unavailable, using in-memory storage',
+            opfsCheck,
+          )
+          bootWarning = { stage: 'warning', ...opfsCheck }
+        }
+
+        const opfsDirectory = useOpfs ? yield* sanitizeOpfsDir(storageOptions.directory, storeId) : undefined
+
+        const makeOpfsDb = (kind: 'state' | 'eventlog') =>
           makeSqliteDb({
             _tag: 'opfs',
-            opfsDirectory,
+            opfsDirectory: opfsDirectory!,
             fileName: kind === 'state' ? getStateDbFileName(schema) : 'eventlog.db',
             configureDb: (db) =>
               configureConnection(db, {
@@ -131,10 +152,17 @@ const makeWorkerRunnerInner = ({ schema, sync: syncOptions, syncPayloadSchema }:
               }).pipe(Effect.provide(runtime), Effect.runSync),
           }).pipe(Effect.acquireRelease((db) => Effect.try(() => db.close()).pipe(Effect.ignoreLogged)))
 
-        // Might involve some async work, so we're running them concurrently
-        const [dbState, dbEventlog] = yield* Effect.all([makeDb('state'), makeDb('eventlog')], {
-          concurrency: 2,
-        })
+        const makeInMemoryDb = () =>
+          makeSqliteDb({
+            _tag: 'in-memory',
+            configureDb: (db) =>
+              configureConnection(db, { foreignKeys: true }).pipe(Effect.provide(runtime), Effect.runSync),
+          }).pipe(Effect.acquireRelease((db) => Effect.try(() => db.close()).pipe(Effect.ignoreLogged)))
+
+        // Use OPFS if available, otherwise fall back to in-memory
+        const [dbState, dbEventlog] = useOpfs
+          ? yield* Effect.all([makeOpfsDb('state'), makeOpfsDb('eventlog')], { concurrency: 2 })
+          : yield* Effect.all([makeInMemoryDb(), makeInMemoryDb()], { concurrency: 2 })
 
         // Clean up old state database files after successful database creation
         // This prevents OPFS file pool capacity exhaustion from accumulated state db files after schema changes/migrations
@@ -161,6 +189,7 @@ const makeWorkerRunnerInner = ({ schema, sync: syncOptions, syncPayloadSchema }:
           shutdownChannel,
           syncPayloadEncoded,
           syncPayloadSchema,
+          ...(bootWarning !== undefined ? { bootWarning } : {}),
         })
       }).pipe(
         Effect.tapCauseLogPretty,
@@ -185,7 +214,7 @@ const makeWorkerRunnerInner = ({ schema, sync: syncOptions, syncPayloadSchema }:
       }).pipe(UnknownError.mapToUnknownError, Effect.withSpan('@livestore/adapter-web:worker:GetRecreateSnapshot')),
     PullStream: ({ cursor }) =>
       Effect.gen(function* () {
-        const { syncProcessor } = yield* LeaderThreadCtx
+        const { syncProcessor } = yield* LeaderThreadCtx // <- syncState comes from here
         return syncProcessor.pull({ cursor })
       }).pipe(
         Stream.unwrapScoped,
@@ -200,6 +229,20 @@ const makeWorkerRunnerInner = ({ schema, sync: syncOptions, syncPayloadSchema }:
           { waitForProcessing: true },
         ),
       ).pipe(Effect.uninterruptible, Effect.withSpan('@livestore/adapter-web:worker:PushToLeader')),
+    StreamEvents: (options) =>
+      LeaderThreadCtx.pipe(
+        Effect.map(({ dbEventlog, syncProcessor }) => {
+          const { _tag: _ignored, ...payload } = options as any
+          const streamOptions = payload as StreamEventsOptions
+          return streamEventsWithSyncState({
+            dbEventlog,
+            syncState: syncProcessor.syncState,
+            options: streamOptions,
+          })
+        }),
+        Stream.unwrapScoped,
+        Stream.withSpan('@livestore/adapter-web:worker:StreamEvents'),
+      ),
     Export: () =>
       Effect.andThen(LeaderThreadCtx, (_) => _.dbState.export()).pipe(
         UnknownError.mapToUnknownError,
@@ -271,13 +314,39 @@ const makeDevtoolsOptions = ({
 
     return {
       enabled: true,
-      boot: Effect.gen(function* () {
-        const persistenceInfo = {
+      boot: Effect.succeed({
+        node,
+        persistenceInfo: {
           state: dbState.metadata.persistenceInfo,
           eventlog: dbEventlog.metadata.persistenceInfo,
-        }
-
-        return { node, persistenceInfo, mode: 'direct' }
+        },
+        mode: 'direct' as const,
       }),
     }
   })
+
+/**
+ * Attempts to access OPFS and returns a warning if unavailable.
+ *
+ * Common failure scenarios:
+ * - Safari/Firefox private browsing: SecurityError or NotAllowedError
+ * - Permission denied: NotAllowedError
+ * - Quota exceeded: QuotaExceededError
+ */
+const checkOpfsAvailability = Effect.gen(function* () {
+  const opfs = yield* Opfs.Opfs
+  return yield* opfs.getRootDirectoryHandle.pipe(
+    Effect.as(undefined),
+    Effect.catchAll((error) => {
+      const reason: BootWarningReason =
+        Schema.is(WebError.SecurityError)(error) || Schema.is(WebError.NotAllowedError)(error)
+          ? 'private-browsing'
+          : 'storage-unavailable'
+      const message =
+        reason === 'private-browsing'
+          ? 'Storage unavailable in private browsing mode. LiveStore will continue without persistence.'
+          : 'Storage access denied. LiveStore will continue without persistence.'
+      return Effect.succeed({ reason, message } as const)
+    }),
+  )
+})

package/src/web-worker/shared-worker/make-shared-worker.ts

@@ -243,6 +243,7 @@ const makeWorkerRunner = Effect.gen(function* () {
     BootStatusStream: forwardRequestStream,
     PushToLeader: forwardRequest,
     PullStream: forwardRequestStream,
+    StreamEvents: forwardRequestStream,
     Export: forwardRequest,
     GetRecreateSnapshot: forwardRequest,
     ExportEventlog: forwardRequest,