@livestore/adapter-web 0.4.0-dev.18 → 0.4.0-dev.19

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

@@ -1,142 +1,119 @@
-import { liveStoreStorageFormatVersion, UnexpectedError } from '@livestore/common'
+import { liveStoreStorageFormatVersion } from '@livestore/common'
 import type { LiveStoreSchema } from '@livestore/common/schema'
-import { decodeSAHPoolFilename, HEADER_OFFSET_DATA, type WebDatabaseMetadataOpfs } from '@livestore/sqlite-wasm/browser'
+import {
+  decodeAccessHandlePoolFilename,
+  HEADER_OFFSET_DATA,
+  type WebDatabaseMetadataOpfs,
+} from '@livestore/sqlite-wasm/browser'
 import { isDevEnv } from '@livestore/utils'
-import { Effect, Schedule, Schema } from '@livestore/utils/effect'
-
-import * as OpfsUtils from '../../opfs-utils.ts'
+import { Chunk, Effect, Option, Order, Schedule, Schema, Stream } from '@livestore/utils/effect'
+import { Opfs, type WebError } from '@livestore/utils/effect/browser'
 import type * as WorkerSchema from './worker-schema.ts'
 
 export class PersistedSqliteError extends Schema.TaggedError<PersistedSqliteError>()('PersistedSqliteError', {
   message: Schema.String,
-  cause: Schema.Defect,
+  cause: Schema.optional(Schema.Defect),
 }) {}
 
