@livestore/sqlite-wasm 0.4.0-dev.22 → 0.4.0-dev.23

package/src/cf/CloudflareDurableObjectVFS.ts

@@ -0,0 +1,325 @@
+import type { CfTypes } from '@livestore/common-cf'
+import * as VFS from '@livestore/wa-sqlite/src/VFS.js'
+
+import { FacadeVFS } from '../FacadeVFS.ts'
+
+// Page size for SQL-based storage. Matches dbState page size (PRAGMA page_size=8192)
+// so each SQLite page write maps to exactly one vfs_pages row write — no read-merge-write.
+export const PAGE_SIZE = 8 * 1024 // 8 KiB
+
+/**
+ * The {@link CloudflareDurableObjectVFS} VFS assumes SQLite is configured with these pragmas.
+ * These pragmas are required both for correctness and for minimizing SQLite writes
+ * to the underlying storage.
+ */
+export const REQUIRED_PRAGMAS = [
+  // Must match the fixed VFS page size so each SQLite page maps to one vfs_pages row.
+  `page_size=${PAGE_SIZE}`,
+  // The rollback journal is the largest source of VFS writes. Keeping it
+  // in WASM memory avoids writing journal pages through the VFS entirely.
+  // This is acceptable because the state database is rebuildable from the
+  // eventlog in case of a crash. We still, however, need the journal for
+  // transaction rollbacks.
+  'journal_mode=MEMORY',
+  // Skips jSync VFS calls (already a no-op, but avoids the dispatch).
+  'synchronous=OFF',
+  // A Durable Object is single-threaded with a single connection, so shared
+  // locking is unnecessary. Exclusive mode skips per-transaction lock/unlock
+  // VFS calls and hot-journal jAccess checks.
+  'locking_mode=EXCLUSIVE',
+  // Temp tables and indices stay in WASM memory, preventing temp-file VFS writes.
+  'temp_store=MEMORY',
+  // Keeps all dirty pages in the WASM page cache until commit. Without this,
+  // SQLite may spill pages to the VFS mid-transaction, and if those pages are
+  // dirtied again before commit, the same page gets written twice.
+  'cache_spill=OFF',
+]
+
+/**
+ * wa-sqlite VFS for the LiveStore **state database** (dbState), backed by
+ * {@link https://developers.cloudflare.com/durable-objects/api/sql-storage/ | SQLite in Durable Objects}.
+ *
+ * ## Why wa-sqlite on top of SQLite in Durable Objects
+ *
+ * LiveStore's state database depends on SQLite APIs that SQLite in
+ * Durable Objects does not expose. This VFS persists wa-sqlite's pages as
+ * rows in the DO's SQLite storage, giving the state database durable
+ * persistence while retaining full access to the SQLite API.
+ *
+ * ## Write Optimization
+ *
+ * Every VFS write becomes a (billable) row write in the DO's SQLite. To
+ * reduce costs, this VFS assumes a wa-sqlite configured with {@link REQUIRED_PRAGMAS}
+ * for minimizing writes.
+ *
+ * ## File Identity
+ *
+ * LiveStore currently only persists the main database file through this VFS,
+ * but pages still stay keyed by file path, so schema-hashed filenames open
+ * isolated databases across process restarts.
+ */
+export class CloudflareDurableObjectVFS extends FacadeVFS {
+  #sql: CfTypes.SqlStorage
+  /**
+   * Tracks the path and open flags for each SQLite file handle.
+   *
+   * @remarks
+   *
+   * After `jOpen`, SQLite calls the VFS with `fileId` for reads, writes,
+   * truncates, size checks, and close, so we need this in-memory map to get
+   * back to the persisted `file_path` key and honor handle-specific flags
+   * such as `SQLITE_OPEN_DELETEONCLOSE`.
+   */
+  #openFiles = new Map<number, { path: string; flags: number }>()
+
+  /**
+   * @param name - VFS name registered with wa-sqlite (must be unique per database).
+   * @param sql - The Durable Object's {@link CfTypes.SqlStorage} handle.
+   * @param module - The wa-sqlite WASM module instance.
+   */
+  constructor(name: string, sql: CfTypes.SqlStorage, module: any) {
+    super(name, module)
+    this.#sql = sql
+    this.#sql.exec(
+      `CREATE TABLE IF NOT EXISTS vfs_pages (
+        file_path TEXT NOT NULL,
+        page_no INTEGER NOT NULL,
+        page_data BLOB NOT NULL,
+        PRIMARY KEY (file_path, page_no)
+      )`,
+    )
+  }
+
+  /**
+   * Accepts any open request unconditionally and records which path each fileId refers to.
+   *
+   * @remarks
+   *
+   * SQLite's fileId is only an in-memory open-handle identifier. Persisted
+   * data must stay keyed by filename so schema-hashed state DB filenames
+   * remain isolated from each other across restarts.
+   */
+  override jOpen(path: string | null, fileId: number, flags: number, pOutFlags: DataView): number {
+    const resolvedPath = this.#resolveOpenPath(path)
+    this.#openFiles.set(fileId, { path: resolvedPath, flags })
+    pOutFlags.setInt32(0, flags, true)
+    return VFS.SQLITE_OK
+  }
+
+  override jClose(fileId: number): number {
+    try {
+      const openFile = this.#openFiles.get(fileId)
+      if (openFile === undefined) return VFS.SQLITE_OK
+
+      this.#openFiles.delete(fileId)
+
+      if ((openFile.flags & VFS.SQLITE_OPEN_DELETEONCLOSE) !== 0) {
+        this.#deleteFilePages(openFile.path)
+      }
+
+      return VFS.SQLITE_OK
+    } catch (error) {
+      console.error('jClose error:', error)
+      return VFS.SQLITE_IOERR_CLOSE
+    }
+  }
+
+  /**
+   * Reads a single page from `vfs_pages` and copies the requested byte range
+   * into {@link buffer}.
+   *
+   * @remarks
+   *
+   * Missing pages are zero-filled and still return `SQLITE_OK` (not `SQLITE_IOERR_SHORT_READ`)
+   * because wa-sqlite expects this during initial database creation.
+   */
+  override jRead(fileId: number, buffer: Uint8Array, offset: number): number {
+    try {
+      const { path } = this.#getOpenFile(fileId)
+      const pageNo = Math.floor(offset / PAGE_SIZE)
+      const cursor = this.#sql.exec<{ page_data: ArrayBuffer }>(
+        'SELECT page_data FROM vfs_pages WHERE file_path = ? AND page_no = ?',
+        path,
+        pageNo,
+      )
+
+      const rows = cursor.toArray()
+
+      if (rows.length === 0) {
+        buffer.fill(0)
+        return VFS.SQLITE_OK
+      }
+
+      const src = new Uint8Array(rows[0]!.page_data)
+      const pageOffset = offset % PAGE_SIZE
+      const available = src.byteLength - pageOffset
+
+      if (available >= buffer.byteLength) {
+        buffer.set(src.subarray(pageOffset, pageOffset + buffer.byteLength))
+        return VFS.SQLITE_OK
+      }
+
+      buffer.set(src.subarray(pageOffset))
+      buffer.fill(0, available)
+      return VFS.SQLITE_OK
+    } catch (error) {
+      console.error('jRead error:', error)
+      return VFS.SQLITE_IOERR
+    }
+  }
+
+  /**
+   * Writes a single page to `vfs_pages`.
+   *
+   * @remarks
+   *
+   * The VFS only supports canonical SQLite page writes. Rejecting any other
+   * shape turns page-size mismatches into a hard failure instead of silently
+   * aliasing multiple SQLite pages onto the same `vfs_pages` row.
+   *
+   * The data is copied out of the WASM heap via `data.slice()` because
+   * Cloudflare's SQL storage cannot persist the {@link FacadeVFS}
+   * Proxy-wrapped buffer across DO restarts.
+   */
+  override jWrite(fileId: number, data: Uint8Array, offset: number): number {
+    try {
+      const { path } = this.#getOpenFile(fileId)
+      this.#assertCanonicalPageWrite(data, offset)
+      const pageNo = Math.floor(offset / PAGE_SIZE)
+      // data.slice() copies out of the WASM heap Proxy so CF SQL storage can persist the BLOB correctly.
+      this.#sql.exec(
+        'INSERT OR REPLACE INTO vfs_pages (file_path, page_no, page_data) VALUES (?, ?, ?)',
+        path,
+        pageNo,
+        data.slice(),
+      )
+      return VFS.SQLITE_OK
+    } catch (error) {
+      console.error('jWrite error:', error)
+      return VFS.SQLITE_IOERR
+    }
+  }
+
+  /** Deletes all pages beyond the new file size boundary. */
+  override jTruncate(fileId: number, size: number): number {
+    try {
+      const { path } = this.#getOpenFile(fileId)
+      const lastPageNo = Math.ceil(size / PAGE_SIZE)
+      this.#sql.exec('DELETE FROM vfs_pages WHERE file_path = ? AND page_no >= ?', path, lastPageNo)
+      return VFS.SQLITE_OK
+    } catch (error) {
+      console.error('jTruncate error:', error)
+      return VFS.SQLITE_IOERR
+    }
+  }
+
+  /**
+   * Derives file size from `MAX(page_no)`.
+   *
+   * @remarks
+   *
+   * Possible because all writes are page-aligned (page size matches `PRAGMA page_size`).
+   */
+  override jFileSize(fileId: number, pSize64: DataView): number {
+    try {
+      const { path } = this.#getOpenFile(fileId)
+      const row = this.#sql.exec<{ max_page: number | null }>(
+        'SELECT MAX(page_no) AS max_page FROM vfs_pages WHERE file_path = ?',
+        path,
+      ).one()
+      const fileSize = row.max_page === null ? 0 : (row.max_page + 1) * PAGE_SIZE
+      pSize64.setBigInt64(0, BigInt(fileSize), true)
+      return VFS.SQLITE_OK
+    } catch (error) {
+      console.error('jFileSize error:', error)
+      return VFS.SQLITE_IOERR
+    }
+  }
+
+  /** Wipes all pages for the requested file path. */
+  override jDelete(path: string, _syncDir: number): number {
+    try {
+      this.#deleteFilePages(this.#getPath(path))
+      return VFS.SQLITE_OK
+    } catch (error) {
+      console.error('jDelete error:', error)
+      return VFS.SQLITE_IOERR
+    }
+  }
+
+  /** Always reports "not found".
+   *
+   * @remarks
+   *
+   * With `locking_mode=EXCLUSIVE` and `journal_mode=MEMORY`, the only `jAccess` call SQLite makes is for
+   * hot-journal detection, which does not apply. Returning 1 (found) would
+   * trigger hot-journal recovery writes on every cold start.
+   */
+  override jAccess(_path: string, _flags: number, pResOut: DataView): number {
+    pResOut.setInt32(0, 0, true)
+    return VFS.SQLITE_OK
+  }
+
+  /** Returns page count and total stored bytes for diagnostics. */
+  getStats(): {
+    pageSize: number
+    totalPages: number
+    totalStoredBytes: number
+  } {
+    try {
+      const cursor = this.#sql.exec<{ total_pages: number; total_bytes: number }>(
+        'SELECT COUNT(*) AS total_pages, COALESCE(SUM(LENGTH(page_data)), 0) AS total_bytes FROM vfs_pages',
+      )
+      const stats = cursor.one()
+
+      return {
+        pageSize: PAGE_SIZE,
+        totalPages: stats.total_pages,
+        totalStoredBytes: stats.total_bytes,
+      }
+    } catch {
+      return {
+        pageSize: PAGE_SIZE,
+        totalPages: 0,
+        totalStoredBytes: 0,
+      }
+    }
+  }
+
+  /**
+   * Convert a bare filename, path, or URL to a UNIX-style path.
+   */
+  #getPath(nameOrURL: string | URL): string {
+    const url = typeof nameOrURL === 'string' ? new URL(nameOrURL, 'file://localhost/') : nameOrURL
+    return url.pathname
+  }
+
+  #resolveOpenPath(path: string | null): string {
+    const pathOrHandleId = path !== null && path !== '' ? path : Math.random().toString(36).slice(2)
+    return this.#getPath(pathOrHandleId)
+  }
+
+  #getOpenFile(fileId: number): { path: string; flags: number } {
+    const openFile = this.#openFiles.get(fileId)
+    if (openFile === undefined) throw new Error(`Unknown fileId ${fileId}`)
+    return openFile
+  }
+
+  #assertCanonicalPageWrite(data: Uint8Array, offset: number) {
+    if (offset % PAGE_SIZE !== 0) {
+      throw new Error(
+        `CloudflareDurableObjectVFS expected page-aligned writes, got offset=${offset} for pageSize=${PAGE_SIZE}`,
+      )
+    }
+
+    if (data.byteLength !== PAGE_SIZE) {
+      throw new Error(
+        `CloudflareDurableObjectVFS expected single-page writes of ${PAGE_SIZE} bytes, got ${data.byteLength}. Check that SQLite PRAGMA page_size matches the VFS page size.`,
+      )
+    }
+  }
+
+  #deleteFilePages(path: string) {
+    this.#sql.exec('DELETE FROM vfs_pages WHERE file_path = ?', path)
+  }
+}

