@componentor/fs 1.1.7

package/src/errors.ts

@@ -0,0 +1,88 @@
+/**
+ * Custom error class for filesystem errors
+ */
+export class FSError extends Error {
+  code: string
+  syscall?: string
+  path?: string
+  original?: Error
+
+  constructor(message: string, code: string, options?: { syscall?: string; path?: string; original?: Error }) {
+    super(message)
+    this.name = 'FSError'
+    this.code = code
+    this.syscall = options?.syscall
+    this.path = options?.path
+    this.original = options?.original
+  }
+}
+
+/**
+ * Create ENOENT (No such file or directory) error
+ */
+export function createENOENT(path: string): FSError {
+  return new FSError(`ENOENT: No such file or directory, '${path}'`, 'ENOENT', { path })
+}
+
+/**
+ * Create EEXIST (File exists) error
+ */
+export function createEEXIST(path: string, operation?: string): FSError {
+  const message = operation
+    ? `EEXIST: file already exists, ${operation} '${path}'`
+    : `EEXIST: File exists, '${path}'`
+  return new FSError(message, 'EEXIST', { path })
+}
+
+/**
+ * Create EACCES (Permission denied) error
+ */
+export function createEACCES(path: string, syscall?: string): FSError {
+  return new FSError(`EACCES: permission denied, access '${path}'`, 'EACCES', { syscall, path })
+}
+
+/**
+ * Create EISDIR (Is a directory) error
+ */
+export function createEISDIR(path: string, operation = 'operation'): FSError {
+  return new FSError(`EISDIR: illegal operation on a directory, ${operation} '${path}'`, 'EISDIR', { path })
+}
+
+/**
+ * Create ELOOP (Too many symbolic links) error
+ */
+export function createELOOP(path: string): FSError {
+  return new FSError(`ELOOP: Too many symbolic links, '${path}'`, 'ELOOP', { path })
+}
+
+/**
+ * Create EINVAL (Invalid argument) error
+ */
+export function createEINVAL(path: string): FSError {
+  return new FSError(`EINVAL: Invalid argument, '${path}'`, 'EINVAL', { path })
+}
+
+/**
+ * Create ECORRUPTED (Data corruption detected) error
+ */
+export function createECORRUPTED(path: string): FSError {
+  return new FSError(`ECORRUPTED: Pack file integrity check failed, '${path}'`, 'ECORRUPTED', { path })
+}
+
+/**
+ * Wrap an error with a standard code if it doesn't have one
+ */
+export function wrapError(err: unknown): FSError {
+  if (err instanceof FSError) return err
+
+  const error = err as Error
+  if (typeof (error as FSError).code === 'string') {
+    const fsErr = new FSError(error.message, (error as FSError).code)
+    fsErr.original = error
+    return fsErr
+  }
+
+  const wrapped = new FSError(error.message || 'Unknown error', 'UNKNOWN')
+  wrapped.original = error
+  return wrapped
+}

package/src/file-handle.ts

