sandlot 0.1.0

package/src/fs.ts

@@ -0,0 +1,935 @@
+import type {
+  IFileSystem,
+  FsEntry,
+  FsStat,
+  MkdirOptions,
+  RmOptions,
+  CpOptions,
+  FileContent,
+  InitialFiles,
+  FileInit,
+} from "just-bash/browser";
+
+/**
+ * Supported buffer encodings
+ */
+type BufferEncoding = "utf8" | "utf-8" | "ascii" | "binary" | "base64" | "hex" | "latin1";
+
+/**
+ * Options for reading files
+ */
+interface ReadFileOptions {
+  encoding?: BufferEncoding | null;
+}
+
+/**
+ * Options for writing files
+ */
+interface WriteFileOptions {
+  encoding?: BufferEncoding;
+}
+
+/**
+ * Directory entry with type information (similar to Node's Dirent)
+ */
+interface DirentEntry {
+  name: string;
+  isFile: boolean;
+  isDirectory: boolean;
+  isSymbolicLink: boolean;
+}
+
+const DEFAULT_FILE_MODE = 0o644;
+const DEFAULT_DIR_MODE = 0o755;
+const DEFAULT_SYMLINK_MODE = 0o777;
+const DEFAULT_MAX_SIZE_BYTES = 50 * 1024 * 1024; // 50MB default limit
+
+/**
+ * Options for creating an IndexedDbFs instance
+ */
+export interface IndexedDbFsOptions {
+  /** Database name in IndexedDB */
+  dbName?: string;
+  /** Maximum total size in bytes (default: 50MB) */
+  maxSizeBytes?: number;
+  /** Initial files to populate (only used if DB is empty) */
+  initialFiles?: InitialFiles;
+}
+
+/**
+ * In-memory filesystem with IndexedDB persistence.
+ * All operations are fast (in-memory), persistence is manual via save().
+ */
+export class IndexedDbFs implements IFileSystem {
+  private entries: Map<string, FsEntry>;
+  private db: IDBDatabase | null = null;
+  private dbName: string;
+  private maxSizeBytes: number;
+  private dirty = false;
+
+  private constructor(
+    entries: Map<string, FsEntry>,
+    db: IDBDatabase | null,
+    dbName: string,
+    maxSizeBytes: number
+  ) {
+    this.entries = entries;
+    this.db = db;
+    this.dbName = dbName;
+    this.maxSizeBytes = maxSizeBytes;
+  }
+
+  /**
+   * Create and initialize a new IndexedDbFs instance
+   */
+  static async create(options: IndexedDbFsOptions = {}): Promise<IndexedDbFs> {
+    const dbName = options.dbName ?? "sandlot-fs";
+    const maxSizeBytes = options.maxSizeBytes ?? DEFAULT_MAX_SIZE_BYTES;
+
+    const db = await IndexedDbFs.openDatabase(dbName);
+    const entries = await IndexedDbFs.loadEntries(db);
+
+    // If empty and initialFiles provided, populate
+    if (entries.size === 0) {
+      // Always ensure root exists
+      entries.set("/", {
+        type: "directory",
+        mode: DEFAULT_DIR_MODE,
+        mtime: new Date(),
+      });
+
+      if (options.initialFiles) {
+        for (const [path, value] of Object.entries(options.initialFiles)) {
+          const normalizedPath = IndexedDbFs.normalizePath(path);
+          const init = IndexedDbFs.parseFileInit(value);
+
+          // Ensure parent directories exist
+          IndexedDbFs.ensureParentDirs(entries, normalizedPath);
+
+          entries.set(normalizedPath, {
+            type: "file",
+            content: init.content,
+            mode: init.mode ?? DEFAULT_FILE_MODE,
+            mtime: init.mtime ?? new Date(),
+          });
+        }
+      }
+    }
+
+    const fs = new IndexedDbFs(entries, db, dbName, maxSizeBytes);
+    return fs;
+  }
+
+  /**
+   * Create an in-memory only instance (no IndexedDB)
+   */
+  static createInMemory(options: Omit<IndexedDbFsOptions, "dbName"> = {}): IndexedDbFs {
+    const maxSizeBytes = options.maxSizeBytes ?? DEFAULT_MAX_SIZE_BYTES;
+    const entries = new Map<string, FsEntry>();
+
+    // Always ensure root exists
+    entries.set("/", {
+      type: "directory",
+      mode: DEFAULT_DIR_MODE,
+      mtime: new Date(),
+    });
+
+    if (options.initialFiles) {
+      for (const [path, value] of Object.entries(options.initialFiles)) {
+        const normalizedPath = IndexedDbFs.normalizePath(path);
+        const init = IndexedDbFs.parseFileInit(value);
+
+        // Ensure parent directories exist
+        IndexedDbFs.ensureParentDirs(entries, normalizedPath);
+
+        entries.set(normalizedPath, {
+          type: "file",
+          content: init.content,
+          mode: init.mode ?? DEFAULT_FILE_MODE,
+          mtime: init.mtime ?? new Date(),
+        });
+      }
+    }
+
+    return new IndexedDbFs(entries, null, "", maxSizeBytes);
+  }
+
+  // ============ Persistence Methods ============
+
+  /**
+   * Save all entries to IndexedDB
+   * @returns true if saved, false if no db or not dirty
+   */
+  async save(): Promise<boolean> {
+    if (!this.db || !this.dirty) {
+      return false;
+    }
+
+    const tx = this.db.transaction("entries", "readwrite");
+    const store = tx.objectStore("entries");
+
+    // Clear and rewrite all entries
+    await this.promisifyRequest(store.clear());
+
+    for (const [path, entry] of this.entries) {
+      store.put({ path, entry: this.serializeEntry(entry) });
+    }
+
+    await this.promisifyTransaction(tx);
+    this.dirty = false;
+    return true;
+  }
+
+  /**
+   * Reload entries from IndexedDB, discarding unsaved changes
+   */
+  async reload(): Promise<void> {
+    if (!this.db) {
+      return;
+    }
+
+    this.entries = await IndexedDbFs.loadEntries(this.db);
+    this.dirty = false;
+  }
+
+  /**
+   * Check if there are unsaved changes
+   */
+  isDirty(): boolean {
+    return this.dirty;
+  }
+
+  /**
+   * Get approximate size of all stored data in bytes
+   */
+  getSize(): number {
+    let size = 0;
+    for (const [path, entry] of this.entries) {
+      size += path.length * 2; // UTF-16
+      if (entry.type === "file") {
+        if (typeof entry.content === "string") {
+          size += entry.content.length * 2;
+        } else {
+          size += entry.content.byteLength;
+        }
+      }
+    }
+    return size;
+  }
+
+  /**
+   * Close the database connection
+   */
+  close(): void {
+    if (this.db) {
+      this.db.close();
+      this.db = null;
+    }
+  }
+
+  // ============ IFileSystem Implementation ============
+
+  async readFile(
+    path: string,
+    options?: ReadFileOptions | BufferEncoding
+  ): Promise<string> {
+    const normalizedPath = this.normalizePath(path);
+    const entry = this.resolveSymlinks(normalizedPath);
+
+    if (!entry) {
+      throw new Error(`ENOENT: no such file or directory, open '${path}'`);
+    }
+    if (entry.type !== "file") {
+      throw new Error(`EISDIR: illegal operation on a directory, read '${path}'`);
+    }
+
+    const content = entry.content;
+    if (typeof content === "string") {
+      return content;
+    }
+
+    // Convert Uint8Array to string
+    const encoding = this.getEncoding(options) ?? "utf8";
+    return this.decodeBuffer(content, encoding);
+  }
+
+  async readFileBuffer(path: string): Promise<Uint8Array> {
+    const normalizedPath = this.normalizePath(path);
+    const entry = this.resolveSymlinks(normalizedPath);
+
+    if (!entry) {
+      throw new Error(`ENOENT: no such file or directory, open '${path}'`);
+    }
+    if (entry.type !== "file") {
+      throw new Error(`EISDIR: illegal operation on a directory, read '${path}'`);
+    }
+
+    const content = entry.content;
+    if (content instanceof Uint8Array) {
+      return content;
+    }
+
+    // Convert string to Uint8Array
+    return new TextEncoder().encode(content);
+  }
+
+  async writeFile(
+    path: string,
+    content: FileContent,
+    options?: WriteFileOptions | BufferEncoding
+  ): Promise<void> {
+    const normalizedPath = this.normalizePath(path);
+    this.checkSizeLimit(content);
+    this.ensureParentDirs(normalizedPath);
+
+    const existing = this.entries.get(normalizedPath);
+    if (existing && existing.type === "directory") {
+      throw new Error(`EISDIR: illegal operation on a directory, open '${path}'`);
+    }
+
+    this.entries.set(normalizedPath, {
+      type: "file",
+      content,
+      mode: existing?.mode ?? DEFAULT_FILE_MODE,
+      mtime: new Date(),
+    });
+    this.dirty = true;
+  }
+
+  async appendFile(
+    path: string,
+    content: FileContent,
+    options?: WriteFileOptions | BufferEncoding
+  ): Promise<void> {
+    const normalizedPath = this.normalizePath(path);
+    let existing: string | Uint8Array = "";
+
+    try {
+      existing = await this.readFile(normalizedPath);
+    } catch {
+      // File doesn't exist, will be created
+    }
+
+    const newContent =
+      typeof existing === "string" && typeof content === "string"
+        ? existing + content
+        : this.concatBuffers(
+          typeof existing === "string" ? new TextEncoder().encode(existing) : existing,
+          typeof content === "string" ? new TextEncoder().encode(content) : content
+        );
+
+    await this.writeFile(normalizedPath, newContent, options);
+  }
+
+  async exists(path: string): Promise<boolean> {
+    const normalizedPath = this.normalizePath(path);
+    return this.entries.has(normalizedPath);
+  }
+
+  async stat(path: string): Promise<FsStat> {
+    const normalizedPath = this.normalizePath(path);
+    const entry = this.resolveSymlinks(normalizedPath);
+
+    if (!entry) {
+      throw new Error(`ENOENT: no such file or directory, stat '${path}'`);
+    }
+
+    return this.entryToStat(entry);
+  }
+
+  async lstat(path: string): Promise<FsStat> {
+    const normalizedPath = this.normalizePath(path);
+    const entry = this.entries.get(normalizedPath);
+
+    if (!entry) {
+      throw new Error(`ENOENT: no such file or directory, lstat '${path}'`);
+    }
+
+    return this.entryToStat(entry);
+  }
+
+  async mkdir(path: string, options?: MkdirOptions): Promise<void> {
+    const normalizedPath = this.normalizePath(path);
+
+    if (this.entries.has(normalizedPath)) {
+      if (options?.recursive) {
+        return; // Already exists, ok with recursive
+      }
+      throw new Error(`EEXIST: file already exists, mkdir '${path}'`);
+    }
+
+    if (options?.recursive) {
+      this.ensureParentDirs(normalizedPath);
+    } else {
+      const parent = this.getParentPath(normalizedPath);
+      if (parent && !this.entries.has(parent)) {
+        throw new Error(`ENOENT: no such file or directory, mkdir '${path}'`);
+      }
+    }
+
+    this.entries.set(normalizedPath, {
+      type: "directory",
+      mode: DEFAULT_DIR_MODE,
+      mtime: new Date(),
+    });
+    this.dirty = true;
+  }
+
+  async readdir(path: string): Promise<string[]> {
+    const normalizedPath = this.normalizePath(path);
+    const entry = this.resolveSymlinks(normalizedPath);
+
+    if (!entry) {
+      throw new Error(`ENOENT: no such file or directory, scandir '${path}'`);
+    }
+    if (entry.type !== "directory") {
+      throw new Error(`ENOTDIR: not a directory, scandir '${path}'`);
+    }
+
+    const prefix = normalizedPath === "/" ? "/" : normalizedPath + "/";
+    const names: string[] = [];
+
+    for (const entryPath of this.entries.keys()) {
+      if (entryPath === normalizedPath) continue;
+      if (!entryPath.startsWith(prefix)) continue;
+
+      const relative = entryPath.slice(prefix.length);
+      if (!relative.includes("/")) {
+        names.push(relative);
+      }
+    }
+
+    return names.sort();
+  }
+
+  async readdirWithFileTypes(path: string): Promise<DirentEntry[]> {
+    const normalizedPath = this.normalizePath(path);
+    const entry = this.resolveSymlinks(normalizedPath);
+
+    if (!entry) {
+      throw new Error(`ENOENT: no such file or directory, scandir '${path}'`);
+    }
+    if (entry.type !== "directory") {
+      throw new Error(`ENOTDIR: not a directory, scandir '${path}'`);
+    }
+
+    const prefix = normalizedPath === "/" ? "/" : normalizedPath + "/";
+    const dirents: DirentEntry[] = [];
+
+    for (const [entryPath, e] of this.entries) {
+      if (entryPath === normalizedPath) continue;
+      if (!entryPath.startsWith(prefix)) continue;
+
+      const relative = entryPath.slice(prefix.length);
+      if (!relative.includes("/")) {
+        dirents.push({
+          name: relative,
+          isFile: e.type === "file",
+          isDirectory: e.type === "directory",
+          isSymbolicLink: e.type === "symlink",
+        });
+      }
+    }
+
+    return dirents.sort((a, b) => a.name.localeCompare(b.name));
+  }
+
+  async rm(path: string, options?: RmOptions): Promise<void> {
+    const normalizedPath = this.normalizePath(path);
+    const entry = this.entries.get(normalizedPath);
+
+    if (!entry) {
+      if (options?.force) return;
+      throw new Error(`ENOENT: no such file or directory, rm '${path}'`);
+    }
+
+    if (entry.type === "directory") {
+      const children = await this.readdir(normalizedPath);
+      if (children.length > 0 && !options?.recursive) {
+        throw new Error(`ENOTEMPTY: directory not empty, rm '${path}'`);
+      }
+
+      if (options?.recursive) {
+        // Delete all children
+        const prefix = normalizedPath === "/" ? "/" : normalizedPath + "/";
+        for (const entryPath of [...this.entries.keys()]) {
+          if (entryPath.startsWith(prefix)) {
+            this.entries.delete(entryPath);
+          }
+        }
+      }
+    }
+
+    this.entries.delete(normalizedPath);
+    this.dirty = true;
+  }
+
+  async cp(src: string, dest: string, options?: CpOptions): Promise<void> {
+    const srcPath = this.normalizePath(src);
+    const destPath = this.normalizePath(dest);
+    const entry = this.entries.get(srcPath);
+
+    if (!entry) {
+      throw new Error(`ENOENT: no such file or directory, cp '${src}'`);
+    }
+
+    if (entry.type === "directory") {
+      if (!options?.recursive) {
+        throw new Error(`EISDIR: cp called on directory without recursive '${src}'`);
+      }
+
+      // Copy directory and all children
+      this.ensureParentDirs(destPath);
+      this.entries.set(destPath, { ...entry, mtime: new Date() });
+
+      const prefix = srcPath === "/" ? "/" : srcPath + "/";
+      for (const [entryPath, e] of this.entries) {
+        if (entryPath.startsWith(prefix)) {
+          const relative = entryPath.slice(srcPath.length);
+          const newPath = destPath + relative;
+          this.entries.set(newPath, this.cloneEntry(e));
+        }
+      }
+    } else {
+      this.ensureParentDirs(destPath);
+      this.entries.set(destPath, this.cloneEntry(entry));
+    }
+
+    this.dirty = true;
+  }
+
+  async mv(src: string, dest: string): Promise<void> {
+    const srcPath = this.normalizePath(src);
+    const destPath = this.normalizePath(dest);
+    const entry = this.entries.get(srcPath);
+
+    if (!entry) {
+      throw new Error(`ENOENT: no such file or directory, mv '${src}'`);
+    }
+
+    this.ensureParentDirs(destPath);
+
+    if (entry.type === "directory") {
+      // Move directory and all children
+      const prefix = srcPath === "/" ? "/" : srcPath + "/";
+      const toMove: [string, FsEntry][] = [];
+
+      for (const [entryPath, e] of this.entries) {
+        if (entryPath === srcPath || entryPath.startsWith(prefix)) {
+          const relative = entryPath.slice(srcPath.length);
+          toMove.push([destPath + relative, e]);
+          this.entries.delete(entryPath);
+        }
+      }
+
+      for (const [newPath, e] of toMove) {
+        this.entries.set(newPath, e);
+      }
+    } else {
+      this.entries.delete(srcPath);
+      this.entries.set(destPath, entry);
+    }
+
+    this.dirty = true;
+  }
+
+  resolvePath(base: string, path: string): string {
+    if (path.startsWith("/")) {
+      return this.normalizePath(path);
+    }
+
+    const baseParts = base.split("/").filter(Boolean);
+    const pathParts = path.split("/").filter(Boolean);
+
+    for (const part of pathParts) {
+      if (part === ".") {
+        continue;
+      } else if (part === "..") {
+        baseParts.pop();
+      } else {
+        baseParts.push(part);
+      }
+    }
+
+    return "/" + baseParts.join("/");
+  }
+
+  getAllPaths(): string[] {
+    return [...this.entries.keys()].sort();
+  }
+
+  async chmod(path: string, mode: number): Promise<void> {
+    const normalizedPath = this.normalizePath(path);
+    const entry = this.entries.get(normalizedPath);
+
+    if (!entry) {
+      throw new Error(`ENOENT: no such file or directory, chmod '${path}'`);
+    }
+
+    entry.mode = mode;
+    entry.mtime = new Date();
+    this.dirty = true;
+  }
+
+  async symlink(target: string, linkPath: string): Promise<void> {
+    const normalizedLinkPath = this.normalizePath(linkPath);
+
+    if (this.entries.has(normalizedLinkPath)) {
+      throw new Error(`EEXIST: file already exists, symlink '${linkPath}'`);
+    }
+
+    this.ensureParentDirs(normalizedLinkPath);
+
+    this.entries.set(normalizedLinkPath, {
+      type: "symlink",
+      target,
+      mode: DEFAULT_SYMLINK_MODE,
+      mtime: new Date(),
+    });
+    this.dirty = true;
+  }
+
+  async link(existingPath: string, newPath: string): Promise<void> {
+    const srcPath = this.normalizePath(existingPath);
+    const destPath = this.normalizePath(newPath);
+
+    const entry = this.entries.get(srcPath);
+    if (!entry) {
+      throw new Error(`ENOENT: no such file or directory, link '${existingPath}'`);
+    }
+    if (entry.type !== "file") {
+      throw new Error(`EPERM: operation not permitted, link '${existingPath}'`);
+    }
+    if (this.entries.has(destPath)) {
+      throw new Error(`EEXIST: file already exists, link '${newPath}'`);
+    }
+
+    this.ensureParentDirs(destPath);
+
+    // Hard links share the same content reference
+    this.entries.set(destPath, {
+      type: "file",
+      content: entry.content,
+      mode: entry.mode,
+      mtime: new Date(),
+    });
+    this.dirty = true;
+  }
+
+  async readlink(path: string): Promise<string> {
+    const normalizedPath = this.normalizePath(path);
+    const entry = this.entries.get(normalizedPath);
+
+    if (!entry) {
+      throw new Error(`ENOENT: no such file or directory, readlink '${path}'`);
+    }
+    if (entry.type !== "symlink") {
+      throw new Error(`EINVAL: invalid argument, readlink '${path}'`);
+    }
+
+    return entry.target;
+  }
+
+  async realpath(path: string): Promise<string> {
+    const normalizedPath = this.normalizePath(path);
+    const parts = normalizedPath.split("/").filter(Boolean);
+    let resolved = "/";
+
+    for (const part of parts) {
+      // Build the next path component
+      resolved = resolved === "/" ? `/${part}` : `${resolved}/${part}`;
+
+      // Check if this path component exists
+      const entry = this.entries.get(resolved);
+      if (!entry) {
+        throw new Error(`ENOENT: no such file or directory, realpath '${path}'`);
+      }
+
+      // If it's a symlink, resolve it
+      if (entry.type === "symlink") {
+        const target = entry.target;
+        // If target is absolute, use it; otherwise resolve relative to parent
+        if (target.startsWith("/")) {
+          resolved = this.normalizePath(target);
+        } else {
+          const parent = this.getParentPath(resolved) ?? "/";
+          resolved = this.resolvePath(parent, target);
+        }
+
+        // Verify the resolved target exists
+        const targetEntry = this.entries.get(resolved);
+        if (!targetEntry) {
+          throw new Error(`ENOENT: no such file or directory, realpath '${path}'`);
+        }
+      }
+    }
+
+    return resolved;
+  }
+
+  async utimes(path: string, atime: Date, mtime: Date): Promise<void> {
+    const normalizedPath = this.normalizePath(path);
+    const entry = this.entries.get(normalizedPath);
+
+    if (!entry) {
+      throw new Error(`ENOENT: no such file or directory, utimes '${path}'`);
+    }
+
+    // Update mtime (atime is ignored as per interface docs, kept for API compatibility)
+    entry.mtime = mtime;
+    this.dirty = true;
+  }
+
+  // ============ Private Helpers ============
+
+  private normalizePath(path: string): string {
+    return IndexedDbFs.normalizePath(path);
+  }
+
+  private static normalizePath(path: string): string {
+    // Handle empty or relative paths
+    if (!path || path === ".") return "/";
+    if (!path.startsWith("/")) {
+      path = "/" + path;
+    }
+
+    const parts = path.split("/").filter(Boolean);
+    const normalized: string[] = [];
+
+    for (const part of parts) {
+      if (part === ".") continue;
+      if (part === "..") {
+        normalized.pop();
+      } else {
+        normalized.push(part);
+      }
+    }
+
+    return "/" + normalized.join("/");
+  }
+
+  private getParentPath(path: string): string | null {
+    if (path === "/") return null;
+    const lastSlash = path.lastIndexOf("/");
+    return lastSlash === 0 ? "/" : path.slice(0, lastSlash);
+  }
+
+  private ensureParentDirs(path: string): void {
+    IndexedDbFs.ensureParentDirs(this.entries, path);
+    this.dirty = true;
+  }
+
+  private static ensureParentDirs(entries: Map<string, FsEntry>, path: string): void {
+    const parts = path.split("/").filter(Boolean);
+    let current = "";
+
+    for (let i = 0; i < parts.length - 1; i++) {
+      current += "/" + parts[i];
+      if (!entries.has(current)) {
+        entries.set(current, {
+          type: "directory",
+          mode: DEFAULT_DIR_MODE,
+          mtime: new Date(),
+        });
+      }
+    }
+  }
+
+  private resolveSymlinks(path: string, maxDepth = 10): FsEntry | null {
+    let current = path;
+    let depth = 0;
+
+    while (depth < maxDepth) {
+      const entry = this.entries.get(current);
+      if (!entry) return null;
+      if (entry.type !== "symlink") return entry;
+
+      // Resolve symlink
+      const target = entry.target;
+      current = target.startsWith("/")
+        ? this.normalizePath(target)
+        : this.resolvePath(this.getParentPath(current) ?? "/", target);
+      depth++;
+    }
+
+    throw new Error(`ELOOP: too many levels of symbolic links, stat '${path}'`);
+  }
+
+  private entryToStat(entry: FsEntry): FsStat {
+    return {
+      isFile: entry.type === "file",
+      isDirectory: entry.type === "directory",
+      isSymbolicLink: entry.type === "symlink",
+      mode: entry.mode,
+      size: entry.type === "file" ? this.getContentSize(entry.content) : 0,
+      mtime: entry.mtime,
+    };
+  }
+
+  private getContentSize(content: string | Uint8Array): number {
+    if (typeof content === "string") {
+      return new TextEncoder().encode(content).byteLength;
+    }
+    return content.byteLength;
+  }
+
+  private cloneEntry(entry: FsEntry): FsEntry {
+    if (entry.type === "file") {
+      return {
+        type: "file",
+        content:
+          entry.content instanceof Uint8Array
+            ? new Uint8Array(entry.content)
+            : entry.content,
+        mode: entry.mode,
+        mtime: new Date(),
+      };
+    }
+    return { ...entry, mtime: new Date() };
+  }
+
+  private checkSizeLimit(content: FileContent): void {
+    const currentSize = this.getSize();
+    const newSize =
+      typeof content === "string"
+        ? content.length * 2
+        : content.byteLength;
+
+    if (currentSize + newSize > this.maxSizeBytes) {
+      throw new Error(
+        `ENOSPC: filesystem size limit exceeded (${this.maxSizeBytes} bytes)`
+      );
+    }
+  }
+
+  private getEncoding(
+    options?: ReadFileOptions | BufferEncoding
+  ): BufferEncoding | null {
+    if (!options) return null;
+    if (typeof options === "string") return options as BufferEncoding;
+    return options.encoding ?? null;
+  }
+
+  private decodeBuffer(buffer: Uint8Array, encoding: BufferEncoding): string {
+    if (encoding === "utf8" || encoding === "utf-8") {
+      return new TextDecoder("utf-8").decode(buffer);
+    }
+    if (encoding === "base64") {
+      let binary = "";
+      for (let i = 0; i < buffer.byteLength; i++) {
+        binary += String.fromCharCode(buffer[i]!);
+      }
+      return btoa(binary);
+    }
+    if (encoding === "hex") {
+      return Array.from(buffer)
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+    }
+    // Default to utf8 for other encodings
+    return new TextDecoder("utf-8").decode(buffer);
+  }
+
+  private concatBuffers(a: Uint8Array, b: Uint8Array): Uint8Array {
+    const result = new Uint8Array(a.byteLength + b.byteLength);
+    result.set(a, 0);
+    result.set(b, a.byteLength);
+    return result;
+  }
+
+  private static parseFileInit(value: FileContent | FileInit): FileInit {
+    if (typeof value === "string" || value instanceof Uint8Array) {
+      return { content: value };
+    }
+    return value;
+  }
+
+  // ============ IndexedDB Helpers ============
+
+  private static openDatabase(dbName: string): Promise<IDBDatabase> {
+    return new Promise((resolve, reject) => {
+      const request = indexedDB.open(dbName, 1);
+
+      request.onerror = () => reject(request.error);
+      request.onsuccess = () => resolve(request.result);
+
+      request.onupgradeneeded = (event) => {
+        const db = (event.target as IDBOpenDBRequest).result;
+        if (!db.objectStoreNames.contains("entries")) {
+          db.createObjectStore("entries", { keyPath: "path" });
+        }
+      };
+    });
+  }
+
+  private static async loadEntries(db: IDBDatabase): Promise<Map<string, FsEntry>> {
+    const tx = db.transaction("entries", "readonly");
+    const store = tx.objectStore("entries");
+
+    return new Promise((resolve, reject) => {
+      const request = store.getAll();
+      request.onerror = () => reject(request.error);
+      request.onsuccess = () => {
+        const entries = new Map<string, FsEntry>();
+        for (const record of request.result) {
+          entries.set(record.path, IndexedDbFs.deserializeEntry(record.entry));
+        }
+        resolve(entries);
+      };
+    });
+  }
+
+  private serializeEntry(entry: FsEntry): object {
+    if (entry.type === "file" && entry.content instanceof Uint8Array) {
+      return {
+        ...entry,
+        content: Array.from(entry.content),
+        contentType: "uint8array",
+        mtime: entry.mtime.toISOString(),
+      };
+    }
+    return {
+      ...entry,
+      mtime: entry.mtime.toISOString(),
+    };
+  }
+
+  private static deserializeEntry(data: any): FsEntry {
+    const mtime = new Date(data.mtime);
+
+    if (data.type === "file") {
+      let content = data.content;
+      if (data.contentType === "uint8array" && Array.isArray(content)) {
+        content = new Uint8Array(content);
+      }
+      return { type: "file", content, mode: data.mode, mtime };
+    }
+    if (data.type === "symlink") {
+      return { type: "symlink", target: data.target, mode: data.mode, mtime };
+    }
+    return { type: "directory", mode: data.mode, mtime };
+  }
+
+  private promisifyRequest<T>(request: IDBRequest<T>): Promise<T> {
+    return new Promise((resolve, reject) => {
+      request.onerror = () => reject(request.error);
+      request.onsuccess = () => resolve(request.result);
+    });
+  }
+
+  private promisifyTransaction(tx: IDBTransaction): Promise<void> {
+    return new Promise((resolve, reject) => {
+      tx.onerror = () => reject(tx.error);
+      tx.oncomplete = () => resolve();
+    });
+  }
+}
+
+/**
+ * Factory function matching the FileSystemFactory type
+ */
+export function createIndexedDbFs(initialFiles?: InitialFiles): IFileSystem {
+  // For sync factory usage, return in-memory version
+  // Use IndexedDbFs.create() for async with persistence
+  return IndexedDbFs.createInMemory({ initialFiles });
+}