package/src/cf/CloudflareWorkerVFS.ts

@@ -1,5 +1,6 @@
 import type { CfTypes } from '@livestore/common-cf'
 import * as VFS from '@livestore/wa-sqlite/src/VFS.js'
+
 import { FacadeVFS } from '../FacadeVFS.ts'
 
 const SECTOR_SIZE = 4096
@@ -106,7 +107,7 @@ export class CloudflareWorkerVFS extends FacadeVFS {
       }
     }
 
-    if (oldestKey) {
+    if (oldestKey !== '') {
       this.#chunkCache.delete(oldestKey)
     }
   }
@@ -114,7 +115,7 @@ export class CloudflareWorkerVFS extends FacadeVFS {
   #getCachedChunk(path: string, chunkIndex: number): Uint8Array | undefined {
     const key = this.#getCacheKey(path, chunkIndex)
     const entry = this.#chunkCache.get(key)
-    if (entry) {
+    if (entry !== undefined) {
       entry.lastAccessed = Date.now()
       return entry.data
     }
@@ -142,7 +143,7 @@ export class CloudflareWorkerVFS extends FacadeVFS {
     const key = `write:${path}`
 
     // Cancel any pending write for this path
-    if (this.#writePromises.has(key)) {
+    if (this.#writePromises.has(key) === true) {
       this.#pendingWrites.delete(key)
     }
 
@@ -163,10 +164,10 @@ export class CloudflareWorkerVFS extends FacadeVFS {
 
   async #loadMetadata(path: string): Promise<FileMetadata | undefined> {
     const cached = this.#metadataCache.get(path)
-    if (cached) return cached
+    if (cached !== undefined) return cached
 
     const metadata = await this.#storage.get<FileMetadata>(this.#getMetadataKey(path))
-    if (metadata) {
+    if (metadata !== undefined) {
       this.#metadataCache.set(path, metadata)
     }
     return metadata
@@ -182,10 +183,10 @@ export class CloudflareWorkerVFS extends FacadeVFS {
 
   async #loadChunk(path: string, chunkIndex: number): Promise<Uint8Array | undefined> {
     const cached = this.#getCachedChunk(path, chunkIndex)
-    if (cached) return cached
+    if (cached !== undefined) return cached
 
     const chunk = await this.#storage.get<Uint8Array>(this.#getChunkKey(path, chunkIndex))
-    if (chunk) {
+    if (chunk !== undefined) {
       this.#setCachedChunk(path, chunkIndex, chunk)
     }
     return chunk
@@ -198,7 +199,7 @@ export class CloudflareWorkerVFS extends FacadeVFS {
 
   async #deleteFile(path: string): Promise<void> {
     const metadata = await this.#loadMetadata(path)
-    if (!metadata) return
+    if (metadata == null) return
 
     // Delete all chunks and metadata atomically
     const keysToDelete = [this.#getMetadataKey(path)]
@@ -220,12 +221,13 @@ export class CloudflareWorkerVFS extends FacadeVFS {
     await this.#updateFileIndex()
   }
 
-  jOpen(zName: string, fileId: number, flags: number, pOutFlags: DataView): number {
+  override jOpen(zName: string, fileId: number, flags: number, pOutFlags: DataView): number {
     try {
-      const path = zName ? this.#getPath(zName) : Math.random().toString(36)
+      const name = zName as unknown
+      const path = typeof name === 'string' && name !== '' ? this.#getPath(name) : Math.random().toString(36)
       const metadata = this.#metadataCache.get(path)
 
-      if (!metadata && flags & VFS.SQLITE_OPEN_CREATE) {
+      if (metadata == null && (flags & VFS.SQLITE_OPEN_CREATE) !== 0) {
         // Create new file
         if (this.#activeFiles.size >= this.#maxFiles) {
           throw new Error('cannot create file: capacity exceeded')
@@ -246,7 +248,7 @@ export class CloudflareWorkerVFS extends FacadeVFS {
         this.#scheduleWrite(path, () => this.#saveMetadata(path, newMetadata))
       }
 
-      if (!this.#metadataCache.has(path)) {
+      if (this.#metadataCache.has(path) === false) {
         throw new Error('file not found')
       }
 
@@ -265,11 +267,11 @@ export class CloudflareWorkerVFS extends FacadeVFS {
     }
   }
 
-  jClose(fileId: number): number {
+  override jClose(fileId: number): number {
     const handle = this.#openFiles.get(fileId)
-    if (handle) {
+    if (handle !== undefined) {
       this.#openFiles.delete(fileId)
-      if (handle.flags & VFS.SQLITE_OPEN_DELETEONCLOSE) {
+      if ((handle.flags & VFS.SQLITE_OPEN_DELETEONCLOSE) !== 0) {
         // Schedule async delete
         this.#scheduleWrite(handle.path, () => this.#deleteFile(handle.path))
       }
@@ -277,10 +279,10 @@ export class CloudflareWorkerVFS extends FacadeVFS {
     return VFS.SQLITE_OK
   }
 
-  jRead(fileId: number, pData: Uint8Array, iOffset: number): number {
+  override jRead(fileId: number, pData: Uint8Array, iOffset: number): number {
     try {
       const handle = this.#openFiles.get(fileId)
-      if (!handle) return VFS.SQLITE_IOERR
+      if (handle == null) return VFS.SQLITE_IOERR
 
       const fileSize = handle.metadata.size
       const requestedBytes = pData.byteLength
@@ -303,7 +305,7 @@ export class CloudflareWorkerVFS extends FacadeVFS {
 
       for (let chunkIndex = startChunk; chunkIndex <= endChunk; chunkIndex++) {
         const chunk = this.#getCachedChunk(handle.path, chunkIndex)
-        if (!chunk) {
+        if (chunk == null) {
           // Cache miss - this is a problem for synchronous operation
           // We should have preloaded chunks during initialization
           console.warn(`Cache miss for chunk ${chunkIndex} of ${handle.path}`)
@@ -338,10 +340,10 @@ export class CloudflareWorkerVFS extends FacadeVFS {
     }
   }
 
-  jWrite(fileId: number, pData: Uint8Array, iOffset: number): number {
+  override jWrite(fileId: number, pData: Uint8Array, iOffset: number): number {
     try {
       const handle = this.#openFiles.get(fileId)
-      if (!handle) return VFS.SQLITE_IOERR
+      if (handle == null) return VFS.SQLITE_IOERR
 
       const bytesToWrite = pData.byteLength
       const startChunk = Math.floor(iOffset / CHUNK_SIZE)
@@ -356,7 +358,7 @@ export class CloudflareWorkerVFS extends FacadeVFS {
         const writeEnd = Math.min(CHUNK_SIZE, iOffset + bytesToWrite - chunkOffset)
 
         let chunk = this.#getCachedChunk(handle.path, chunkIndex)
-        if (!chunk) {
+        if (chunk == null) {
           // Create new chunk
           chunk = new Uint8Array(CHUNK_SIZE)
         } else {
@@ -399,10 +401,10 @@ export class CloudflareWorkerVFS extends FacadeVFS {
     }
   }
 
-  jTruncate(fileId: number, iSize: number): number {
+  override jTruncate(fileId: number, iSize: number): number {
     try {
       const handle = this.#openFiles.get(fileId)
-      if (!handle) return VFS.SQLITE_IOERR
+      if (handle == null) return VFS.SQLITE_IOERR
 
       // const oldSize = handle.metadata.size
       const newChunkCount = Math.ceil(iSize / CHUNK_SIZE)
@@ -435,7 +437,7 @@ export class CloudflareWorkerVFS extends FacadeVFS {
 
         if (lastChunkSize < CHUNK_SIZE) {
           const lastChunk = this.#getCachedChunk(handle.path, lastChunkIndex)
-          if (lastChunk) {
+          if (lastChunk !== undefined) {
             const truncatedChunk = new Uint8Array(CHUNK_SIZE)
             truncatedChunk.set(lastChunk.subarray(0, lastChunkSize))
             this.#setCachedChunk(handle.path, lastChunkIndex, truncatedChunk)
@@ -454,10 +456,10 @@ export class CloudflareWorkerVFS extends FacadeVFS {
     }
   }
 
-  jSync(fileId: number, _flags: number): number {
+  override jSync(fileId: number, _flags: number): number {
     try {
       const handle = this.#openFiles.get(fileId)
-      if (!handle) return VFS.SQLITE_IOERR
+      if (handle == null) return VFS.SQLITE_IOERR
 
       // Force sync all pending writes for this file
       // Note: DurableObjectStorage operations are already synchronous
@@ -469,10 +471,10 @@ export class CloudflareWorkerVFS extends FacadeVFS {
     }
   }
 
-  jFileSize(fileId: number, pSize64: DataView): number {
+  override jFileSize(fileId: number, pSize64: DataView): number {
     try {
       const handle = this.#openFiles.get(fileId)
-      if (!handle) return VFS.SQLITE_IOERR
+      if (handle == null) return VFS.SQLITE_IOERR
 
       pSize64.setBigInt64(0, BigInt(handle.metadata.size), true)
       return VFS.SQLITE_OK
@@ -482,19 +484,19 @@ export class CloudflareWorkerVFS extends FacadeVFS {
     }
   }
 
-  jSectorSize(_fileId: number): number {
+  override jSectorSize(_fileId: number): number {
     return SECTOR_SIZE
   }
 
-  jDeviceCharacteristics(_fileId: number): number {
+  override jDeviceCharacteristics(_fileId: number): number {
     return VFS.SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN
   }
 
-  jAccess(zName: string, _flags: number, pResOut: DataView): number {
+  override jAccess(zName: string, _flags: number, pResOut: DataView): number {
     try {
       const path = this.#getPath(zName)
       const exists = this.#activeFiles.has(path)
-      pResOut.setInt32(0, exists ? 1 : 0, true)
+      pResOut.setInt32(0, exists === true ? 1 : 0, true)
       return VFS.SQLITE_OK
     } catch (e: any) {
       console.error('jAccess error:', e.message)
@@ -502,7 +504,7 @@ export class CloudflareWorkerVFS extends FacadeVFS {
     }
   }
 
-  jDelete(zName: string, _syncDir: number): number {
+  override jDelete(zName: string, _syncDir: number): number {
     try {
       const path = this.#getPath(zName)
 
@@ -526,7 +528,7 @@ export class CloudflareWorkerVFS extends FacadeVFS {
   }
 
   async isReady() {
-    if (!this.#initialized) {
+    if (this.#initialized === false) {
       await this.#initializeStorage()
       this.#initialized = true
     }
@@ -536,7 +538,7 @@ export class CloudflareWorkerVFS extends FacadeVFS {
   async #initializeStorage() {
     // Load list of existing files
     const fileList = await this.#storage.get<string[]>('index:files')
-    if (fileList) {
+    if (fileList !== undefined) {
       for (const path of fileList) {
         this.#activeFiles.add(path)
         // Preload metadata for all files
@@ -557,8 +559,8 @@ export class CloudflareWorkerVFS extends FacadeVFS {
     for (const path of this.#activeFiles) {
       const metadata = this.#metadataCache.get(path)
       if (
-        metadata &&
-        (metadata.flags & VFS.SQLITE_OPEN_DELETEONCLOSE || (metadata.flags & PERSISTENT_FILE_TYPES) === 0)
+        metadata !== undefined &&
+        ((metadata.flags & VFS.SQLITE_OPEN_DELETEONCLOSE) !== 0 || (metadata.flags & PERSISTENT_FILE_TYPES) === 0)
       ) {
         console.warn(`Cleaning up temporary file: ${path}`)
         await this.#deleteFile(path)
@@ -615,13 +617,13 @@ export class CloudflareWorkerVFS extends FacadeVFS {
    */
   async #preloadChunks(path: string, startChunk: number, count = 3) {
     const metadata = this.#metadataCache.get(path)
-    if (!metadata) return
+    if (metadata == null) return
 
     const endChunk = Math.min(startChunk + count, metadata.chunkCount)
     const promises: Promise<void>[] = []
 
     for (let i = startChunk; i < endChunk; i++) {
-      if (!this.#getCachedChunk(path, i)) {
+      if (this.#getCachedChunk(path, i) == null) {
         promises.push(this.#loadChunk(path, i).then(() => {}))
       }
     }

package/src/cf/README.md

@@ -37,7 +37,7 @@ CREATE INDEX IF NOT EXISTS idx_vfs_blocks_range ON vfs_blocks(file_path, block_i
 CREATE INDEX IF NOT EXISTS idx_vfs_files_modified ON vfs_files(modified_at);
 
 -- Trigger to update modified_at timestamp when file size changes
-CREATE TRIGGER IF NOT EXISTS trg_vfs_files_update_modified 
+CREATE TRIGGER IF NOT EXISTS trg_vfs_files_update_modified
   AFTER UPDATE OF file_size ON vfs_files
   BEGIN
     UPDATE vfs_files SET modified_at = unixepoch() WHERE file_path = NEW.file_path;
@@ -45,7 +45,7 @@ CREATE TRIGGER IF NOT EXISTS trg_vfs_files_update_modified
 
 -- View for file statistics (useful for debugging and monitoring)
 CREATE VIEW IF NOT EXISTS vfs_file_stats AS
-SELECT 
+SELECT
   f.file_path,
   f.file_size,
   f.flags,
@@ -57,4 +57,4 @@ SELECT
 FROM vfs_files f
 LEFT JOIN vfs_blocks b ON f.file_path = b.file_path
 GROUP BY f.file_path, f.file_size, f.flags, f.created_at, f.modified_at;
-```
+```

package/src/cf/mod.ts

@@ -5,12 +5,16 @@ import type { CfTypes } from '@livestore/common-cf'
 import { Effect } from '@livestore/utils/effect'
 import type * as WaSqlite from '@livestore/wa-sqlite'
 import type { MemoryVFS } from '@livestore/wa-sqlite/src/examples/MemoryVFS.js'
+
 import { makeInMemoryDb } from '../in-memory-vfs.ts'
 import { makeSqliteDb } from '../make-sqlite-db.ts'
-import { CloudflareSqlVFS } from './CloudflareSqlVFS.ts'
+import { CloudflareDurableObjectVFS } from './CloudflareDurableObjectVFS.ts'
 
-export { BlockManager } from './BlockManager.ts'
-export { CloudflareSqlVFS } from './CloudflareSqlVFS.ts'
+export {
+  CloudflareDurableObjectVFS,
+  PAGE_SIZE as CF_SQL_VFS_PAGE_SIZE,
+  REQUIRED_PRAGMAS as CF_SQL_VFS_REQUIRED_PRAGMAS,
+} from './CloudflareDurableObjectVFS.ts'
 export { CloudflareWorkerVFS } from './CloudflareWorkerVFS.ts'
 
 export type CloudflareDatabaseMetadataInMemory = {
@@ -24,8 +28,7 @@ export type CloudflareDatabaseMetadataInMemory = {
 
 export type CloudflareDatabaseMetadataFs = {
   _tag: 'storage'
-  // vfs: CloudflareWorkerVFS
-  vfs: CloudflareSqlVFS
+  vfs: CloudflareDurableObjectVFS
   dbPointer: number
   persistenceInfo: PersistenceInfo
   deleteDb: () => void
@@ -115,18 +118,10 @@ const makeCloudflareFsDb = ({
     // If this is becoming a problem, we can use a hashed version of the directory name
     const vfsName = `cf-do-sqlite-${fileName}`
     if (sqlite3.vfs_registered.has(vfsName) === false) {
-      // TODO refactor with Effect FileSystem instead of using `node:fs` directly inside of CloudflareWorkerVFS
-      // const nodeFsVfs = new CloudflareWorkerVFS(vfsName, storage, (sqlite3 as any).module)
-      const nodeFsVfs = new CloudflareSqlVFS(vfsName, storage.sql, (sqlite3 as any).module)
-
-      // Initialize the VFS schema before registering it
-      const isReady = yield* Effect.promise(() => nodeFsVfs.isReady())
-      if (!isReady) {
-        throw new Error(`Failed to initialize CloudflareSqlVFS for ${vfsName}`)
-      }
+      const vfs = new CloudflareDurableObjectVFS(vfsName, storage.sql, (sqlite3 as any).module)
 
       // @ts-expect-error TODO fix types
-      sqlite3.vfs_register(nodeFsVfs, false)
+      sqlite3.vfs_register(vfs, false)
     }
 
     // yield* fs.makeDirectory(directory, { recursive: true })