@@ -0,0 +1,100 @@
+import type { FileHandle, ReadResult, WriteResult, Stats, ReadFileOptions, WriteFileOptions } from './types.js'
+
+export interface FileHandleContext {
+  readFile(path: string, options?: ReadFileOptions): Promise<string | Uint8Array>
+  writeFile(path: string, data: string | Uint8Array, options?: WriteFileOptions): Promise<void>
+  appendFile(path: string, data: string | Uint8Array, options?: WriteFileOptions): Promise<void>
+  stat(path: string): Promise<Stats>
+  truncate(path: string, len: number): Promise<void>
+}
+
+/**
+ * Create a FileHandle-like object for the open() method
+ */
+export function createFileHandle(
+  resolvedPath: string,
+  initialPosition: number,
+  context: FileHandleContext
+): FileHandle {
+  let position = initialPosition
+
+  return {
+    fd: Math.floor(Math.random() * 1000000),
+
+    async read(
+      buffer: Uint8Array,
+      offset = 0,
+      length = buffer.length,
+      pos: number | null = null
+    ): Promise<ReadResult> {
+      const readPos = pos !== null ? pos : position
+      const data = await context.readFile(resolvedPath) as Uint8Array
+      const bytesToRead = Math.min(length, data.length - readPos)
+      buffer.set(data.subarray(readPos, readPos + bytesToRead), offset)
+      if (pos === null) position += bytesToRead
+      return { bytesRead: bytesToRead, buffer }
+    },
+
+    async write(
+      buffer: Uint8Array,
+      offset = 0,
+      length = buffer.length,
+      pos: number | null = null
+    ): Promise<WriteResult> {
+      const writePos = pos !== null ? pos : position
+      let existingData = new Uint8Array(0)
+
+      try {
+        existingData = await context.readFile(resolvedPath) as Uint8Array
+      } catch (e) {
+        if ((e as { code?: string }).code !== 'ENOENT') throw e
+      }
+
+      const dataToWrite = buffer.subarray(offset, offset + length)
+      const newSize = Math.max(existingData.length, writePos + length)
+      const newData = new Uint8Array(newSize)
+      newData.set(existingData, 0)
+      newData.set(dataToWrite, writePos)
+
+      await context.writeFile(resolvedPath, newData)
+      if (pos === null) position += length
+      return { bytesWritten: length, buffer }
+    },
+
+    async close(): Promise<void> {
+      // No-op for OPFS
+    },
+
+    async stat(): Promise<Stats> {
+      return context.stat(resolvedPath)
+    },
+
+    async truncate(len = 0): Promise<void> {
+      return context.truncate(resolvedPath, len)
+    },
+
+    async sync(): Promise<void> {
+      // No-op for OPFS (writes are already persisted)
+    },
+
+    async datasync(): Promise<void> {
+      // No-op for OPFS
+    },
+
+    async readFile(options?: ReadFileOptions): Promise<string | Uint8Array> {
+      return context.readFile(resolvedPath, options)
+    },
+
+    async writeFile(data: string | Uint8Array, options?: WriteFileOptions): Promise<void> {
+      return context.writeFile(resolvedPath, data, options)
+    },
+
+    async appendFile(data: string | Uint8Array, options?: WriteFileOptions): Promise<void> {
+      return context.appendFile(resolvedPath, data, options)
+    },
+
+    [Symbol.asyncDispose]: async function(): Promise<void> {
+      // No-op for OPFS
+    }
+  }
+}

package/src/global.d.ts

@@ -0,0 +1,57 @@
+// File System Access API type declarations
+
+interface FileSystemSyncAccessHandle {
+  read(buffer: ArrayBufferView, options?: { at?: number }): number
+  write(buffer: ArrayBufferView, options?: { at?: number }): number
+  truncate(newSize: number): void
+  getSize(): number
+  flush(): void
+  close(): void
+}
+
+interface FileSystemFileHandle {
+  readonly kind: 'file'
+  readonly name: string
+  getFile(): Promise<File>
+  createWritable(options?: { keepExistingData?: boolean }): Promise<FileSystemWritableFileStream>
+  createSyncAccessHandle(): Promise<FileSystemSyncAccessHandle>
+}
+
+interface FileSystemDirectoryHandle {
+  readonly kind: 'directory'
+  readonly name: string
+  getFileHandle(name: string, options?: { create?: boolean }): Promise<FileSystemFileHandle>
+  getDirectoryHandle(name: string, options?: { create?: boolean }): Promise<FileSystemDirectoryHandle>
+  removeEntry(name: string, options?: { recursive?: boolean }): Promise<void>
+  resolve(possibleDescendant: FileSystemHandle): Promise<string[] | null>
+  entries(): AsyncIterableIterator<[string, FileSystemHandle]>
+  keys(): AsyncIterableIterator<string>
+  values(): AsyncIterableIterator<FileSystemHandle>
+  [Symbol.asyncIterator](): AsyncIterableIterator<[string, FileSystemHandle]>
+}
+
+interface FileSystemWritableFileStream extends WritableStream {
+  write(data: ArrayBuffer | ArrayBufferView | Blob | string | WriteParams): Promise<void>
+  seek(position: number): Promise<void>
+  truncate(size: number): Promise<void>
+}
+
+interface WriteParams {
+  type: 'write' | 'seek' | 'truncate'
+  data?: ArrayBuffer | ArrayBufferView | Blob | string
+  position?: number
+  size?: number
+}
+
+type FileSystemHandle = FileSystemFileHandle | FileSystemDirectoryHandle
+
+interface StorageManager {
+  getDirectory(): Promise<FileSystemDirectoryHandle>
+  estimate(): Promise<StorageEstimate>
+  persist(): Promise<boolean>
+  persisted(): Promise<boolean>
+}
+
+interface Navigator {
+  storage: StorageManager
+}

