@componentor/fs 1.2.3 → 1.2.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@componentor/fs",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "description": "A blazing-fast, Node.js-compatible filesystem for the browser using OPFS",
   "type": "module",
   "main": "./dist/index.js",

package/src/handle-manager.ts

@@ -16,6 +16,70 @@ export interface GetHandleOptions {
 const FILE_HANDLE_POOL_SIZE = 50
 const DIR_CACHE_MAX_SIZE = 200
 
+/**
+ * Manages file-level locks to prevent concurrent sync access handle creation.
+ * OPFS only allows one sync access handle per file at a time.
+ */
+export class FileLockManager {
+  private locks: Map<string, Promise<void>> = new Map()
+  private lockResolvers: Map<string, () => void> = new Map()
+  private waitQueues: Map<string, Array<() => void>> = new Map()
+
+  /**
+   * Acquire an exclusive lock on a file path.
+   * If the file is already locked, waits until it's released.
+   * Returns a release function that MUST be called when done.
+   */
+  async acquire(path: string): Promise<() => void> {
+    const normalizedPath = normalize(path)
+
+    // If file is currently locked, wait for it
+    while (this.locks.has(normalizedPath)) {
+      await this.locks.get(normalizedPath)
+    }
+
+    // Create new lock
+    let resolve: () => void
+    const lockPromise = new Promise<void>(r => {
+      resolve = r
+    })
+
+    this.locks.set(normalizedPath, lockPromise)
+    this.lockResolvers.set(normalizedPath, resolve!)
+
+    // Return release function
+    return () => {
+      const resolver = this.lockResolvers.get(normalizedPath)
+      this.locks.delete(normalizedPath)
+      this.lockResolvers.delete(normalizedPath)
+      if (resolver) resolver()
+    }
+  }
+
+  /**
+   * Check if a file is currently locked
+   */
+  isLocked(path: string): boolean {
+    return this.locks.has(normalize(path))
+  }
+
+  /**
+   * Clear all locks (use with caution, mainly for cleanup)
+   */
+  clearAll(): void {
+    // Resolve all pending locks
+    for (const resolver of this.lockResolvers.values()) {
+      resolver()
+    }
+    this.locks.clear()
+    this.lockResolvers.clear()
+    this.waitQueues.clear()
+  }
+}
+
+// Global file lock manager instance
+export const fileLockManager = new FileLockManager()
+
 /**
  * Manages OPFS handles with caching for improved performance
  */

package/src/index.ts

@@ -24,7 +24,7 @@ import type {
 import { constants, flagsToString } from './constants.js'
 import { createENOENT, createEEXIST, createEACCES, createEISDIR, wrapError } from './errors.js'
 import { normalize, dirname, basename, join, isRoot, segments } from './path-utils.js'
-import { HandleManager } from './handle-manager.js'
+import { HandleManager, fileLockManager } from './handle-manager.js'
 import { SymlinkManager } from './symlink-manager.js'
 import { PackedStorage } from './packed-storage.js'
 import { createFileHandle } from './file-handle.js'
@@ -187,11 +187,19 @@ export default class OPFS {
         let buffer: Uint8Array
 
         if (this.useSync) {
-          const access = await fileHandle.createSyncAccessHandle()
-          const size = access.getSize()
-          buffer = new Uint8Array(size)
-          access.read(buffer)
-          access.close()
+          const releaseLock = await fileLockManager.acquire(resolvedPath)
+          try {
+            const access = await fileHandle.createSyncAccessHandle()
+            try {
+              const size = access.getSize()
+              buffer = new Uint8Array(size)
+              access.read(buffer)
+            } finally {
+              access.close()
+            }
+          } finally {
+            releaseLock()
+          }
         } else {
           const file = await fileHandle.getFile()
           buffer = new Uint8Array(await file.arrayBuffer())
@@ -269,11 +277,19 @@ export default class OPFS {
 
               let buffer: Uint8Array
               if (this.useSync) {
-                const access = await fileHandle.createSyncAccessHandle()
-                const size = access.getSize()
-                buffer = new Uint8Array(size)
-                access.read(buffer)
-                access.close()
+                const releaseLock = await fileLockManager.acquire(resolvedPath)
+                try {
+                  const access = await fileHandle.createSyncAccessHandle()
+                  try {
+                    const size = access.getSize()
+                    buffer = new Uint8Array(size)
+                    access.read(buffer)
+                  } finally {
+                    access.close()
+                  }
+                } finally {
+                  releaseLock()
+                }
               } else {
                 const file = await fileHandle.getFile()
                 buffer = new Uint8Array(await file.arrayBuffer())
@@ -310,11 +326,19 @@ export default class OPFS {
       const buffer = typeof data === 'string' ? new TextEncoder().encode(data) : data
 
       if (this.useSync) {
-        const access = await fileHandle!.createSyncAccessHandle()
-        // Set exact size (more efficient than truncate(0) + write)
-        access.truncate(buffer.length)
-        access.write(buffer, { at: 0 })
-        access.close()
+        const releaseLock = await fileLockManager.acquire(resolvedPath)
+        try {
+          const access = await fileHandle!.createSyncAccessHandle()
+          try {
+            // Set exact size (more efficient than truncate(0) + write)
+            access.truncate(buffer.length)
+            access.write(buffer, { at: 0 })
+          } finally {
+            access.close()
+          }
+        } finally {
+          releaseLock()
+        }
       } else {
         const writable = await fileHandle!.createWritable()
         await writable.write(buffer)
@@ -1036,9 +1060,17 @@ export default class OPFS {
       if (!fileHandle) throw createENOENT(path)
 
       if (this.useSync) {
-        const access = await fileHandle.createSyncAccessHandle()
-        access.truncate(len)
-        access.close()
+        const releaseLock = await fileLockManager.acquire(resolvedPath)
+        try {
+          const access = await fileHandle.createSyncAccessHandle()
+          try {
+            access.truncate(len)
+          } finally {
+            access.close()
+          }
+        } finally {
+          releaseLock()
+        }
       } else {
         const file = await fileHandle.getFile()
         const data = new Uint8Array(await file.arrayBuffer())

package/src/packed-storage.ts

@@ -15,6 +15,7 @@
  */
 
 import type { HandleManager } from './handle-manager.js'
+import { fileLockManager } from './handle-manager.js'
 import { createECORRUPTED } from './errors.js'
 
 // ============ Compression ============
@@ -163,9 +164,9 @@ export class PackedStorage {
   /**
    * Load pack index from disk (always reloads to support hybrid mode)
    * Verifies CRC32 checksum for integrity
+   * Note: Caller must hold the lock
    */
   private async loadIndex(): Promise<PackIndex> {
-    // Always reload from disk to ensure we see writes from other threads/workers
     try {
       const { fileHandle } = await this.handleManager.getHandle(PACK_FILE)
       if (!fileHandle) {
@@ -173,37 +174,44 @@ export class PackedStorage {
       }
 
       if (this.useSync) {
-        const access = await fileHandle.createSyncAccessHandle()
-        const size = access.getSize()
-        if (size < 8) {
-          access.close()
-          return {}
-        }
-
-        // Read header: index length + CRC32
-        const header = new Uint8Array(8)
-        access.read(header, { at: 0 })
-        const view = new DataView(header.buffer)
-        const indexLen = view.getUint32(0, true)
-        const storedCrc = view.getUint32(4, true)
-
-        // Read everything after header (index + data) for CRC verification
-        const contentSize = size - 8
-        const content = new Uint8Array(contentSize)
-        access.read(content, { at: 8 })
-        access.close()
-
-        // Verify CRC32 if enabled
-        if (this.useChecksum && storedCrc !== 0) {
-          const calculatedCrc = crc32(content)
-          if (calculatedCrc !== storedCrc) {
-            throw createECORRUPTED(PACK_FILE)
+        const releaseLock = await fileLockManager.acquire(PACK_FILE)
+        try {
+          const access = await fileHandle.createSyncAccessHandle()
+          try {
+            const size = access.getSize()
+            if (size < 8) {
+              return {}
+            }
+
+            // Read header: index length + CRC32
+            const header = new Uint8Array(8)
+            access.read(header, { at: 0 })
+            const view = new DataView(header.buffer)
+            const indexLen = view.getUint32(0, true)
+            const storedCrc = view.getUint32(4, true)
+
+            // Read everything after header (index + data) for CRC verification
+            const contentSize = size - 8
+            const content = new Uint8Array(contentSize)
+            access.read(content, { at: 8 })
+
+            // Verify CRC32 if enabled
+            if (this.useChecksum && storedCrc !== 0) {
+              const calculatedCrc = crc32(content)
+              if (calculatedCrc !== storedCrc) {
+                throw createECORRUPTED(PACK_FILE)
+              }
+            }
+
+            // Parse index from content
+            const indexJson = new TextDecoder().decode(content.subarray(0, indexLen))
+            return JSON.parse(indexJson)
+          } finally {
+            access.close()
           }
+        } finally {
+          releaseLock()
         }
-
-        // Parse index from content
-        const indexJson = new TextDecoder().decode(content.subarray(0, indexLen))
-        return JSON.parse(indexJson)
       } else {
         const file = await fileHandle.getFile()
         const data = new Uint8Array(await file.arrayBuffer())
@@ -266,10 +274,18 @@ export class PackedStorage {
     let buffer: Uint8Array
 
     if (this.useSync) {
-      const access = await fileHandle.createSyncAccessHandle()
-      buffer = new Uint8Array(entry.size)
-      access.read(buffer, { at: entry.offset })
-      access.close()
+      const releaseLock = await fileLockManager.acquire(PACK_FILE)
+      try {
+        const access = await fileHandle.createSyncAccessHandle()
+        try {
+          buffer = new Uint8Array(entry.size)
+          access.read(buffer, { at: entry.offset })
+        } finally {
+          access.close()
+        }
+      } finally {
+        releaseLock()
+      }
     } else {
       const file = await fileHandle.getFile()
       const data = new Uint8Array(await file.arrayBuffer())
@@ -320,19 +336,27 @@ export class PackedStorage {
     const decompressPromises: Array<{ path: string; promise: Promise<Uint8Array> }> = []
 
     if (this.useSync) {
-      const access = await fileHandle.createSyncAccessHandle()
-      for (const { path, offset, size, originalSize } of toRead) {
-        const buffer = new Uint8Array(size)
-        access.read(buffer, { at: offset })
-
-        if (originalSize !== undefined) {
-          // Queue for decompression
-          decompressPromises.push({ path, promise: decompress(buffer) })
-        } else {
-          results.set(path, buffer)
+      const releaseLock = await fileLockManager.acquire(PACK_FILE)
+      try {
+        const access = await fileHandle.createSyncAccessHandle()
+        try {
+          for (const { path, offset, size, originalSize } of toRead) {
+            const buffer = new Uint8Array(size)
+            access.read(buffer, { at: offset })
+
+            if (originalSize !== undefined) {
+              // Queue for decompression
+              decompressPromises.push({ path, promise: decompress(buffer) })
+            } else {
+              results.set(path, buffer)
+            }
+          }
+        } finally {
+          access.close()
         }
+      } finally {
+        releaseLock()
       }
-      access.close()
     } else {
       const file = await fileHandle.getFile()
       const data = new Uint8Array(await file.arrayBuffer())
@@ -444,16 +468,25 @@ export class PackedStorage {
 
   /**
    * Write the pack file to OPFS
+   * Note: Caller must hold the lock
    */
   private async writePackFile(data: Uint8Array): Promise<void> {
     const { fileHandle } = await this.handleManager.getHandle(PACK_FILE, { create: true })
     if (!fileHandle) return
 
     if (this.useSync) {
-      const access = await fileHandle.createSyncAccessHandle()
-      access.truncate(data.length)
-      access.write(data, { at: 0 })
-      access.close()
+      const releaseLock = await fileLockManager.acquire(PACK_FILE)
+      try {
+        const access = await fileHandle.createSyncAccessHandle()
+        try {
+          access.truncate(data.length)
+          access.write(data, { at: 0 })
+        } finally {
+          access.close()
+        }
+      } finally {
+        releaseLock()
+      }
     } else {
       const writable = await fileHandle.createWritable()
       await writable.write(data)
@@ -479,46 +512,54 @@ export class PackedStorage {
     const newIndexBuf = encoder.encode(JSON.stringify(index))
 
     if (this.useSync) {
-      const access = await fileHandle.createSyncAccessHandle()
-      const size = access.getSize()
-
-      // Read old header to get old index length
-      const oldHeader = new Uint8Array(8)
-      access.read(oldHeader, { at: 0 })
-      const oldIndexLen = new DataView(oldHeader.buffer).getUint32(0, true)
-
-      // Read data portion (after old index)
-      const dataStart = 8 + oldIndexLen
-      const dataSize = size - dataStart
-      const dataPortion = new Uint8Array(dataSize)
-      if (dataSize > 0) {
-        access.read(dataPortion, { at: dataStart })
-      }
+      const releaseLock = await fileLockManager.acquire(PACK_FILE)
+      try {
+        const access = await fileHandle.createSyncAccessHandle()
+        try {
+          const size = access.getSize()
+
+          // Read old header to get old index length
+          const oldHeader = new Uint8Array(8)
+          access.read(oldHeader, { at: 0 })
+          const oldIndexLen = new DataView(oldHeader.buffer).getUint32(0, true)
+
+          // Read data portion (after old index)
+          const dataStart = 8 + oldIndexLen
+          const dataSize = size - dataStart
+          const dataPortion = new Uint8Array(dataSize)
+          if (dataSize > 0) {
+            access.read(dataPortion, { at: dataStart })
+          }
 
-      // Build new content (new index + data)
-      const newContent = new Uint8Array(newIndexBuf.length + dataSize)
-      newContent.set(newIndexBuf, 0)
-      if (dataSize > 0) {
-        newContent.set(dataPortion, newIndexBuf.length)
-      }
+          // Build new content (new index + data)
+          const newContent = new Uint8Array(newIndexBuf.length + dataSize)
+          newContent.set(newIndexBuf, 0)
+          if (dataSize > 0) {
+            newContent.set(dataPortion, newIndexBuf.length)
+          }
 
-      // Calculate new CRC32 if enabled
-      const checksum = this.useChecksum ? crc32(newContent) : 0
+          // Calculate new CRC32 if enabled
+          const checksum = this.useChecksum ? crc32(newContent) : 0
 
-      // Build new header
-      const newHeader = new Uint8Array(8)
-      const view = new DataView(newHeader.buffer)
-      view.setUint32(0, newIndexBuf.length, true)
-      view.setUint32(4, checksum, true)
+          // Build new header
+          const newHeader = new Uint8Array(8)
+          const view = new DataView(newHeader.buffer)
+          view.setUint32(0, newIndexBuf.length, true)
+          view.setUint32(4, checksum, true)
 
-      // Write new file
-      const newFile = new Uint8Array(8 + newContent.length)
-      newFile.set(newHeader, 0)
-      newFile.set(newContent, 8)
+          // Write new file
+          const newFile = new Uint8Array(8 + newContent.length)
+          newFile.set(newHeader, 0)
+          newFile.set(newContent, 8)
 
-      access.truncate(newFile.length)
-      access.write(newFile, { at: 0 })
-      access.close()
+          access.truncate(newFile.length)
+          access.write(newFile, { at: 0 })
+        } finally {
+          access.close()
+        }
+      } finally {
+        releaseLock()
+      }
     } else {
       // For non-sync, rewrite the whole file
       const file = await fileHandle.getFile()

package/src/symlink-manager.ts

@@ -1,5 +1,6 @@
 import type { SymlinkCache, SymlinkDefinition } from './types.js'
 import type { HandleManager } from './handle-manager.js'
+import { fileLockManager } from './handle-manager.js'
 import { normalize } from './path-utils.js'
 import { createELOOP, createEINVAL, createEEXIST } from './errors.js'
 
@@ -101,13 +102,21 @@ export class SymlinkManager {
     const buffer = new TextEncoder().encode(data)
 
     if (this.useSync) {
-      const access = await fileHandle.createSyncAccessHandle()
-      access.truncate(0)
-      let written = 0
-      while (written < buffer.length) {
-        written += access.write(buffer.subarray(written), { at: written })
+      const releaseLock = await fileLockManager.acquire(SYMLINK_FILE)
+      try {
+        const access = await fileHandle.createSyncAccessHandle()
+        try {
+          access.truncate(0)
+          let written = 0
+          while (written < buffer.length) {
+            written += access.write(buffer.subarray(written), { at: written })
+          }
+        } finally {
+          access.close()
+        }
+      } finally {
+        releaseLock()
       }
-      access.close()
     } else {
       const writable = await fileHandle.createWritable()
       await writable.write(buffer)