@dotdo/postgres 0.1.0

package/src/pglite/dovfs-adapter.ts

@@ -0,0 +1,1122 @@
+/**
+ * PGLite Adapter - Bridges DOVFS to PGLite Filesystem interface
+ *
+ * This adapter implements PGLite's Filesystem interface using our DOVFS
+ * (Durable Object Virtual File System) for persistent storage in Cloudflare
+ * Durable Objects.
+ *
+ * Extends PGLite's BaseFilesystem to provide a synchronous filesystem API
+ * over the async DOVFS storage.
+ *
+ * @module dovfs-adapter
+ */
+
+import type { DOVFSStorage, FileMetadata } from './dovfs'
+import {
+  DOVFS,
+  DOVFSFile,
+  SQLITE_OK,
+  SQLITE_OPEN_READWRITE,
+  SQLITE_OPEN_CREATE,
+  SQLITE_OPEN_READONLY,
+} from './dovfs'
+
+/**
+ * BaseFilesystem abstract class compatible with PGLite's filesystem interface.
+ *
+ * This is a minimal implementation that provides the base functionality needed
+ * by DOVFSAdapter without requiring import from pglite internals.
+ *
+ * @abstract
+ */
+export abstract class BaseFilesystem {
+  /** Base data directory for the filesystem */
+  protected dataDir?: string
+  /** Enable debug logging */
+  readonly debug: boolean
+
+  /**
+   * Creates a new BaseFilesystem instance.
+   * @param dataDir - Optional base data directory path
+   * @param options - Configuration options
+   * @param options.debug - Enable debug logging (default: false)
+   */
+  constructor(dataDir?: string, { debug = false }: { debug?: boolean } = {}) {
+    this.dataDir = dataDir
+    this.debug = debug
+  }
+
+  /**
+   * Sync filesystem to persistent storage.
+   * @param _relaxedDurability - If true, allows for less strict durability guarantees
+   */
+  async syncToFs(_relaxedDurability?: boolean): Promise<void> {}
+
+  /**
+   * Perform initial sync from storage to in-memory representation.
+   */
+  async initialSyncFs(): Promise<void> {}
+
+  /**
+   * Close the filesystem and release resources.
+   */
+  async closeFs(): Promise<void> {}
+
+  // Filesystem API - abstract methods to be implemented by subclasses
+  abstract chmod(path: string, mode: number): void
+  abstract close(fd: number): void
+  abstract fstat(fd: number): FsStats
+  abstract lstat(path: string): FsStats
+  abstract mkdir(path: string, options?: { recursive?: boolean; mode?: number }): void
+  abstract open(path: string, flags?: string, mode?: number): number
+  abstract readdir(path: string): string[]
+  abstract read(fd: number, buffer: Uint8Array, offset: number, length: number, position: number): number
+  abstract rename(oldPath: string, newPath: string): void
+  abstract rmdir(path: string): void
+  abstract truncate(path: string, len: number): void
+  abstract unlink(path: string): void
+  abstract utimes(path: string, atime: number, mtime: number): void
+  abstract writeFile(path: string, data: string | Uint8Array, options?: { encoding?: string; mode?: number; flag?: string }): void
+  abstract write(fd: number, buffer: Uint8Array, offset: number, length: number, position: number): number
+}
+
+// PGLite filesystem constants
+/** WASM filesystem prefix path */
+export const WASM_PREFIX = '/tmp/pglite'
+/** PostgreSQL data directory path within WASM filesystem */
+export const PGDATA = WASM_PREFIX + '/base'
+
+/**
+ * Error codes compatible with Emscripten's FS error system.
+ * These codes map to standard POSIX errno values used by Emscripten.
+ * @see https://man7.org/linux/man-pages/man3/errno.3.html
+ */
+export const ERRNO_CODES = {
+  /** Bad file descriptor */
+  EBADF: 8,
+  /** File descriptor in bad state */
+  EBADFD: 127,
+  /** File already exists */
+  EEXIST: 20,
+  /** Invalid argument */
+  EINVAL: 28,
+  /** Is a directory (illegal operation on a directory) */
+  EISDIR: 31,
+  /** No such device */
+  ENODEV: 43,
+  /** No such file or directory */
+  ENOENT: 44,
+  /** Not a directory */
+  ENOTDIR: 54,
+  /** Directory not empty */
+  ENOTEMPTY: 55,
+} as const
+
+/** Type for ERRNO_CODES keys */
+export type ErrnoCode = keyof typeof ERRNO_CODES
+
+/**
+ * Filesystem error type with errno code
+ */
+export interface FsError extends Error {
+  code: ErrnoCode | string
+}
+
+/**
+ * File stats structure compatible with PGLite's FsStats.
+ * Mirrors the stat(2) system call structure.
+ */
+export interface FsStats {
+  /** Device ID */
+  dev: number
+  /** Inode number */
+  ino: number
+  /** File mode (permissions and type) */
+  mode: number
+  /** Number of hard links */
+  nlink: number
+  /** User ID of owner */
+  uid: number
+  /** Group ID of owner */
+  gid: number
+  /** Device ID (if special file) */
+  rdev: number
+  /** Total size in bytes */
+  size: number
+  /** Block size for filesystem I/O */
+  blksize: number
+  /** Number of 512B blocks allocated */
+  blocks: number
+  /** Time of last access (ms since epoch) */
+  atime: number
+  /** Time of last modification (ms since epoch) */
+  mtime: number
+  /** Time of last status change (ms since epoch) */
+  ctime: number
+}
+
+/** File open mode flags used internally */
+const FILE_MODE_READ = 0x01
+const FILE_MODE_WRITE = 0x02
+
+/**
+ * Open file descriptor tracking.
+ * Maintains state for each open file handle.
+ * @internal
+ */
+interface OpenFile {
+  /** Full path to the file */
+  path: string
+  /** DOVFS file handle */
+  file: DOVFSFile
+  /** Current read/write position */
+  position: number
+  /** Open flags (SQLITE_OPEN_*) */
+  flags: number
+  /** Internal mode flags (FILE_MODE_READ, FILE_MODE_WRITE) */
+  modeFlags: number
+}
+
+/**
+ * In-memory file node for virtual filesystem.
+ * Represents either a file or directory in the virtual filesystem tree.
+ * @internal
+ */
+interface FileNode {
+  /** File or directory name (basename) */
+  name: string
+  /** Full path */
+  path: string
+  /** File mode (permissions and type flags) */
+  mode: number
+  /** Size in bytes (0 for directories) */
+  size: number
+  /** True if this node represents a directory */
+  isDirectory: boolean
+  /** Creation timestamp (ms since epoch) */
+  created: number
+  /** Last modification timestamp (ms since epoch) */
+  modified: number
+  /** Last access timestamp (ms since epoch) */
+  accessed: number
+  /** File contents (undefined for directories) */
+  data?: Uint8Array
+  /** Child nodes (only for directories) */
+  children?: Map<string, FileNode>
+}
+
+/**
+ * Creates a filesystem error with the appropriate code.
+ * @param code - Error code name (e.g., 'ENOENT', 'EBADF')
+ * @param message - Human-readable error message
+ * @returns Error object with code property set
+ * @internal
+ */
+function createFsError(code: ErrnoCode, message: string): NodeJS.ErrnoException {
+  const error = new Error(message) as NodeJS.ErrnoException
+  error.code = code
+  return error
+}
+
+/**
+ * DOVFSAdapter - Adapts DOVFS for use with PGLite
+ *
+ * This class extends PGLite's BaseFilesystem and implements the filesystem
+ * operations required by PGLite, using DOVFS for persistent storage.
+ *
+ * The adapter maintains an in-memory representation of the filesystem tree
+ * while using DOVFS for persistent storage of file contents. This design
+ * allows for synchronous filesystem operations (required by PGLite's WASM
+ * interface) while deferring async storage operations to sync points.
+ *
+ * @example
+ * ```typescript
+ * const storage = ctx.storage; // Durable Object storage
+ * const adapter = new DOVFSAdapter(storage, '/pgdata', { debug: false });
+ * await adapter.initialSyncFs();
+ * // Use adapter for filesystem operations
+ * await adapter.closeFs();
+ * ```
+ */
+export class DOVFSAdapter extends BaseFilesystem {
+  /** Durable Object storage interface */
+  private storage: DOVFSStorage
+  /** DOVFS instance for file operations */
+  private dovfs: DOVFS
+  /** Map of open file descriptors to their state */
+  private files: Map<number, OpenFile> = new Map()
+  /** Next file descriptor to assign (starts after stdin/stdout/stderr) */
+  private nextFd: number = 3
+  /** In-memory filesystem tree */
+  private inMemoryNodes: Map<string, FileNode> = new Map()
+
+  /**
+   * Creates a new DOVFSAdapter instance.
+   * @param storage - Durable Object storage interface
+   * @param dataDir - Optional base data directory path
+   * @param options - Configuration options
+   * @param options.debug - Enable debug logging (default: false)
+   */
+  constructor(
+    storage: DOVFSStorage,
+    dataDir?: string,
+    options: { debug?: boolean } = {}
+  ) {
+    super(dataDir, options)
+    this.storage = storage
+    this.dovfs = new DOVFS(storage)
+    this.initRootDirectory()
+  }
+
+  /**
+   * Initialize root directory structure.
+   * Creates the root node with proper directory permissions.
+   * @internal
+   */
+  private initRootDirectory(): void {
+    const now = Date.now()
+    this.inMemoryNodes.set('/', {
+      name: '',
+      path: '/',
+      mode: 0o40755, // Directory with rwxr-xr-x
+      size: 0,
+      isDirectory: true,
+      created: now,
+      modified: now,
+      accessed: now,
+      children: new Map(),
+    })
+  }
+
+  /**
+   * Get or create a directory node in the filesystem tree.
+   * @param path - Absolute path to the directory
+   * @param mode - Optional mode (permissions) for the directory
+   * @returns The directory FileNode
+   * @internal
+   */
+  private getOrCreateDir(path: string, mode?: number): FileNode {
+    const existing = this.inMemoryNodes.get(path)
+    if (existing) return existing
+
+    const now = Date.now()
+    const parts = path.split('/').filter(p => p !== '')
+    const name = parts[parts.length - 1] || ''
+
+    // Combine directory type with provided permissions or default
+    const dirMode = 0o40000 | (mode !== undefined ? (mode & 0o777) : 0o755)
+
+    const node: FileNode = {
+      name,
+      path,
+      mode: dirMode,
+      size: 0,
+      isDirectory: true,
+      created: now,
+      modified: now,
+      accessed: now,
+      children: new Map(),
+    }
+
+    this.inMemoryNodes.set(path, node)
+
+    // Add to parent directory
+    const parentPath = '/' + parts.slice(0, -1).join('/')
+    const parent = this.inMemoryNodes.get(parentPath || '/')
+    if (parent?.children) {
+      parent.children.set(name, node)
+    }
+
+    return node
+  }
+
+  /**
+   * Get or create a file node in the filesystem tree.
+   * If the file exists and data is provided, updates the file content.
+   * @param path - Absolute path to the file
+   * @param data - Optional file content
+   * @param mode - Optional file permissions (default: 0o644)
+   * @returns The file FileNode
+   * @internal
+   */
+  private getOrCreateFile(path: string, data?: Uint8Array, mode?: number): FileNode {
+    const existing = this.inMemoryNodes.get(path)
+    if (existing && !existing.isDirectory) {
+      if (data !== undefined) {
+        existing.data = data
+        existing.size = data.length
+        existing.modified = Date.now()
+      }
+      if (mode !== undefined) {
+        // Update mode, preserving file type bits
+        existing.mode = 0o100000 | (mode & 0o777)
+      }
+      return existing
+    }
+
+    const now = Date.now()
+    const parts = path.split('/').filter(p => p !== '')
+    const name = parts[parts.length - 1] || ''
+
+    // Combine regular file type with provided permissions or default
+    const fileMode = 0o100000 | (mode !== undefined ? (mode & 0o777) : 0o644)
+
+    const node: FileNode = {
+      name,
+      path,
+      mode: fileMode,
+      size: data?.length ?? 0,
+      isDirectory: false,
+      created: now,
+      modified: now,
+      accessed: now,
+      data,
+    }
+
+    this.inMemoryNodes.set(path, node)
+
+    // Add to parent directory
+    const parentPath = '/' + parts.slice(0, -1).join('/')
+    const parent = this.inMemoryNodes.get(parentPath || '/')
+    if (parent?.children) {
+      parent.children.set(name, node)
+    }
+
+    return node
+  }
+
+  /**
+   * Log a debug message if debug mode is enabled.
+   * @param args - Arguments to log
+   * @internal
+   */
+  private log(...args: unknown[]): void {
+    if (this.debug) {
+      console.log('[DOVFSAdapter]', ...args)
+    }
+  }
+
+  /**
+   * Change file mode (permissions).
+   * Updates the mode bits for the specified file or directory.
+   * @param path - Absolute path to the file or directory
+   * @param mode - New mode bits (e.g., 0o644 for rw-r--r--)
+   * @throws {NodeJS.ErrnoException} ENOENT if path does not exist
+   */
+  chmod(path: string, mode: number): void {
+    this.log('chmod', path, mode)
+    const node = this.inMemoryNodes.get(path)
+    if (!node) {
+      throw createFsError('ENOENT', `ENOENT: no such file or directory, chmod '${path}'`)
+    }
+    // Preserve the file type bits (high bits) and update permission bits
+    const typeBits = node.mode & 0o170000
+    node.mode = typeBits | (mode & 0o777)
+  }
+
+  /**
+   * Close a file descriptor and release associated resources.
+   * Flushes any pending writes to storage before closing.
+   * @param fd - File descriptor to close
+   * @throws {NodeJS.ErrnoException} EBADF if fd is not a valid open file descriptor
+   */
+  close(fd: number): void {
+    this.log('close', fd)
+    const openFile = this.files.get(fd)
+    if (!openFile) {
+      throw createFsError('EBADF', `EBADF: bad file descriptor, close '${fd}'`)
+    }
+    // Flush pending writes and close the file
+    // Note: We fire-and-forget here since PGLite expects synchronous close.
+    // Errors are logged but not propagated; use syncToFs() for guaranteed durability.
+    void openFile.file.xClose().catch((err: unknown) => {
+      this.log('Error closing file:', err)
+    })
+    this.files.delete(fd)
+  }
+
+  /**
+   * Get file stats by file descriptor.
+   * @param fd - Open file descriptor
+   * @returns File stats structure
+   * @throws {NodeJS.ErrnoException} EBADF if fd is not a valid open file descriptor
+   */
+  fstat(fd: number): FsStats {
+    this.log('fstat', fd)
+    const openFile = this.files.get(fd)
+    if (!openFile) {
+      throw createFsError('EBADF', `EBADF: bad file descriptor, fstat '${fd}'`)
+    }
+
+    const node = this.inMemoryNodes.get(openFile.path)
+    const now = Date.now()
+
+    // Use in-memory node size if available, otherwise fall back to DOVFSFile size
+    const size = node?.size ?? openFile.file.size
+
+    return {
+      dev: 0,
+      ino: 0,
+      mode: node?.mode ?? 0o100644,
+      nlink: 1,
+      uid: 0,
+      gid: 0,
+      rdev: 0,
+      size,
+      blksize: 4096,
+      blocks: Math.ceil(size / 512),
+      atime: node?.accessed ?? now,
+      mtime: node?.modified ?? now,
+      ctime: node?.created ?? now,
+    }
+  }
+
+  /**
+   * Get file stats by path.
+   * Note: This implementation does not follow symlinks (same as lstat behavior).
+   * @param path - Absolute path to the file or directory
+   * @returns File stats structure
+   * @throws {NodeJS.ErrnoException} ENOENT if path does not exist
+   */
+  lstat(path: string): FsStats {
+    this.log('lstat', path)
+    const node = this.inMemoryNodes.get(path)
+
+    if (!node) {
+      throw createFsError('ENOENT', `ENOENT: no such file or directory, lstat '${path}'`)
+    }
+
+    return {
+      dev: 0,
+      ino: 0,
+      mode: node.mode,
+      nlink: 1,
+      uid: 0,
+      gid: 0,
+      rdev: 0,
+      size: node.size,
+      blksize: 4096,
+      blocks: Math.ceil(node.size / 512),
+      atime: node.accessed,
+      mtime: node.modified,
+      ctime: node.created,
+    }
+  }
+
+  /**
+   * Create a directory.
+   * @param path - Absolute path for the new directory
+   * @param options - Optional configuration
+   * @param options.recursive - If true, create parent directories as needed (like mkdir -p)
+   * @param options.mode - Directory permissions (default: 0o755)
+   * @throws {NodeJS.ErrnoException} ENOENT if parent directory does not exist (non-recursive)
+   * @throws {NodeJS.ErrnoException} EEXIST if directory already exists (non-recursive)
+   */
+  mkdir(path: string, options?: { recursive?: boolean; mode?: number }): void {
+    this.log('mkdir', path, options)
+    const mode = options?.mode
+
+    if (options?.recursive) {
+      // Create all directories in the path
+      const parts = path.split('/').filter(p => p !== '')
+      let currentPath = ''
+      for (let i = 0; i < parts.length; i++) {
+        currentPath += '/' + parts[i]
+        if (!this.inMemoryNodes.has(currentPath)) {
+          // Only apply custom mode to the final directory
+          const dirMode = i === parts.length - 1 ? mode : undefined
+          this.getOrCreateDir(currentPath, dirMode)
+        }
+      }
+    } else {
+      // Check parent exists
+      const parts = path.split('/').filter(p => p !== '')
+      const parentPath = '/' + parts.slice(0, -1).join('/')
+      if (parts.length > 1 && !this.inMemoryNodes.has(parentPath)) {
+        throw createFsError('ENOENT', `ENOENT: no such file or directory, mkdir '${path}'`)
+      }
+
+      // Check if already exists
+      if (this.inMemoryNodes.has(path)) {
+        throw createFsError('EEXIST', `EEXIST: file already exists, mkdir '${path}'`)
+      }
+
+      this.getOrCreateDir(path, mode)
+    }
+  }
+
+  /**
+   * Open a file and return a file descriptor.
+   *
+   * Note: This method initiates async file opening but returns synchronously
+   * as required by PGLite's interface. The file is opened lazily - the async
+   * open operation runs in the background, and any errors are logged.
+   * Use syncToFs() to ensure all operations are complete.
+   *
+   * @param path - Absolute path to the file
+   * @param flags - Open mode: 'r' (read), 'w'/'w+' (write/create), 'a' (append), 'r+' (read/write)
+   * @param mode - File permissions when creating (default: 0o644)
+   * @returns File descriptor (integer >= 3)
+   * @throws {NodeJS.ErrnoException} ENOENT if file doesn't exist in read mode
+   */
+  open(path: string, flags?: string, mode?: number): number {
+    this.log('open', path, flags, mode)
+
+    // Parse flags string to SQLITE open flags and internal mode flags
+    let openFlags = SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE
+    let modeFlags = FILE_MODE_READ | FILE_MODE_WRITE
+    const isReadOnly = flags === 'r'
+    const requiresExisting = flags === 'r' || flags === 'r+'
+
+    if (flags === 'r') {
+      openFlags = SQLITE_OPEN_READONLY
+      modeFlags = FILE_MODE_READ
+    } else if (flags === 'w' || flags === 'w+') {
+      openFlags = SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE
+      modeFlags = FILE_MODE_READ | FILE_MODE_WRITE
+    } else if (flags === 'a') {
+      openFlags = SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE
+      modeFlags = FILE_MODE_WRITE
+    } else if (flags === 'r+') {
+      openFlags = SQLITE_OPEN_READWRITE
+      modeFlags = FILE_MODE_READ | FILE_MODE_WRITE
+    }
+
+    // Check if file exists for read modes
+    const existingNode = this.inMemoryNodes.get(path)
+    if (requiresExisting && !existingNode) {
+      throw createFsError('ENOENT', `ENOENT: no such file or directory, open '${path}'`)
+    }
+
+    // Ensure parent directory exists for write modes
+    if (!isReadOnly) {
+      const parts = path.split('/').filter(p => p !== '')
+      if (parts.length > 1) {
+        const parentPath = '/' + parts.slice(0, -1).join('/')
+        if (!this.inMemoryNodes.has(parentPath)) {
+          this.mkdir(parentPath, { recursive: true })
+        }
+      }
+    }
+
+    // Create DOVFS file handle
+    const file = new DOVFSFile(this.storage, path, openFlags)
+
+    // Assign file descriptor
+    const fd = this.nextFd++
+    this.files.set(fd, {
+      path,
+      file,
+      position: 0,
+      flags: openFlags,
+      modeFlags,
+    })
+
+    // Ensure node exists in memory with the provided mode
+    if (!existingNode) {
+      this.getOrCreateFile(path, undefined, mode)
+    }
+
+    // Open the file asynchronously
+    // Note: PGLite expects synchronous return, so we fire-and-forget here.
+    // The file handle tracks its own open state.
+    void file.xOpen().catch((err: unknown) => {
+      this.log('Error opening file:', err)
+    })
+
+    return fd
+  }
+
+  /**
+   * Read directory contents.
+   * @param path - Absolute path to the directory
+   * @returns Array of entry names (not full paths)
+   * @throws {NodeJS.ErrnoException} ENOENT if path does not exist
+   * @throws {NodeJS.ErrnoException} ENOTDIR if path is not a directory
+   */
+  readdir(path: string): string[] {
+    this.log('readdir', path)
+    const node = this.inMemoryNodes.get(path)
+
+    if (!node) {
+      throw createFsError('ENOENT', `ENOENT: no such file or directory, scandir '${path}'`)
+    }
+
+    if (!node.isDirectory) {
+      throw createFsError('ENOTDIR', `ENOTDIR: not a directory, scandir '${path}'`)
+    }
+
+    return Array.from(node.children?.keys() ?? [])
+  }
+
+  /**
+   * Read data from a file descriptor into a buffer.
+   * @param fd - Open file descriptor
+   * @param buffer - Buffer to read data into
+   * @param offset - Offset within buffer to start writing
+   * @param length - Maximum number of bytes to read
+   * @param position - File position to read from
+   * @returns Number of bytes actually read (0 at EOF)
+   * @throws {NodeJS.ErrnoException} EBADF if fd is not a valid open file descriptor
+   */
+  read(
+    fd: number,
+    buffer: Uint8Array,
+    offset: number,
+    length: number,
+    position: number
+  ): number {
+    this.log('read', fd, offset, length, position)
+
+    const openFile = this.files.get(fd)
+    if (!openFile) {
+      throw createFsError('EBADF', `EBADF: bad file descriptor, read '${fd}'`)
+    }
+
+    // Use in-memory data if available
+    const node = this.inMemoryNodes.get(openFile.path)
+    if (node?.data) {
+      const start = position
+      const end = Math.min(start + length, node.data.length)
+      const bytesToRead = end - start
+
+      if (bytesToRead <= 0) return 0
+
+      buffer.set(node.data.subarray(start, end), offset)
+      return bytesToRead
+    }
+
+    // No data in memory - return 0 (EOF)
+    return 0
+  }
+
+  /**
+   * Rename a file or directory.
+   * Moves the entry from oldPath to newPath, updating all internal references.
+   * For directories, also updates all children paths recursively.
+   * @param oldPath - Current absolute path
+   * @param newPath - New absolute path
+   * @throws {FsError} ENOENT if oldPath does not exist
+   */
+  rename(oldPath: string, newPath: string): void {
+    this.log('rename', oldPath, newPath)
+
+    const node = this.inMemoryNodes.get(oldPath)
+    if (!node) {
+      throw createFsError('ENOENT', `ENOENT: no such file or directory, rename '${oldPath}' -> '${newPath}'`)
+    }
+
+    // If destination exists, remove it first (overwrite behavior)
+    const existingDest = this.inMemoryNodes.get(newPath)
+    if (existingDest) {
+      if (existingDest.isDirectory) {
+        // Can only overwrite empty directories
+        if (existingDest.children && existingDest.children.size > 0) {
+          throw createFsError('ENOTEMPTY', `ENOTEMPTY: directory not empty, rename '${oldPath}' -> '${newPath}'`)
+        }
+      }
+      // Remove the destination
+      this.inMemoryNodes.delete(newPath)
+      const destParts = newPath.split('/').filter(p => p !== '')
+      const destParentPath = '/' + destParts.slice(0, -1).join('/')
+      const destParent = this.inMemoryNodes.get(destParentPath || '/')
+      if (destParent?.children) {
+        destParent.children.delete(destParts[destParts.length - 1])
+      }
+    }
+
+    // Collect all nodes to rename (node + descendants for directories)
+    const nodesToRename: Array<{ oldPath: string; node: FileNode }> = []
+
+    const collectNodes = (currentPath: string, currentNode: FileNode): void => {
+      nodesToRename.push({ oldPath: currentPath, node: currentNode })
+      if (currentNode.isDirectory && currentNode.children) {
+        for (const [childName, childNode] of currentNode.children) {
+          const childOldPath = currentPath + '/' + childName
+          collectNodes(childOldPath, childNode)
+        }
+      }
+    }
+    collectNodes(oldPath, node)
+
+    // Remove from old parent's children first
+    const oldParts = oldPath.split('/').filter(p => p !== '')
+    const oldParentPath = '/' + oldParts.slice(0, -1).join('/')
+    const oldParent = this.inMemoryNodes.get(oldParentPath || '/')
+    if (oldParent?.children) {
+      oldParent.children.delete(oldParts[oldParts.length - 1])
+    }
+
+    // Update all nodes with new paths
+    for (const { oldPath: nodeOldPath, node: n } of nodesToRename) {
+      this.inMemoryNodes.delete(nodeOldPath)
+
+      // Calculate new path by replacing oldPath prefix with newPath
+      const relativePath = nodeOldPath.slice(oldPath.length)
+      const nodeNewPath = newPath + relativePath
+
+      const newParts = nodeNewPath.split('/').filter(p => p !== '')
+      n.name = newParts[newParts.length - 1] || ''
+      n.path = nodeNewPath
+
+      this.inMemoryNodes.set(nodeNewPath, n)
+    }
+
+    // Add to new parent's children
+    const parts = newPath.split('/').filter(p => p !== '')
+    const newParentPath = '/' + parts.slice(0, -1).join('/')
+    let newParent = this.inMemoryNodes.get(newParentPath || '/')
+
+    // Ensure new parent exists
+    if (!newParent && newParentPath !== '') {
+      this.mkdir(newParentPath, { recursive: true })
+      newParent = this.inMemoryNodes.get(newParentPath)
+    }
+
+    if (newParent?.children) {
+      newParent.children.set(node.name, node)
+    }
+  }
+
+  /**
+   * Remove an empty directory.
+   * @param path - Absolute path to the directory
+   * @throws {FsError} ENOENT if path does not exist
+   * @throws {FsError} ENOTDIR if path is not a directory
+   * @throws {FsError} ENOTEMPTY if directory is not empty
+   * @throws {FsError} EINVAL if trying to remove root directory
+   */
+  rmdir(path: string): void {
+    this.log('rmdir', path)
+
+    // Cannot remove root directory
+    if (path === '/') {
+      throw createFsError('EINVAL', `EINVAL: invalid argument, rmdir '${path}'`)
+    }
+
+    const node = this.inMemoryNodes.get(path)
+    if (!node) {
+      throw createFsError('ENOENT', `ENOENT: no such file or directory, rmdir '${path}'`)
+    }
+
+    if (!node.isDirectory) {
+      throw createFsError('ENOTDIR', `ENOTDIR: not a directory, rmdir '${path}'`)
+    }
+
+    if (node.children && node.children.size > 0) {
+      throw createFsError('ENOTEMPTY', `ENOTEMPTY: directory not empty, rmdir '${path}'`)
+    }
+
+    // Remove from parent's children
+    const parts = path.split('/').filter(p => p !== '')
+    const parentPath = '/' + parts.slice(0, -1).join('/')
+    const parent = this.inMemoryNodes.get(parentPath || '/')
+    if (parent?.children) {
+      parent.children.delete(node.name)
+    }
+
+    this.inMemoryNodes.delete(path)
+  }
+
+  /**
+   * Truncate a file to a specified length.
+   * If length is less than current size, data is removed.
+   * If length is greater than current size, the file is extended with zeros.
+   * @param path - Absolute path to the file
+   * @param len - New file length in bytes
+   * @throws {FsError} ENOENT if path does not exist
+   * @throws {FsError} EISDIR if path is a directory
+   */
+  truncate(path: string, len: number): void {
+    this.log('truncate', path, len)
+
+    const node = this.inMemoryNodes.get(path)
+    if (!node) {
+      throw createFsError('ENOENT', `ENOENT: no such file or directory, truncate '${path}'`)
+    }
+
+    if (node.isDirectory) {
+      throw createFsError('EISDIR', `EISDIR: illegal operation on a directory, truncate '${path}'`)
+    }
+
+    if (node.data) {
+      if (len < node.data.length) {
+        // Shrink: create smaller array
+        node.data = node.data.slice(0, len)
+      } else if (len > node.data.length) {
+        // Grow: create larger array, copy existing data
+        const newData = new Uint8Array(len)
+        newData.set(node.data)
+        node.data = newData
+      }
+      node.size = len
+    } else {
+      // No existing data - create zero-filled array
+      node.data = new Uint8Array(len)
+      node.size = len
+    }
+
+    node.modified = Date.now()
+  }
+
+  /**
+   * Remove a file.
+   * @param path - Absolute path to the file
+   * @throws {FsError} ENOENT if path does not exist
+   * @throws {FsError} EISDIR if path is a directory (use rmdir instead)
+   */
+  unlink(path: string): void {
+    this.log('unlink', path)
+
+    const node = this.inMemoryNodes.get(path)
+    if (!node) {
+      throw createFsError('ENOENT', `ENOENT: no such file or directory, unlink '${path}'`)
+    }
+
+    if (node.isDirectory) {
+      throw createFsError('EISDIR', `EISDIR: illegal operation on a directory, unlink '${path}'`)
+    }
+
+    // Remove from parent's children
+    const parts = path.split('/').filter(p => p !== '')
+    const parentPath = '/' + parts.slice(0, -1).join('/')
+    const parent = this.inMemoryNodes.get(parentPath || '/')
+    if (parent?.children) {
+      parent.children.delete(node.name)
+    }
+
+    this.inMemoryNodes.delete(path)
+  }
+
+  /**
+   * Update file access and modification times.
+   * @param path - Absolute path to the file or directory
+   * @param atime - Access time in milliseconds since epoch
+   * @param mtime - Modification time in milliseconds since epoch
+   * @throws {FsError} ENOENT if path does not exist
+   */
+  utimes(path: string, atime: number, mtime: number): void {
+    this.log('utimes', path, atime, mtime)
+
+    const node = this.inMemoryNodes.get(path)
+    if (!node) {
+      throw createFsError('ENOENT', `ENOENT: no such file or directory, utimes '${path}'`)
+    }
+    node.accessed = atime
+    node.modified = mtime
+  }
+
+  /**
+   * Write a file directly.
+   * @param path - Absolute path to the file
+   * @param data - Data to write (string or Uint8Array)
+   * @param options - Optional configuration
+   * @param options.encoding - Text encoding (default: utf-8)
+   * @param options.mode - File permissions (default: 0o644)
+   * @param options.flag - Open flags (default: 'w')
+   */
+  writeFile(
+    path: string,
+    data: string | Uint8Array,
+    options?: { encoding?: string; mode?: number; flag?: string }
+  ): void {
+    this.log('writeFile', path, options)
+
+    // Ensure parent directory exists
+    const parts = path.split('/').filter(p => p !== '')
+    if (parts.length > 1) {
+      const parentPath = '/' + parts.slice(0, -1).join('/')
+      if (!this.inMemoryNodes.has(parentPath)) {
+        this.mkdir(parentPath, { recursive: true })
+      }
+    }
+
+    // Convert string to Uint8Array if needed
+    let bytes: Uint8Array
+    if (typeof data === 'string') {
+      bytes = new TextEncoder().encode(data)
+    } else {
+      bytes = data
+    }
+
+    this.getOrCreateFile(path, bytes, options?.mode)
+  }
+
+  /**
+   * Write to a file descriptor.
+   * @param fd - Open file descriptor
+   * @param buffer - Buffer containing data to write
+   * @param offset - Offset within buffer to start reading
+   * @param length - Number of bytes to write
+   * @param position - File position to write at
+   * @returns Number of bytes written
+   * @throws {NodeJS.ErrnoException} EBADF if fd is invalid or opened read-only
+   */
+  write(
+    fd: number,
+    buffer: Uint8Array,
+    offset: number,
+    length: number,
+    position: number
+  ): number {
+    this.log('write', fd, offset, length, position)
+
+    const openFile = this.files.get(fd)
+    if (!openFile) {
+      throw createFsError('EBADF', `EBADF: bad file descriptor, write '${fd}'`)
+    }
+
+    // Check if file was opened for writing
+    if (!(openFile.modeFlags & FILE_MODE_WRITE)) {
+      throw createFsError('EBADF', `EBADF: bad file descriptor (read-only), write '${fd}'`)
+    }
+
+    // Get or create the node
+    let node = this.inMemoryNodes.get(openFile.path)
+    if (!node) {
+      node = this.getOrCreateFile(openFile.path)
+    }
+
+    // Prepare the data to write
+    const dataToWrite = buffer.subarray(offset, offset + length)
+
+    // Expand or create data buffer if needed
+    const requiredSize = position + length
+    if (!node.data || node.data.length < requiredSize) {
+      const newData = new Uint8Array(requiredSize)
+      if (node.data) {
+        newData.set(node.data)
+      }
+      node.data = newData
+    }
+
+    // Write the data
+    node.data.set(dataToWrite, position)
+    node.size = Math.max(node.size, requiredSize)
+    node.modified = Date.now()
+
+    return length
+  }
+
+  /**
+   * Sync all open files to storage
+   * @throws If storage operations fail
+   */
+  async syncToFs(relaxedDurability?: boolean): Promise<void> {
+    this.log('syncToFs', relaxedDurability)
+
+    // Write all in-memory file data to DOVFS
+    // Collect all errors and report them
+    const errors: Error[] = []
+
+    for (const [path, node] of this.inMemoryNodes) {
+      if (!node.isDirectory && node.data && node.data.length > 0) {
+        try {
+          const file = new DOVFSFile(
+            this.storage,
+            path,
+            SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE
+          )
+          const result = await file.xOpen()
+          if (result !== SQLITE_OK) {
+            // xOpen failed - check for original error or create descriptive one
+            if (file.lastError) {
+              errors.push(file.lastError)
+            } else {
+              errors.push(new Error(`Failed to open file ${path}: SQLITE error ${result}`))
+            }
+            continue
+          }
+          const writeResult = await file.xWrite(node.data, 0)
+          if (writeResult !== SQLITE_OK) {
+            if (file.lastError) {
+              errors.push(file.lastError)
+            } else {
+              errors.push(new Error(`Failed to write file ${path}: SQLITE error ${writeResult}`))
+            }
+            continue
+          }
+          const syncResult = await file.xSync(0)
+          if (syncResult !== SQLITE_OK) {
+            if (file.lastError) {
+              errors.push(file.lastError)
+            } else {
+              errors.push(new Error(`Failed to sync file ${path}: SQLITE error ${syncResult}`))
+            }
+            continue
+          }
+          await file.xClose()
+        } catch (error) {
+          errors.push(error instanceof Error ? error : new Error(String(error)))
+        }
+      }
+    }
+
+    // If any errors occurred, throw the first one
+    if (errors.length > 0) {
+      throw errors[0]
+    }
+  }
+
+  /**
+   * Initial sync from storage
+   */
+  async initialSyncFs(): Promise<void> {
+    this.log('initialSyncFs')
+
+    // Load existing files from DOVFS
+    const files = await this.dovfs.listFiles()
+    for (const path of files) {
+      const info = await this.dovfs.getFileInfo(path)
+      if (info) {
+        // Create directory structure
+        const parts = path.split('/').filter(p => p !== '')
+        let currentPath = ''
+        for (let i = 0; i < parts.length - 1; i++) {
+          currentPath += '/' + parts[i]
+          if (!this.inMemoryNodes.has(currentPath)) {
+            this.getOrCreateDir(currentPath)
+          }
+        }
+
+        // Load file data
+        const file = new DOVFSFile(this.storage, path, SQLITE_OPEN_READONLY)
+        const result = await file.xOpen()
+        if (result === SQLITE_OK && info.size > 0) {
+          const data = new Uint8Array(info.size)
+          await file.xRead(data, 0)
+          await file.xClose()
+          this.getOrCreateFile(path, data)
+        } else {
+          this.getOrCreateFile(path, new Uint8Array(0))
+        }
+      }
+    }
+  }
+
+  /**
+   * Close the filesystem
+   */
+  async closeFs(): Promise<void> {
+    this.log('closeFs')
+
+    // Close all open files
+    for (const [fd] of this.files) {
+      this.close(fd)
+    }
+
+    // Final sync
+    await this.syncToFs()
+  }
+}
+
+/**
+ * Create a DOVFSAdapter instance
+ */
+export function createDOVFSAdapter(
+  storage: DOVFSStorage,
+  dataDir?: string,
+  options?: { debug?: boolean }
+): DOVFSAdapter {
+  return new DOVFSAdapter(storage, dataDir, options)
+}