package/src/handle-manager.ts

@@ -0,0 +1,250 @@
+import { normalize, segments, dirname } from './path-utils.js'
+import { createENOENT } from './errors.js'
+
+export interface HandleResult {
+  dir: FileSystemDirectoryHandle
+  name: string
+  fileHandle: FileSystemFileHandle | null
+  dirHandle: FileSystemDirectoryHandle | null
+}
+
+export interface GetHandleOptions {
+  create?: boolean
+  kind?: 'file' | 'directory'
+}
+
+const FILE_HANDLE_POOL_SIZE = 50
+const DIR_CACHE_MAX_SIZE = 200
+
+/**
+ * Manages OPFS handles with caching for improved performance
+ */
+export class HandleManager {
+  private rootPromise: Promise<FileSystemDirectoryHandle>
+  private dirCache: Map<string, FileSystemDirectoryHandle> = new Map()
+  private fileHandlePool: Map<string, FileSystemFileHandle> = new Map()
+
+  constructor() {
+    this.rootPromise = navigator.storage.getDirectory()
+  }
+
+  /**
+   * Get the root directory handle
+   */
+  async getRoot(): Promise<FileSystemDirectoryHandle> {
+    return this.rootPromise
+  }
+
+  /**
+   * Cache a directory handle with LRU eviction
+   */
+  private cacheDirHandle(path: string, handle: FileSystemDirectoryHandle): void {
+    if (this.dirCache.size >= DIR_CACHE_MAX_SIZE) {
+      // Delete oldest entry (first key in Map maintains insertion order)
+      const firstKey = this.dirCache.keys().next().value
+      if (firstKey) this.dirCache.delete(firstKey)
+    }
+    this.dirCache.set(path, handle)
+  }
+
+  /**
+   * Clear directory cache for a path and its children
+   */
+  clearCache(path = ''): void {
+    const normalizedPath = normalize(path)
+
+    // For root path, just clear everything
+    if (normalizedPath === '/' || normalizedPath === '') {
+      this.dirCache.clear()
+      this.fileHandlePool.clear()
+      return
+    }
+
+    // Clear directory cache
+    if (this.dirCache.size > 0) {
+      for (const key of this.dirCache.keys()) {
+        if (key === normalizedPath || key.startsWith(normalizedPath + '/')) {
+          this.dirCache.delete(key)
+        }
+      }
+    }
+
+    // Clear file handle pool for affected paths
+    if (this.fileHandlePool.size > 0) {
+      for (const key of this.fileHandlePool.keys()) {
+        if (key === normalizedPath || key.startsWith(normalizedPath + '/')) {
+          this.fileHandlePool.delete(key)
+        }
+      }
+    }
+  }
+
+  /**
+   * Get a file handle from the pool or create a new one
+   */
+  async getPooledFileHandle(path: string, create = false): Promise<FileSystemFileHandle | null> {
+    const normalizedPath = normalize(path)
+
+    // Check pool first
+    const pooled = this.fileHandlePool.get(normalizedPath)
+    if (pooled) {
+      return pooled
+    }
+
+    // Get handle the normal way
+    const { fileHandle } = await this.getHandle(normalizedPath, { create })
+    if (!fileHandle) return null
+
+    // Add to pool with LRU eviction
+    if (this.fileHandlePool.size >= FILE_HANDLE_POOL_SIZE) {
+      // Delete oldest entry (first key in Map maintains insertion order)
+      const firstKey = this.fileHandlePool.keys().next().value
+      if (firstKey) this.fileHandlePool.delete(firstKey)
+    }
+    this.fileHandlePool.set(normalizedPath, fileHandle)
+
+    return fileHandle
+  }
+
+  /**
+   * Invalidate a specific file handle from the pool
+   */
+  invalidateFileHandle(path: string): void {
+    const normalizedPath = normalize(path)
+    this.fileHandlePool.delete(normalizedPath)
+  }
+
+  /**
+   * Get file or directory handle for a path
+   */
+  async getHandle(path: string, opts: GetHandleOptions = {}): Promise<HandleResult> {
+    // Use segments() for optimized path parsing (leverages normalize cache)
+    const parts = segments(path)
+
+    // Handle root or empty path
+    if (parts.length === 0) {
+      const root = await this.rootPromise
+      return { dir: root, name: '', fileHandle: null, dirHandle: root }
+    }
+
+    let dir = await this.rootPromise
+    let currentPath = ''
+
+    // Navigate to parent directory using cache
+    for (let i = 0; i < parts.length - 1; i++) {
+      currentPath += '/' + parts[i]
+
+      // Check cache first for better performance
+      if (this.dirCache.has(currentPath)) {
+        dir = this.dirCache.get(currentPath)!
+        continue
+      }
+
+      try {
+        dir = await dir.getDirectoryHandle(parts[i], { create: opts.create })
+        this.cacheDirHandle(currentPath, dir)
+      } catch {
+        throw createENOENT(path)
+      }
+    }
+
+    const name = parts[parts.length - 1]
+
+    try {
+      if (opts.kind === 'directory') {
+        const dirHandle = await dir.getDirectoryHandle(name, { create: opts.create })
+        return { dir, name, fileHandle: null, dirHandle }
+      } else {
+        const fileHandle = await dir.getFileHandle(name, { create: opts.create })
+        return { dir, name, fileHandle, dirHandle: null }
+      }
+    } catch {
+      if (!opts.create) {
+        return { dir, name, fileHandle: null, dirHandle: null }
+      }
+      throw createENOENT(path)
+    }
+  }
+
+  /**
+   * Get directory handle with caching
+   */
+  async getDirectoryHandle(path: string): Promise<FileSystemDirectoryHandle> {
+    const normalizedPath = normalize(path)
+
+    if (normalizedPath === '/' || normalizedPath === '') {
+      return this.rootPromise
+    }
+
+    // Check cache first
+    if (this.dirCache.has(normalizedPath)) {
+      return this.dirCache.get(normalizedPath)!
+    }
+
+    const parts = segments(normalizedPath)
+    let dir = await this.rootPromise
+    let currentPath = ''
+
+    for (const part of parts) {
+      currentPath += '/' + part
+
+      if (this.dirCache.has(currentPath)) {
+        dir = this.dirCache.get(currentPath)!
+        continue
+      }
+
+      dir = await dir.getDirectoryHandle(part)
+      this.cacheDirHandle(currentPath, dir)
+    }
+
+    return dir
+  }
+
+  /**
+   * Ensure parent directory exists
+   */
+  async ensureParentDir(path: string): Promise<void> {
+    const parentPath = dirname(path)
+    if (parentPath === '/' || parentPath === '') return
+
+    const parts = segments(parentPath)
+    let dir = await this.rootPromise
+    let currentPath = ''
+
+    for (const part of parts) {
+      currentPath += '/' + part
+
+      // Check cache first for better performance
+      if (this.dirCache.has(currentPath)) {
+        dir = this.dirCache.get(currentPath)!
+        continue
+      }
+
+      dir = await dir.getDirectoryHandle(part, { create: true })
+      this.cacheDirHandle(currentPath, dir)
+    }
+  }
+
+  /**
+   * Create directory (with automatic parent creation)
+   */
+  async mkdir(path: string): Promise<void> {
+    const normalizedPath = normalize(path)
+    this.clearCache(normalizedPath)
+
+    const parts = segments(normalizedPath)
+    let dir = await this.rootPromise
+
+    for (let i = 0; i < parts.length; i++) {
+      const part = parts[i]
+      const subPath = '/' + parts.slice(0, i + 1).join('/')
+
+      if (this.dirCache.has(subPath)) {
+        dir = this.dirCache.get(subPath)!
+      } else {
+        dir = await dir.getDirectoryHandle(part, { create: true })
+        this.cacheDirHandle(subPath, dir)
+      }
+    }
+  }
+}