-export const readPersistedAppDbFromClientSession = ({
-  storageOptions,
-  storeId,
-  schema,
-}: {
+export const readPersistedStateDbFromClientSession: (args: {
   storageOptions: WorkerSchema.StorageType
   storeId: string
   schema: LiveStoreSchema
-}) =>
-  Effect.promise(async () => {
-    const directory = sanitizeOpfsDir(storageOptions.directory, storeId)
-    const sahPoolOpaqueDir = await OpfsUtils.getDirHandle(directory).catch(() => undefined)
-
-    if (sahPoolOpaqueDir === undefined) {
-      return undefined
-    }
-
-    const tryGetDbFile = async (fileHandle: FileSystemFileHandle) => {
-      const file = await fileHandle.getFile()
-      const fileName = await decodeSAHPoolFilename(file)
-      return fileName ? { fileName, file } : undefined
-    }
+}) => Effect.Effect<
+  Uint8Array<ArrayBuffer>,
+  // All the following errors could actually happen:
+  | PersistedSqliteError
+  | WebError.UnknownError
+  | WebError.TypeError
+  | WebError.NotFoundError
+  | WebError.NotAllowedError
+  | WebError.TypeMismatchError
+  | WebError.SecurityError
+  | Opfs.OpfsError,
+  Opfs.Opfs
+> = Effect.fn('@livestore/adapter-web:readPersistedStateDbFromClientSession')(
+  function* ({ storageOptions, storeId, schema }) {
+    const accessHandlePoolDirString = yield* sanitizeOpfsDir(storageOptions.directory, storeId)
+
+    const accessHandlePoolDirHandle = yield* Opfs.getDirectoryHandleByPath(accessHandlePoolDirString)
+
+    const stateDbFileName = `/${getStateDbFileName(schema)}`
+
+    const handlesStream = yield* Opfs.Opfs.values(accessHandlePoolDirHandle)
+
+    const stateDbFileOption = yield* handlesStream.pipe(
+      Stream.filter((handle): handle is FileSystemFileHandle => handle.kind === 'file'),
+      Stream.mapEffect(
+        (fileHandle) =>
+          Effect.gen(function* () {
+            const file = yield* Opfs.Opfs.getFile(fileHandle)
+            const fileName = yield* Effect.promise(() => decodeAccessHandlePoolFilename(file))
+            return { file, fileName }
+          }),
+        { concurrency: 'unbounded' },
+      ),
+      Stream.find(({ fileName }) => fileName === stateDbFileName),
+      Stream.runHead,
+    )
 
-    const getAllFiles = async (asyncIterator: AsyncIterable<FileSystemHandle>): Promise<FileSystemFileHandle[]> => {
-      const results: FileSystemFileHandle[] = []
-      for await (const value of asyncIterator) {
-        if (value.kind === 'file') {
-          results.push(value as FileSystemFileHandle)
-        }
-      }
-      return results
+    if (Option.isNone(stateDbFileOption)) {
+      return yield* new PersistedSqliteError({
+        message: `State database file not found in client session (expected '${stateDbFileName}' in '${accessHandlePoolDirString}')`,
+      })
     }
 
-    const files = await getAllFiles(sahPoolOpaqueDir.values())
-
-    const fileResults = await Promise.all(files.map(tryGetDbFile))
-
-    const appDbFileName = `/${getStateDbFileName(schema)}`
-
-    const dbFileRes = fileResults.find((_) => _?.fileName === appDbFileName)
-    // console.debug('fileResults', fileResults, 'dbFileRes', dbFileRes)
-
-    if (dbFileRes !== undefined) {
-      const data = await dbFileRes.file.slice(HEADER_OFFSET_DATA).arrayBuffer()
-      // console.debug('readPersistedAppDbFromClientSession', data.byteLength, data)
-
-      // Given the SAH pool always eagerly creates files with empty non-header data,
-      // we want to return undefined if the file exists but is empty
-      if (data.byteLength === 0) {
-        return undefined
-      }
+    const stateDbBuffer = yield* Effect.promise(() =>
+      stateDbFileOption.value.file.slice(HEADER_OFFSET_DATA).arrayBuffer(),
+    )
 
-      return new Uint8Array(data)
+    // Given the access handle pool always eagerly creates files with empty non-header data,
+    // we want to return undefined if the file exists but is empty
+    if (stateDbBuffer.byteLength === 0) {
+      return yield* new PersistedSqliteError({
+        message: `State database file is empty in client session (expected '${stateDbFileName}' in '${accessHandlePoolDirString}')`,
+      })
     }
 
-    return undefined
-  }).pipe(
-    Effect.logWarnIfTakesLongerThan({
-      duration: 1000,
-      label: '@livestore/adapter-web:readPersistedAppDbFromClientSession',
-    }),
-    Effect.withPerformanceMeasure('@livestore/adapter-web:readPersistedAppDbFromClientSession'),
-    Effect.withSpan('@livestore/adapter-web:readPersistedAppDbFromClientSession'),
-  )
-
-export const resetPersistedDataFromClientSession = ({
-  storageOptions,
-  storeId,
-}: {
-  storageOptions: WorkerSchema.StorageType
-  storeId: string
-}) =>
-  Effect.gen(function* () {
-    const directory = sanitizeOpfsDir(storageOptions.directory, storeId)
-    yield* opfsDeleteAbs(directory)
-  }).pipe(
-    Effect.retry({
-      schedule: Schedule.exponentialBackoff10Sec,
-    }),
-    Effect.withSpan('@livestore/adapter-web:resetPersistedDataFromClientSession'),
-  )
+    return new Uint8Array(stateDbBuffer)
+  },
+  Effect.logWarnIfTakesLongerThan({
+    duration: 1000,
+    label: '@livestore/adapter-web:readPersistedStateDbFromClientSession',
+  }),
+  Effect.withPerformanceMeasure('@livestore/adapter-web:readPersistedStateDbFromClientSession'),
+)
 
-const opfsDeleteAbs = (absPath: string) =>
-  Effect.promise(async () => {
-    // Get the root directory handle
-    const root = await OpfsUtils.rootHandlePromise
-
-    // Split the absolute path to traverse directories
-    const pathParts = absPath.split('/').filter((part) => part.length)
-
-    try {
-      // Traverse to the target file handle
-      let currentDir = root
-      for (let i = 0; i < pathParts.length - 1; i++) {
-        currentDir = await currentDir.getDirectoryHandle(pathParts[i]!)
-      }
-
-      // Delete the file
-      await currentDir.removeEntry(pathParts.at(-1)!, { recursive: true })
-    } catch (error) {
-      if (error instanceof DOMException && error.name === 'NotFoundError') {
-        // Can ignore as it's already been deleted or not there in the first place
-        return
-      } else {
-        throw error
-      }
-    }
-  }).pipe(
-    UnexpectedError.mapToUnexpectedError,
-    Effect.withSpan('@livestore/adapter-web:worker:opfsDeleteFile', { attributes: { absFilePath: absPath } }),
-  )
+export const resetPersistedDataFromClientSession = Effect.fn(
+  '@livestore/adapter-web:resetPersistedDataFromClientSession',
+)(
+  function* ({ storageOptions, storeId }: { storageOptions: WorkerSchema.StorageType; storeId: string }) {
+    const directory = yield* sanitizeOpfsDir(storageOptions.directory, storeId)
+    yield* Opfs.remove(directory).pipe(
+      // We ignore NotFoundError here as it may not exist or have already been deleted
+      Effect.catchTag('@livestore/utils/Web/NotFoundError', () => Effect.void),
+    )
+  },
+  Effect.retry({
+    schedule: Schedule.exponentialBackoff10Sec,
+  }),
+)
 
-export const sanitizeOpfsDir = (directory: string | undefined, storeId: string) => {
-  // Root dir should be `''` not `/`
-  if (directory === undefined || directory === '' || directory === '/')
+export const sanitizeOpfsDir = Effect.fn('@livestore/adapter-web:sanitizeOpfsDir')(function* (
+  directory: string | undefined,
+  storeId: string,
+) {
+  if (directory === undefined || directory === '' || directory === '/') {
     return `livestore-${storeId}@${liveStoreStorageFormatVersion}`
+  }
 
   if (directory.includes('/')) {
-    throw new Error(
-      `@livestore/adapter-web:worker:sanitizeOpfsDir: Nested directories are not yet supported ('${directory}')`,
-    )
+    return yield* new PersistedSqliteError({
+      message: `Nested directories are not yet supported ('${directory}')`,
+    })
   }
 
   return `${directory}@${liveStoreStorageFormatVersion}`
-}
+})
 
 export const getStateDbFileName = (schema: LiveStoreSchema) => {
   const schemaHashSuffix =
@@ -145,6 +122,7 @@ export const getStateDbFileName = (schema: LiveStoreSchema) => {
 }
 
 export const MAX_ARCHIVED_STATE_DBS_IN_DEV = 3
+export const ARCHIVE_DIR_NAME = 'archive'
 
 /**
  * Cleanup old state database files after successful migration.
@@ -153,210 +131,119 @@ export const MAX_ARCHIVED_STATE_DBS_IN_DEV = 3
  * @param vfs - The AccessHandlePoolVFS instance for safe file operations
  * @param currentSchema - Current schema (to avoid deleting the active database)
  */
-export const cleanupOldStateDbFiles = Effect.fn('@livestore/adapter-web:cleanupOldStateDbFiles')(
-  function* ({
-    vfs,
-    currentSchema,
-    opfsDirectory,
-  }: {
-    vfs: WebDatabaseMetadataOpfs['vfs']
-    currentSchema: LiveStoreSchema
-    opfsDirectory: string
-  }) {
-    // Only cleanup for auto migration strategy because:
-    // - Auto strategy: Creates new database files per schema change (e.g., state123.db, state456.db)
-    //   which accumulate over time and can exhaust OPFS file pool capacity
-    // - Manual strategy: Always reuses the same database file (statefixed.db) across schema changes,
-    //   so there are never multiple old files to clean up
-    if (currentSchema.state.sqlite.migrations.strategy === 'manual') {
-      yield* Effect.logDebug('Skipping state db cleanup - manual migration strategy uses fixed filename')
-      return
-    }
-
-    const isDev = isDevEnv()
-    const currentDbFileName = getStateDbFileName(currentSchema)
-    const currentPath = `/${currentDbFileName}`
-
-    const allPaths = yield* Effect.sync(() => vfs.getTrackedFilePaths())
-    const oldStateDbPaths = allPaths.filter(
-      (path) => path.startsWith('/state') && path.endsWith('.db') && path !== currentPath,
-    )
-
-    if (oldStateDbPaths.length === 0) {
-      yield* Effect.logDebug('State db cleanup completed: no old database files found')
-      return
-    }
+export const cleanupOldStateDbFiles: (options: {
+  vfs: WebDatabaseMetadataOpfs['vfs']
+  currentSchema: LiveStoreSchema
+  opfsDirectory: string
+}) => Effect.Effect<
+  void,
+  // All the following errors could actually happen:
+  | WebError.AbortError
+  | WebError.DataCloneError
+  | WebError.EvalError
+  | WebError.InvalidModificationError
+  | WebError.InvalidStateError
+  | WebError.NoModificationAllowedError
+  | WebError.NotAllowedError
+  | WebError.NotFoundError
+  | WebError.QuotaExceededError
+  | WebError.RangeError
+  | WebError.ReferenceError
+  | WebError.SecurityError
+  | WebError.TypeError
+  | WebError.TypeMismatchError
+  | WebError.URIError
+  | WebError.UnknownError
+  | Opfs.OpfsError
+  | PersistedSqliteError,
+  Opfs.Opfs
+> = Effect.fn('@livestore/adapter-web:cleanupOldStateDbFiles')(function* ({ vfs, currentSchema, opfsDirectory }) {
+  // Only cleanup for auto migration strategy because:
+  // - Auto strategy: Creates new database files per schema change (e.g., state123.db, state456.db)
+  //   which accumulate over time and can exhaust OPFS file pool capacity
+  // - Manual strategy: Always reuses the same database file (statefixed.db) across schema changes,
+  //   so there are never multiple old files to clean up
+  if (currentSchema.state.sqlite.migrations.strategy === 'manual') {
+    yield* Effect.logDebug('Skipping state db cleanup - manual migration strategy uses fixed filename')
+    return
+  }
 
-    yield* Effect.logDebug(`Found ${oldStateDbPaths.length} old state database file(s) to clean up`)
+  const isDev = isDevEnv()
+  const currentDbFileName = getStateDbFileName(currentSchema)
+  const currentPath = `/${currentDbFileName}`
 
-    let deletedCount = 0
-    const archivedFileNames: string[] = []
-    let archiveDirHandle: FileSystemDirectoryHandle | undefined
+  const allPaths = yield* Effect.sync(() => vfs.getTrackedFilePaths())
+  const oldStateDbPaths = allPaths.filter(
+    (path) => path.startsWith('/state') && path.endsWith('.db') && path !== currentPath,
+  )
 
-    for (const path of oldStateDbPaths) {
-      const fileName = path.startsWith('/') ? path.slice(1) : path
+  if (oldStateDbPaths.length === 0) {
+    yield* Effect.logDebug('No old database files found')
+    return
+  }
 
-      if (isDev) {
-        archiveDirHandle = yield* Effect.tryPromise({
-          try: () => OpfsUtils.getDirHandle(`${opfsDirectory}/archive`, { create: true }),
-          catch: (cause) => new ArchiveStateDbError({ message: 'Failed to ensure archive directory', cause }),
-        })
+  const absoluteArchiveDirName = `${opfsDirectory}/${ARCHIVE_DIR_NAME}`
+  if (isDev && !(yield* Opfs.exists(absoluteArchiveDirName))) yield* Opfs.makeDirectory(absoluteArchiveDirName)
 
-        const archivedFileName = yield* archiveStateDbFile({
-          vfs,
-          fileName,
-          archiveDirHandle,
-        })
+  for (const path of oldStateDbPaths) {
+    const fileName = path.startsWith('/') ? path.slice(1) : path
 
-        archivedFileNames.push(archivedFileName)
-      }
+    if (isDev) {
+      const archiveFileData = yield* vfs.readFilePayload(fileName)
 
-      const vfsResultCode = yield* Effect.try({
-        try: () => vfs.jDelete(fileName, 0),
-        catch: (cause) => new SqliteVfsError({ operation: 'jDelete', fileName, cause }),
-      })
+      const archiveFileName = `${Date.now()}-${fileName}`
 
-      // 0 indicates a successful result in SQLite.
-      // See https://www.sqlite.org/c3ref/c_abort.html
-      if (vfsResultCode !== 0) {
-        return yield* new SqliteVfsError({
-          operation: 'jDelete',
-          fileName,
-          vfsResultCode,
-        })
-      }
-
-      deletedCount++
-      yield* Effect.logDebug(`Successfully deleted old state database file: ${fileName}`)
+      yield* Opfs.writeFile(`${opfsDirectory}/archive/${archiveFileName}`, new Uint8Array(archiveFileData))
     }
 
-    if (isDev && archiveDirHandle !== undefined) {
-      const pruneResult = yield* pruneArchiveDir({
-        archiveDirHandle,
-        keep: MAX_ARCHIVED_STATE_DBS_IN_DEV,
+    const vfsResultCode = yield* Effect.try({
+      try: () => vfs.jDelete(fileName, 0),
+      catch: (cause) =>
+        new PersistedSqliteError({ message: `Failed to delete old state database file: ${fileName}`, cause }),
+    })
+
+    // 0 indicates a successful result in SQLite.
+    // See https://www.sqlite.org/c3ref/c_abort.html
+    if (vfsResultCode !== 0) {
+      return yield* new PersistedSqliteError({
+        message: `Failed to delete old state database file: ${fileName}, got result code: ${vfsResultCode}`,
       })
-
-      yield* Effect.logDebug(
-        `State db cleanup completed: archived ${archivedFileNames.length} file(s); removed ${deletedCount} old database file(s) from active pool; archive retained ${pruneResult.retained.length} file(s)`,
-      )
-    } else {
-      yield* Effect.logDebug(`State db cleanup completed: removed ${deletedCount} old database file(s)`)
     }
-  },
-  Effect.mapError(
-    (error) =>
-      new PersistedSqliteError({
-        message: 'Failed to clean up old state database file(s)',
-        cause: error,
-      }),
-  ),
-)
 
-const archiveStateDbFile = Effect.fn('@livestore/adapter-web:archiveStateDbFile')(function* ({
-  vfs,
-  fileName,
-  archiveDirHandle,
-}: {
-  vfs: WebDatabaseMetadataOpfs['vfs']
-  fileName: string
-  archiveDirHandle: FileSystemDirectoryHandle
-}) {
-  const stateDbBuffer = vfs.readFilePayload(fileName)
-
-  const archiveFileName = `${Date.now()}-${fileName}`
-
-  const archiveFileHandle = yield* Effect.tryPromise({
-    try: () => archiveDirHandle.getFileHandle(archiveFileName, { create: true }),
-    catch: (cause) =>
-      new ArchiveStateDbError({
-        message: 'Failed to open archive file handle',
-        fileName: archiveFileName,
-        cause,
-      }),
-  })
-
-  const archiveFileAccessHandle = yield* Effect.acquireRelease(
-    Effect.tryPromise({
-      try: () => archiveFileHandle.createSyncAccessHandle(),
-      catch: (cause) =>
-        new ArchiveStateDbError({
-          message: 'Failed to create sync access handle for archived file',
-          fileName: archiveFileName,
-          cause,
-        }),
-    }),
-    (handle) => Effect.sync(() => handle.close()).pipe(Effect.ignoreLogged),
-  )
+    yield* Effect.logDebug(`Deleted old state database file: ${fileName}`)
+  }
 
-  yield* Effect.try({
-    try: () => {
-      archiveFileAccessHandle.write(stateDbBuffer)
-      archiveFileAccessHandle.flush()
-    },
-    catch: (cause) =>
-      new ArchiveStateDbError({
-        message: 'Failed to write archived state database',
-        fileName: archiveFileName,
-        cause,
-      }),
-  })
-
-  return archiveFileName
-}, Effect.scoped)
-
-const pruneArchiveDir = Effect.fn('@livestore/adapter-web:pruneArchiveDir')(function* ({
-  archiveDirHandle,
+  if (isDev) {
+    yield* pruneArchiveDirectory({
+      archiveDirectory: absoluteArchiveDirName,
+      keep: MAX_ARCHIVED_STATE_DBS_IN_DEV,
+    })
+  }
+})
+
+const pruneArchiveDirectory = Effect.fn('@livestore/adapter-web:pruneArchiveDirectory')(function* ({
+  archiveDirectory,
   keep,
 }: {
-  archiveDirHandle: FileSystemDirectoryHandle
+  archiveDirectory: string
   keep: number
 }) {
-  const files = yield* Effect.tryPromise({
-    try: async () => {
-      const result: { name: string; lastModified: number }[] = []
-
-      for await (const entry of archiveDirHandle.values()) {
-        if (entry.kind !== 'file') continue
-        const fileHandle = await archiveDirHandle.getFileHandle(entry.name)
-        const file = await fileHandle.getFile()
-        result.push({ name: entry.name, lastModified: file.lastModified })
-      }
-
-      return result.sort((a, b) => b.lastModified - a.lastModified)
-    },
-    catch: (cause) => new ArchiveStateDbError({ message: 'Failed to enumerate archived state databases', cause }),
-  })
-
-  const retained = files.slice(0, keep)
-  const toDelete = files.slice(keep)
-
-  yield* Effect.forEach(toDelete, ({ name }) =>
-    Effect.tryPromise({
-      try: () => archiveDirHandle.removeEntry(name),
-      catch: (cause) =>
-        new ArchiveStateDbError({
-          message: 'Failed to delete archived state database',
-          fileName: name,
-          cause,
-        }),
-    }),
+  const archiveDirHandle = yield* Opfs.getDirectoryHandleByPath(archiveDirectory)
+  const handlesStream = yield* Opfs.Opfs.values(archiveDirHandle)
+  const filesWithMetadata = yield* handlesStream.pipe(
+    Stream.filter((handle): handle is FileSystemFileHandle => handle.kind === 'file'),
+    Stream.mapEffect((fileHandle) => Opfs.getMetadata(fileHandle)),
+    Stream.runCollect,
+  )
+  const filesToDelete = filesWithMetadata.pipe(
+    Chunk.sort(Order.mapInput(Order.number, (entry: { lastModified: number }) => entry.lastModified)),
+    Chunk.drop(keep),
+    Chunk.toReadonlyArray,
   )
 
-  return {
-    retained,
-    deleted: toDelete,
-  }
-})
+  if (filesToDelete.length === 0) return
 
-export class ArchiveStateDbError extends Schema.TaggedError<ArchiveStateDbError>()('ArchiveStateDbError', {
-  message: Schema.String,
-  fileName: Schema.optional(Schema.String),
-  cause: Schema.Defect,
-}) {}
+  yield* Effect.forEach(filesToDelete, ({ name }) => Opfs.Opfs.removeEntry(archiveDirHandle, name))
 
-export class SqliteVfsError extends Schema.TaggedError<SqliteVfsError>()('SqliteVfsError', {
-  operation: Schema.String,
-  fileName: Schema.String,
-  vfsResultCode: Schema.optional(Schema.Number),
-  cause: Schema.optional(Schema.Defect),
-}) {}
+  yield* Effect.logDebug(`Pruned ${filesToDelete.length} old database file(s) from archive directory`)
+})

package/src/web-worker/common/shutdown-channel.ts

@@ -1,8 +1,15 @@
 import { ShutdownChannel } from '@livestore/common/leader-thread'
-import { WebChannel } from '@livestore/utils/effect'
+import type { Effect, Scope, WebChannel } from '@livestore/utils/effect'
+import { WebChannelBrowser } from '@livestore/utils/effect/browser'
 
-export const makeShutdownChannel = (storeId: string) =>
-  WebChannel.broadcastChannel({
+export const makeShutdownChannel = (
+  storeId: string,
+): Effect.Effect<
+  WebChannel.WebChannel<typeof ShutdownChannel.All.Type, typeof ShutdownChannel.All.Type>,
+  never,
+  Scope.Scope
+> =>
+  WebChannelBrowser.broadcastChannel({
     channelName: `livestore.shutdown.${storeId}`,
     schema: ShutdownChannel.All,
   })

package/src/web-worker/common/worker-disconnect-channel.ts

@@ -1,10 +1,17 @@
-import { Schema, WebChannel } from '@livestore/utils/effect'
+import { type Effect, Schema, type Scope, type WebChannel } from '@livestore/utils/effect'
+import { WebChannelBrowser } from '@livestore/utils/effect/browser'
 
 export class DedicatedWorkerDisconnectBroadcast extends Schema.TaggedStruct('DedicatedWorkerDisconnectBroadcast', {}) {}
 
 /** Used across workers for leader election purposes */
-export const makeWorkerDisconnectChannel = (storeId: string) =>
-  WebChannel.broadcastChannel({
+export const makeWorkerDisconnectChannel = (
+  storeId: string,
+): Effect.Effect<
+  WebChannel.WebChannel<typeof DedicatedWorkerDisconnectBroadcast.Type, typeof DedicatedWorkerDisconnectBroadcast.Type>,
+  never,
+  Scope.Scope
+> =>
+  WebChannelBrowser.broadcastChannel({
     channelName: `livestore.worker-disconnect.${storeId}`,
     schema: DedicatedWorkerDisconnectBroadcast,
   })