@rljson/fs-agent 0.0.2

package/dist/fs-agent.js

@@ -0,0 +1,4049 @@
+import { BsMem as BsMem$1 } from "@rljson/bs";
+import { timeId, Route, iterateTablesSync, iterateTables, throwOnInvalidTableCfg, validateRljsonAgainstTableCfg, createTreesTableCfg } from "@rljson/rljson";
+import { stat, readFile, mkdir, writeFile, readdir, utimes, rm } from "fs/promises";
+import { dirname, join, sep } from "path";
+import { hip, hsh, hshBuffer } from "@rljson/hash";
+import { watch } from "fs";
+import { Db } from "@rljson/db";
+import { copy, equals, merge } from "@rljson/json";
+import { Readable } from "node:stream";
+class FsBlobAdapter {
+  _bs;
+  constructor(bs) {
+    this._bs = bs || new BsMem$1();
+  }
+  /**
+   * Gets the blob storage instance
+   */
+  get bs() {
+    return this._bs;
+  }
+  /**
+   * Converts a file to a blob and returns metadata
+   * @param filePath - Absolute path to the file
+   * @param options - Conversion options
+   * @returns File metadata including blob ID
+   */
+  async fileToBlob(filePath, options = {}) {
+    const bs = options.bs || this._bs;
+    const includePath = options.includePath !== false;
+    const stats = await stat(filePath);
+    const content = await readFile(filePath);
+    const blobProps = await bs.setBlob(content);
+    const name = filePath.split("/").pop() || filePath.split("\\").pop() || "";
+    const metadata = {
+      name,
+      blobId: blobProps.blobId,
+      size: stats.size,
+      mtime: stats.mtime.getTime(),
+      path: includePath ? filePath : ""
+    };
+    return metadata;
+  }
+  /**
+   * Converts multiple files to blobs
+   * @param filePaths - Array of absolute file paths
+   * @param options - Conversion options
+   * @returns Array of file metadata
+   */
+  async filesToBlobs(filePaths, options = {}) {
+    const results = [];
+    for (const filePath of filePaths) {
+      const metadata = await this.fileToBlob(filePath, options);
+      results.push(metadata);
+    }
+    return results;
+  }
+  /**
+   * Writes a file from a blob using metadata
+   * @param metadata - File metadata including blob ID
+   * @param targetPath - Target path where file should be written
+   * @param options - Conversion options
+   */
+  async blobToFile(metadata, targetPath, options = {}) {
+    const bs = options.bs || this._bs;
+    const createDirs = options.createDirs !== false;
+    const preserveMtime = options.preserveMtime !== false;
+    const blob = await bs.getBlob(metadata.blobId);
+    if (createDirs) {
+      const dir = dirname(targetPath);
+      await mkdir(dir, { recursive: true });
+    }
+    await writeFile(targetPath, blob.content);
+    if (preserveMtime && metadata.mtime) {
+      const { utimes: utimes2 } = await import("fs/promises");
+      const mtime = new Date(metadata.mtime);
+      await utimes2(targetPath, mtime, mtime);
+    }
+  }
+  /**
+   * Writes multiple files from blobs
+   * @param metadataList - Array of file metadata
+   * @param targetDir - Target directory where files should be written
+   * @param options - Conversion options
+   */
+  async blobsToFiles(metadataList, targetDir, options = {}) {
+    for (const metadata of metadataList) {
+      const targetPath = `${targetDir}/${metadata.name}`;
+      await this.blobToFile(metadata, targetPath, options);
+    }
+  }
+  /**
+   * Retrieves file content from blob storage
+   * @param blobId - Blob ID
+   * @returns File content as Buffer
+   */
+  async getFileContent(blobId) {
+    const blob = await this._bs.getBlob(blobId);
+    return blob.content;
+  }
+  /**
+   * Checks if a blob exists in storage
+   * @param blobId - Blob ID to check
+   * @returns True if blob exists
+   */
+  async hasBlob(blobId) {
+    return await this._bs.blobExists(blobId);
+  }
+  /**
+   * Creates an example instance for testing
+   */
+  static example() {
+    return new FsBlobAdapter();
+  }
+}
+class FsDbAdapter {
+  constructor(db, treeKey) {
+    this.db = db;
+    this.treeKey = treeKey;
+  }
+  /**
+   * Store a filesystem tree in the database
+   * @param fsTree - The filesystem tree to store
+   * @param options - Storage options
+   * @returns The root tree reference
+   */
+  async storeFsTree(fsTree, options = {}) {
+    const { notify = false } = options;
+    if (!fsTree) {
+      throw new Error("fsTree cannot be null or undefined");
+    }
+    if (!fsTree.rootHash || typeof fsTree.rootHash !== "string") {
+      throw new Error(
+        `Invalid rootHash: expected non-empty string, got ${typeof fsTree.rootHash}`
+      );
+    }
+    if (!fsTree.trees || !(fsTree.trees instanceof Map)) {
+      throw new Error(
+        `Invalid trees: expected Map, got ${typeof fsTree.trees}`
+      );
+    }
+    if (fsTree.trees.size === 0) {
+      throw new Error(
+        "Cannot store empty tree: trees Map must contain at least one node"
+      );
+    }
+    if (!fsTree.trees.has(fsTree.rootHash)) {
+      throw new Error(
+        `Root hash "${fsTree.rootHash}" not found in trees Map. The tree structure may be corrupted.`
+      );
+    }
+    const rootTree = fsTree.trees.get(fsTree.rootHash);
+    const trees = Array.from(fsTree.trees.values()).filter(
+      (tree) => tree._hash !== fsTree.rootHash
+    );
+    trees.push(rootTree);
+    const treeTable = {
+      _type: "trees",
+      _data: trees
+    };
+    try {
+      await this.db.core.import({
+        [this.treeKey]: treeTable
+      });
+    } catch (error) {
+      throw new Error(
+        `Failed to import tree data into database: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+    const treeRootRef = trees[trees.length - 1]._hash;
+    const historyRow = {
+      timeId: timeId(),
+      route: `/${this.treeKey}/${treeRootRef}`,
+      [`${this.treeKey}Ref`]: treeRootRef
+    };
+    const historyTable = {
+      _type: "insertHistory",
+      _data: [historyRow]
+    };
+    await this.db.core.import({
+      [`${this.treeKey}InsertHistory`]: historyTable
+    });
+    if (notify) {
+      const treeKeyRoute = Route.fromFlat(`/${this.treeKey}`);
+      this.db.notify.notify(treeKeyRoute, historyRow);
+    }
+    return treeRootRef;
+  }
+  /**
+   * Get the tree table key
+   */
+  getTreeKey() {
+    return this.treeKey;
+  }
+  /**
+   * Get the database instance
+   */
+  getDb() {
+    return this.db;
+  }
+}
+class FsScanner {
+  _rootPath;
+  _tree = null;
+  _watcher = null;
+  _changeCallbacks = [];
+  _options;
+  _bs;
+  _paused = false;
+  constructor(rootPath, options = {}) {
+    this._rootPath = rootPath;
+    this._options = {
+      ignore: options.ignore || ["node_modules", ".git", "dist", "coverage"],
+      maxDepth: options.maxDepth,
+      followSymlinks: options.followSymlinks ?? false,
+      bs: options.bs
+    };
+    this._bs = options.bs || new BsMem$1();
+  }
+  get tree() {
+    return this._tree;
+  }
+  get rootPath() {
+    return this._rootPath;
+  }
+  get bs() {
+    return this._bs;
+  }
+  async scan() {
+    try {
+      const stats = await stat(this._rootPath);
+      if (!stats.isDirectory()) {
+        throw new Error(
+          `Root path "${this._rootPath}" exists but is not a directory`
+        );
+      }
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        throw new Error(
+          `Root path "${this._rootPath}" does not exist. Cannot scan non-existent directory.`
+        );
+      }
+      throw new Error(
+        `Cannot access root path "${this._rootPath}": ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+    const trees = /* @__PURE__ */ new Map();
+    let rootTree;
+    try {
+      rootTree = await this._scanDirectory(this._rootPath, ".", 0, trees);
+    } catch (error) {
+      throw new Error(
+        `Failed to scan directory "${this._rootPath}": ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+    hip(rootTree);
+    const rootHashStr = rootTree._hash;
+    if (!rootHashStr) {
+      throw new Error(
+        "Failed to generate hash for root tree. Tree structure may be invalid."
+      );
+    }
+    trees.set(rootHashStr, rootTree);
+    this._tree = {
+      rootHash: rootHashStr,
+      trees
+    };
+    return this._tree;
+  }
+  async _scanDirectory(absolutePath, relativePath, depth, trees) {
+    const stats = await stat(absolutePath);
+    const entries = await readdir(absolutePath, { withFileTypes: true });
+    const childRefs = [];
+    for (const entry of entries) {
+      if (this._shouldIgnore(entry.name)) {
+        continue;
+      }
+      const childPath = join(absolutePath, entry.name);
+      const childRelPath = relativePath === "." ? entry.name : `${relativePath}/${entry.name}`;
+      if (entry.isSymbolicLink() && !this._options.followSymlinks) {
+        continue;
+      }
+      if (this._options.maxDepth !== void 0 && depth >= this._options.maxDepth) {
+        continue;
+      }
+      const childStats = await stat(childPath);
+      if (entry.isDirectory()) {
+        const childTree = await this._scanDirectory(
+          childPath,
+          childRelPath,
+          depth + 1,
+          trees
+        );
+        hip(childTree);
+        const childHashStr = childTree._hash;
+        trees.set(childHashStr, childTree);
+        childRefs.push(childHashStr);
+      } else if (entry.isFile()) {
+        let fileContent;
+        try {
+          fileContent = await readFile(childPath);
+        } catch (error) {
+          throw new Error(
+            `Failed to read file "${childRelPath}": ${error instanceof Error ? error.message : String(error)}`
+          );
+        }
+        let blobProps;
+        try {
+          blobProps = await this._bs.setBlob(fileContent);
+        } catch (error) {
+          throw new Error(
+            `Failed to store blob for file "${childRelPath}": ${error instanceof Error ? error.message : String(error)}`
+          );
+        }
+        if (!blobProps || !blobProps.blobId) {
+          throw new Error(
+            `Blob storage returned invalid blobId for file "${childRelPath}"`
+          );
+        }
+        const fileMeta = {
+          name: entry.name,
+          type: "file",
+          path: childPath,
+          relativePath: childRelPath,
+          size: childStats.size,
+          mtime: childStats.mtime.getTime(),
+          blobId: blobProps.blobId
+          // Link to content in Bs
+        };
+        const fileTree = {
+          id: entry.name,
+          isParent: false,
+          meta: fileMeta,
+          children: null
+        };
+        hip(fileTree);
+        const fileTreeHashStr = fileTree._hash;
+        trees.set(fileTreeHashStr, fileTree);
+        childRefs.push(fileTreeHashStr);
+      }
+    }
+    const dirName = relativePath === "." ? (
+      /* v8 ignore next -- @preserve */
+      this._rootPath.split(sep).pop() || ""
+    ) : (
+      /* v8 ignore next -- @preserve */
+      relativePath.split("/").pop() || ""
+    );
+    const dirMeta = {
+      name: dirName,
+      type: "directory",
+      path: absolutePath,
+      relativePath,
+      mtime: stats.mtime.getTime()
+    };
+    const dirTree = {
+      id: dirName,
+      isParent: childRefs.length > 0,
+      meta: dirMeta,
+      children: childRefs.length > 0 ? childRefs : null
+    };
+    return dirTree;
+  }
+  _shouldIgnore(name) {
+    if (!this._options.ignore) {
+      return false;
+    }
+    for (const pattern of this._options.ignore) {
+      if (name === pattern || name.startsWith(pattern)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  async watch() {
+    if (this._watcher) {
+      throw new Error("Already watching. Call stopWatch() first.");
+    }
+    if (!this._tree) {
+      await this.scan();
+    }
+    this._watcher = watch(
+      this._rootPath,
+      { recursive: true },
+      /* v8 ignore next -- @preserve */
+      async (eventType, filename) => {
+        if (!filename) return;
+        if (this._shouldIgnore(filename)) {
+          return;
+        }
+        await this._handleFileChange(eventType, filename);
+      }
+    );
+  }
+  async _handleFileChange(_eventType, filename) {
+    if (this._paused) {
+      return;
+    }
+    const relativePath = filename.replace(/\\/g, "/");
+    try {
+      await stat(join(this._rootPath, filename));
+      const existingTree = this._findTreeByPath(relativePath);
+      if (!existingTree) {
+        await this.scan();
+        await this._notifyChange({
+          type: "added",
+          path: relativePath
+        });
+      } else {
+        await this.scan();
+        await this._notifyChange({
+          type: "modified",
+          path: relativePath
+        });
+      }
+    } catch {
+      try {
+        await stat(this._rootPath);
+        await this.scan();
+        await this._notifyChange({
+          type: "deleted",
+          path: relativePath
+        });
+      } catch {
+        this.stopWatch();
+      }
+    }
+  }
+  _findTreeByPath(relativePath) {
+    if (!this._tree) return void 0;
+    for (const tree of this._tree.trees.values()) {
+      const meta = tree.meta;
+      if (meta && meta.relativePath === relativePath) {
+        return tree;
+      }
+    }
+    return void 0;
+  }
+  async _notifyChange(change) {
+    if (this._paused) {
+      return;
+    }
+    for (const callback of this._changeCallbacks) {
+      await callback(change);
+    }
+  }
+  onChange(callback) {
+    this._changeCallbacks.push(callback);
+  }
+  offChange(callback) {
+    this._changeCallbacks = this._changeCallbacks.filter(
+      (cb) => cb !== callback
+    );
+  }
+  stopWatch() {
+    if (this._watcher) {
+      this._watcher.close();
+      this._watcher = null;
+    }
+  }
+  /**
+   * Temporarily pause file change notifications
+   * Used to prevent loops when updating filesystem from external source
+   */
+  pauseWatch() {
+    this._paused = true;
+  }
+  /**
+   * Resume file change notifications
+   */
+  resumeWatch() {
+    this._paused = false;
+  }
+  getTreeByHash(treeHash) {
+    return this._tree?.trees.get(treeHash);
+  }
+  getTreeByPath(relativePath) {
+    return this._findTreeByPath(relativePath);
+  }
+  getAllTrees() {
+    if (!this._tree) {
+      return [];
+    }
+    return Array.from(this._tree.trees.values());
+  }
+  getChildren(treeHash) {
+    const tree = this.getTreeByHash(treeHash);
+    if (!tree || !tree.children) {
+      return [];
+    }
+    return tree.children.map((childHash) => this.getTreeByHash(childHash)).filter((t) => t !== void 0);
+  }
+  getRootTree() {
+    if (!this._tree) return void 0;
+    return this._tree.trees.get(this._tree.rootHash);
+  }
+  static example() {
+    return new FsScanner(process.cwd(), {
+      ignore: ["node_modules", ".git", "dist", "coverage"]
+    });
+  }
+}
+class FsAgent {
+  _scanner;
+  _adapter;
+  _rootPath;
+  _bs;
+  _db;
+  _treeKey;
+  _stopSync;
+  _stopSyncFromDb;
+  _lastSentRef;
+  constructor(rootPath, bs, options = {}) {
+    this._rootPath = rootPath;
+    this._bs = bs || new BsMem$1();
+    this._db = options.db;
+    this._treeKey = options.treeKey;
+    this._scanner = new FsScanner(rootPath, { ...options, bs: this._bs });
+    this._adapter = new FsBlobAdapter(this._bs);
+    if (this._db && this._treeKey) {
+      this._startAutoSync().catch(() => {
+      });
+      this._startAutoSyncFromDb(options.bidirectional || false).catch(() => {
+      });
+    }
+  }
+  /**
+   * Gets the root path
+   */
+  get rootPath() {
+    return this._rootPath;
+  }
+  /**
+   * Gets the blob storage instance
+   */
+  get bs() {
+    return this._bs;
+  }
+  /**
+   * Gets the scanner instance
+   */
+  get scanner() {
+    return this._scanner;
+  }
+  /**
+   * Gets the adapter instance
+   */
+  get adapter() {
+    return this._adapter;
+  }
+  /**
+   * Starts automatic syncing to database
+   * Note: Auto-sync requires Connector which is not available in constructor.
+   * Consider using syncToDb() directly instead of constructor options.
+   */
+  async _startAutoSync() {
+    if (!this._db || !this._treeKey) {
+      return;
+    }
+    throw new Error(
+      "Auto-sync from constructor is not supported. Use syncToDb() method directly with a Connector instance."
+    );
+  }
+  /**
+   * Starts automatic syncing from database
+   * @param bidirectional - Whether bidirectional sync is enabled
+   * Note: Auto-sync requires Connector which is not available in constructor.
+   * Consider using syncFromDb() directly instead of constructor options.
+   */
+  async _startAutoSyncFromDb(bidirectional) {
+    if (!this._db || !this._treeKey || !bidirectional) {
+      return;
+    }
+    throw new Error(
+      "Auto-sync from constructor is not supported. Use syncFromDb() method directly with a Connector instance."
+    );
+  }
+  /**
+   * Stops automatic syncing and cleans up resources
+   */
+  dispose() {
+    if (this._stopSync) {
+      this._stopSync();
+      this._stopSync = void 0;
+    }
+    if (this._stopSyncFromDb) {
+      this._stopSyncFromDb();
+      this._stopSyncFromDb = void 0;
+    }
+  }
+  /**
+   * Extracts filesystem into tree structure with file content in blobs
+   * File content is stored in Bs, tree structure returned with blobIds embedded
+   * @returns Tree structure with blobIds in file metadata
+   */
+  async extract() {
+    const tree = await this._scanner.scan();
+    return tree;
+  }
+  /**
+   * Restores filesystem from tree structure and blob storage
+   * @param tree - Tree structure with blobIds in file metadata
+   * @param targetPath - Optional target path (defaults to rootPath)
+   * @param options - Restore options
+   */
+  async restore(tree, targetPath, options) {
+    const target = targetPath || this._rootPath;
+    const { expectedDirs, expectedFiles } = this._collectExpectedPaths(
+      tree,
+      target
+    );
+    await this._restoreTree(tree.rootHash, tree.trees, target);
+    if (options?.cleanTarget) {
+      await this._pruneExtraneous(target, expectedDirs, expectedFiles);
+    }
+  }
+  /**
+   * Recursively restores a tree node and its children
+   * @param treeHash - Hash of the tree node to restore
+   * @param trees - Map of all tree nodes
+   * @param targetPath - Target directory path
+   */
+  async _restoreTree(treeHash, trees, targetPath) {
+    const treeNode = trees.get(treeHash);
+    if (!treeNode) {
+      throw new Error(`Tree node not found: ${treeHash}`);
+    }
+    const meta = treeNode.meta;
+    if (!meta) {
+      throw new Error(`Tree node is missing meta for hash: ${treeHash}`);
+    }
+    if (meta.type === "file") {
+      const filePath = join(targetPath, meta.relativePath);
+      if (meta.blobId) {
+        let fileBlob;
+        try {
+          fileBlob = await this._bs.getBlob(meta.blobId);
+        } catch (error) {
+          throw new Error(
+            `Failed to retrieve blob for file "${meta.relativePath}" (blobId: ${meta.blobId}): ${error instanceof Error ? error.message : String(error)}`
+          );
+        }
+        if (!fileBlob || !fileBlob.content) {
+          throw new Error(
+            `Missing blob content for file "${meta.relativePath}" (blobId: ${meta.blobId}). The blob may have been deleted or not synced properly.`
+          );
+        }
+        await mkdir(dirname(filePath), { recursive: true });
+        await writeFile(filePath, fileBlob.content);
+        if (meta.mtime) {
+          const mtime = new Date(meta.mtime);
+          await utimes(filePath, mtime, mtime);
+        }
+      }
+    } else if (meta.type === "directory") {
+      const dirPath = meta.relativePath === "." ? targetPath : join(targetPath, meta.relativePath);
+      await mkdir(dirPath, { recursive: true });
+      if (treeNode.children && Array.isArray(treeNode.children)) {
+        for (const childHash of treeNode.children) {
+          await this._restoreTree(childHash, trees, targetPath);
+        }
+      }
+    }
+  }
+  /**
+   * Gets the current tree structure
+   */
+  getTree() {
+    return this._scanner.tree;
+  }
+  /**
+   * Checks if a blob exists in storage
+   * @param blobId - Blob ID to check
+   */
+  async hasBlob(blobId) {
+    return await this._adapter.hasBlob(blobId);
+  }
+  /**
+   * Gets file content from blob storage
+   * @param blobId - Blob ID
+   */
+  async getFileContent(blobId) {
+    return await this._adapter.getFileContent(blobId);
+  }
+  /**
+   * Extracts and stores filesystem tree in database
+   * Reads from filesystem, stores trees in DB and blobs in Bs
+   * @param db - Database instance
+   * @param treeKey - Tree table key
+   * @param options - Storage options
+   * @returns The root tree reference
+   */
+  async storeInDb(db, treeKey, options) {
+    const tree = await this.extract();
+    if (!tree || !tree.rootHash || !tree.trees) {
+      throw new Error(
+        "Cannot store empty or invalid tree in database. Ensure the filesystem has been scanned and contains valid data."
+      );
+    }
+    if (tree.trees.size === 0) {
+      throw new Error(
+        "Cannot store tree with no nodes. The tree structure is empty."
+      );
+    }
+    const dbAdapter = new FsDbAdapter(db, treeKey);
+    return await dbAdapter.storeFsTree(tree, options);
+  }
+  /**
+   * Recursively fetches all tree nodes starting from a root hash
+   * Trees are stored as separate rows with parent-child relationships
+   * This method follows the tree structure and fetches all related nodes
+   * @param db - Database instance
+   * @param route - Route to tree table
+   * @param treeKey - Tree table key
+   * @param rootHash - Hash of the root node to start fetching from
+   * @returns Array of all tree nodes in the tree
+   */
+  async _fetchTreeRecursively(db, route, treeKey, rootHash) {
+    const fetchedNodes = /* @__PURE__ */ new Map();
+    const nodesToFetch = /* @__PURE__ */ new Set([rootHash]);
+    const processed = /* @__PURE__ */ new Set();
+    while (nodesToFetch.size > 0) {
+      const currentHash = Array.from(nodesToFetch)[0];
+      nodesToFetch.delete(currentHash);
+      if (processed.has(currentHash)) {
+        continue;
+      }
+      processed.add(currentHash);
+      let result;
+      try {
+        result = await db.get(route, { _hash: currentHash });
+      } catch {
+        continue;
+      }
+      const treeData = result?.rljson?.[treeKey];
+      if (!treeData || !treeData._data) {
+        continue;
+      }
+      const dataArray = Array.isArray(treeData._data) ? treeData._data : Object.values(treeData._data);
+      for (const node of dataArray) {
+        if (!node._hash) continue;
+        fetchedNodes.set(node._hash, node);
+        if (node.children && Array.isArray(node.children)) {
+          for (const childHash of node.children) {
+            if (typeof childHash === "string" && !processed.has(childHash)) {
+              nodesToFetch.add(childHash);
+            }
+          }
+        }
+      }
+    }
+    return Array.from(fetchedNodes.values());
+  }
+  /**
+   * Loads tree from database and restores to filesystem
+   * Writes to filesystem from DB trees and Bs blobs
+   * @param db - Database instance
+   * @param treeKey - Tree table key
+   * @param rootRef - Root tree reference (hash)
+   * @param targetPath - Optional target path (defaults to rootPath)
+   * @param options - Restore options
+   */
+  async loadFromDb(db, treeKey, rootRef, targetPath, options) {
+    if (!rootRef || rootRef.trim() === "") {
+      throw new Error("rootRef cannot be empty");
+    }
+    const route = Route.fromFlat(treeKey);
+    const allNodes = await this._fetchTreeRecursively(
+      db,
+      route,
+      treeKey,
+      rootRef
+    );
+    if (allNodes.length === 0) {
+      throw new Error(
+        `No tree nodes found for ${treeKey}@${rootRef}. The tree may have been deleted or the reference is invalid.`
+      );
+    }
+    const trees = /* @__PURE__ */ new Map();
+    for (const treeNode of allNodes) {
+      if (treeNode._hash) {
+        trees.set(treeNode._hash, treeNode);
+      }
+    }
+    if (!trees.has(rootRef)) {
+      throw new Error(
+        `Root tree node "${rootRef}" not found in tree data. Available hashes: ${Array.from(trees.keys()).slice(0, 5).join(", ")}${trees.size > 5 ? "..." : ""}`
+      );
+    }
+    const fsTree = {
+      rootHash: rootRef,
+      trees
+    };
+    await this.restore(fsTree, targetPath, options);
+  }
+  /**
+   * Collects expected file and directory paths for cleanup
+   * @param tree - Tree structure to evaluate
+   * @param target - Filesystem root where the tree will be restored
+   */
+  _collectExpectedPaths(tree, target) {
+    const expectedDirs = /* @__PURE__ */ new Set([target]);
+    const expectedFiles = /* @__PURE__ */ new Set();
+    for (const [, node] of tree.trees) {
+      const meta = node?.meta;
+      if (!meta) {
+        continue;
+      }
+      if (meta.type === "directory") {
+        const dirPath = meta.relativePath === "." ? target : join(target, meta.relativePath);
+        expectedDirs.add(dirPath);
+      } else if (meta.type === "file") {
+        const filePath = join(target, meta.relativePath);
+        expectedFiles.add(filePath);
+        expectedDirs.add(dirname(filePath));
+      }
+    }
+    return { expectedDirs, expectedFiles };
+  }
+  /**
+   * Remove files/dirs not present in the expected sets
+   * @param currentDir - Directory currently being inspected
+   * @param expectedDirs - Allowed directory paths
+   * @param expectedFiles - Allowed file paths
+   */
+  async _pruneExtraneous(currentDir, expectedDirs, expectedFiles) {
+    const entries = await readdir(currentDir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        if (!expectedDirs.has(fullPath)) {
+          await rm(fullPath, { recursive: true, force: true });
+          continue;
+        }
+        await this._pruneExtraneous(fullPath, expectedDirs, expectedFiles);
+      } else {
+        if (!expectedFiles.has(fullPath)) {
+          await rm(fullPath, { force: true });
+        }
+      }
+    }
+  }
+  /**
+   * Watches filesystem for changes and syncs to database
+   * Uses Connector for socket-based broadcast
+   * @param db - Database instance
+   * @param connector - Connector instance for socket-based sync
+   * @param treeKey - Tree table key
+   * @param options - Storage options (e.g., notify)
+   * @returns Function to stop watching
+   */
+  async syncToDb(db, connector, treeKey, options) {
+    const initialRef = await this.storeInDb(db, treeKey, options);
+    if (initialRef) {
+      this._lastSentRef = initialRef;
+      connector.send(initialRef);
+    }
+    const syncCallback = async () => {
+      const tree = this._scanner.tree;
+      if (tree) {
+        const dbAdapter = new FsDbAdapter(db, treeKey);
+        const ref = await dbAdapter.storeFsTree(tree, options);
+        this._lastSentRef = ref;
+        if (ref) {
+          connector.send(ref);
+        }
+      }
+    };
+    this._scanner.onChange(syncCallback);
+    await this._scanner.watch();
+    return () => {
+      this._scanner.offChange(syncCallback);
+      this._scanner.stopWatch();
+    };
+  }
+  /**
+   * Watches database for tree changes and syncs to filesystem
+   * Uses Connector for socket-based notifications
+   * @param db - Database instance
+   * @param connector - Connector instance for socket-based sync
+   * @param treeKey - Tree table key
+   * @param restoreOptions - Restore options (e.g., cleanTarget)
+   * @returns Function to stop watching
+   */
+  async syncFromDb(db, connector, treeKey, restoreOptions) {
+    if (!this._scanner["_watcher"]) {
+      await this._scanner.watch();
+    }
+    const syncCallback = async (treeRef) => {
+      if (!treeRef || typeof treeRef !== "string") {
+        return;
+      }
+      if (treeRef === this._lastSentRef) {
+        return;
+      }
+      this._scanner.pauseWatch();
+      try {
+        await this.loadFromDb(db, treeKey, treeRef, void 0, restoreOptions);
+      } catch {
+      } finally {
+        this._scanner.resumeWatch();
+      }
+    };
+    connector.listen(syncCallback);
+    return () => {
+      connector.teardown();
+    };
+  }
+  /** Example instance for test purposes */
+  static get example() {
+    return new FsAgent(process.cwd());
+  }
+}
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+class IsReady {
+  constructor() {
+    __publicField(this, "_state", false);
+    __publicField(this, "_callbacks", []);
+  }
+  static get instance() {
+    return new IsReady();
+  }
+  static get example() {
+    return new IsReady();
+  }
+  get state() {
+    return this._state;
+  }
+  resolve() {
+    this._state = true;
+    this._callbacks.forEach((callback) => {
+      callback();
+    });
+    this._callbacks = [];
+  }
+  reset() {
+    this._state = false;
+  }
+  get promise() {
+    return this._isReady();
+  }
+  _isReady() {
+    return new Promise((resolve) => {
+      if (this._state) {
+        resolve();
+      } else {
+        this._callbacks.push(() => {
+          resolve();
+        });
+      }
+    });
+  }
+}
+class IoTools {
+  /**
+   * Constructor
+   * @param io The Io interface to use
+   */
+  constructor(io) {
+    this.io = io;
+  }
+  /**
+   * Returns the table configuration of the tableCfgs table.
+   */
+  static get tableCfgsTableCfg() {
+    const tableCfg = hip({
+      _hash: "",
+      key: "tableCfgs",
+      type: "tableCfgs",
+      isHead: false,
+      isRoot: false,
+      isShared: true,
+      previous: "",
+      columns: [
+        {
+          key: "_hash",
+          type: "string",
+          titleShort: "Hash",
+          titleLong: "Row Hash"
+        },
+        {
+          key: "key",
+          type: "string",
+          titleShort: "Key",
+          titleLong: "Table Key"
+        },
+        {
+          key: "type",
+          type: "string",
+          titleShort: "Type",
+          titleLong: "Content Type"
+        },
+        {
+          key: "isHead",
+          type: "boolean",
+          titleShort: "Is Head",
+          titleLong: "Is Head Table"
+        },
+        {
+          key: "isRoot",
+          type: "boolean",
+          titleShort: "Is Root",
+          titleLong: "Is Root Table"
+        },
+        {
+          key: "isShared",
+          type: "boolean",
+          titleShort: "Is Shared",
+          titleLong: "Is Shared Table"
+        },
+        {
+          key: "previous",
+          type: "string",
+          titleShort: "Previous",
+          titleLong: "Previous Table Configuration Hash"
+        },
+        {
+          key: "columns",
+          type: "jsonArray",
+          titleShort: "Columns",
+          titleLong: "Column Configurations"
+        }
+      ]
+    });
+    return tableCfg;
+  }
+  /**
+   * Initializes the revisions table.
+   */
+  initRevisionsTable = async () => {
+    const tableCfg = {
+      key: "revisions",
+      type: "revisions",
+      isHead: true,
+      isRoot: true,
+      isShared: false,
+      columns: [
+        {
+          key: "_hash",
+          type: "string",
+          titleShort: "Hash",
+          titleLong: "Row Hash"
+        },
+        {
+          key: "table",
+          type: "string",
+          titleShort: "Table",
+          titleLong: "Table Key"
+        },
+        {
+          key: "predecessor",
+          type: "string",
+          titleShort: "Predecessor",
+          titleLong: "Predecessor Revision Hash"
+        },
+        {
+          key: "successor",
+          type: "string",
+          titleShort: "Successor",
+          titleLong: "Successor Revision Hash"
+        },
+        {
+          key: "timestamp",
+          type: "number",
+          titleShort: "Timestamp",
+          titleLong: "Revision Timestamp"
+        },
+        {
+          key: "id",
+          type: "string",
+          titleShort: "ID",
+          titleLong: "Revision ID"
+        }
+      ]
+    };
+    await this.io.createOrExtendTable({ tableCfg });
+  };
+  /**
+   * Example object for test purposes
+   * @returns An instance of io tools
+   */
+  static example = async () => {
+    const io = await IoMem.example();
+    await io.init();
+    await io.isReady();
+    return new IoTools(io);
+  };
+  /**
+   * Throws if the table does not exist
+   */
+  async throwWhenTableDoesNotExist(table) {
+    const exists = await this.io.tableExists(table);
+    if (!exists) {
+      throw new Error(`Table "${table}" not found`);
+    }
+  }
+  /**
+   * Throws if any of the tables in rljson do not exist
+   * @param rljson - The Rljson object to check
+   */
+  async throwWhenTablesDoNotExist(rljson) {
+    try {
+      await iterateTables(rljson, async (tableKey) => {
+        const exists = await this.io.tableExists(tableKey);
+        if (!exists) {
+          throw new Error(`Table "${tableKey}" not found`);
+        }
+      });
+    } catch (e) {
+      const missingTables = e.map((e2) => e2.tableKey);
+      throw new Error(
+        `The following tables do not exist: ${missingTables.join(", ")}`
+      );
+    }
+  }
+  /**
+   * Returns the current table cfgs of all tables
+   * @returns The table configuration of all tables
+   */
+  async tableCfgs() {
+    const tables = await this.io.rawTableCfgs();
+    const newestVersion = {};
+    for (let i = tables.length - 1; i >= 0; i--) {
+      const table = tables[i];
+      const existing = newestVersion[table.key];
+      if (!existing || existing.columns.length < table.columns.length) {
+        newestVersion[table.key] = table;
+      }
+    }
+    const resultData = Object.values(newestVersion).sort((a, b) => {
+      if (a.key < b.key) {
+        return -1;
+      }
+      if (a.key > b.key) {
+        return 1;
+      }
+      return 0;
+    });
+    return resultData;
+  }
+  /**
+   * Returns a list with all table names
+   */
+  async allTableKeys() {
+    const result = (await this.tableCfgs()).map((e) => e.key);
+    return result;
+  }
+  /**
+   * Returns the configuration of a given table
+   */
+  async tableCfg(table) {
+    const tableCfg = await this.tableCfgOrNull(table);
+    if (!tableCfg) {
+      throw new Error(`Table "${table}" not found`);
+    }
+    return tableCfg;
+  }
+  /**
+     * Returns the configuration of a given table or null if it does not exist.
+  
+     */
+  async tableCfgOrNull(table) {
+    const tableCfgs = await this.tableCfgs();
+    const tableCfg = tableCfgs.find((e) => e.key === table);
+    return tableCfg ?? null;
+  }
+  /**
+   * Returns a list of all column names of a given table
+   */
+  async allColumnKeys(table) {
+    const tableCfg = await this.tableCfg(table);
+    const result = tableCfg.columns.map((column) => column.key);
+    return result;
+  }
+  /**
+   * Throws when a column does not exist in a given table
+   * @param table - The table to check
+   * @param columns - The column to check
+   */
+  async throwWhenColumnDoesNotExist(table, columns) {
+    const tableCfg = await this.tableCfg(table);
+    const columnKeys = tableCfg.columns.map((column) => column.key);
+    const missingColumns = columns.filter(
+      (column) => !columnKeys.includes(column)
+    );
+    if (missingColumns.length > 0) {
+      throw new Error(
+        `The following columns do not exist in table "${table}": ${missingColumns.join(
+          ", "
+        )}.`
+      );
+    }
+  }
+  /**
+   * Throws when a table update is not compatible with the current table
+   * configuration.
+   */
+  async throwWhenTableIsNotCompatible(update) {
+    const prefix = `Invalid update of table able "${update.key}"`;
+    throwOnInvalidTableCfg(update);
+    const existing = await this.tableCfgOrNull(update.key);
+    if (existing) {
+      if (existing.columns.length > update.columns.length) {
+        const deletedColumnKeys = existing.columns.map((column) => column.key).filter(
+          (key) => !update.columns.some((column) => column.key === key)
+        );
+        if (deletedColumnKeys.length > 0) {
+          const deletedColumns = deletedColumnKeys.join(", ");
+          throw new Error(
+            `${prefix}: Columns must not be deleted. Deleted columns: ${deletedColumns}}`
+          );
+        }
+      }
+      for (let i = 0; i < existing.columns.length; i++) {
+        const before = existing.columns[i].key;
+        const after = update.columns[i].key;
+        if (before !== after) {
+          throw new Error(
+            `${prefix}: Column keys must not change! Column "${before}" was renamed into "${after}".`
+          );
+        }
+      }
+      for (let i = 0; i < existing.columns.length; i++) {
+        const column = existing.columns[i].key;
+        const before = existing.columns[i].type;
+        const after = update.columns[i].type;
+        if (before !== after) {
+          throw new Error(
+            `${prefix}: Column types must not change! Type of column "${column}" was changed from "${before}" to ${after}.`
+          );
+        }
+      }
+    }
+  }
+  /**
+   * Throws if the data in the table do not match the table configuration
+   */
+  async throwWhenTableDataDoesNotMatchCfg(data) {
+    const errors = [];
+    await iterateTables(data, async (tableKey) => {
+      const tableCfg = await this.tableCfg(tableKey);
+      const table = data[tableKey];
+      if (table._type === "tableCfgs") return;
+      errors.push(...validateRljsonAgainstTableCfg(table._data, tableCfg));
+    });
+    if (errors.length > 0) {
+      throw new Error(
+        `Table data does not match the configuration.
+
+Errors:
+${errors.map((e) => `- ${e}`).join("\n")}`
+      );
+    }
+  }
+  /**
+   * Sorts the data of a table by the hash and updates the table hash in place
+   */
+  sortTableDataAndUpdateHash(table) {
+    table._data.sort((a, b) => {
+      const hashA = a._hash;
+      const hashB = b._hash;
+      if (hashA < hashB) {
+        return -1;
+      }
+      if (hashA > hashB) {
+        return 1;
+      }
+      return 0;
+    });
+    table._hash = "";
+    hip(table, {
+      updateExistingHashes: false,
+      throwOnWrongHashes: false
+    });
+  }
+}
+class IoMem {
+  // ...........................................................................
+  // Constructor & example
+  init() {
+    this._isOpen = true;
+    return this._init();
+  }
+  close() {
+    this._isOpen = false;
+    return Promise.resolve();
+  }
+  get isOpen() {
+    return this._isOpen;
+  }
+  static example = async () => {
+    const io = new IoMem();
+    await io.init();
+    return io;
+  };
+  // ...........................................................................
+  // General
+  isReady() {
+    return this._isReady.promise;
+  }
+  // ...........................................................................
+  // Dump
+  dump() {
+    return this._dump();
+  }
+  async dumpTable(request) {
+    return this._dumpTable(request);
+  }
+  // ...........................................................................
+  // Meta Data
+  async contentType(request) {
+    return this._contentType(request);
+  }
+  // ...........................................................................
+  // Rows
+  readRows(request) {
+    return this._readRows(request);
+  }
+  async rowCount(table) {
+    const tableData = this._mem[table];
+    if (!tableData) {
+      throw new Error(`Table "${table}" not found`);
+    }
+    return Promise.resolve(tableData._data.length);
+  }
+  // ...........................................................................
+  // Write
+  write(request) {
+    return this._write(request);
+  }
+  // ...........................................................................
+  // Table management
+  async tableExists(tableKey) {
+    const table = this._mem[tableKey];
+    return table ? true : false;
+  }
+  createOrExtendTable(request) {
+    return this._createOrExtendTable(request);
+  }
+  async rawTableCfgs() {
+    const tables = this._mem.tableCfgs._data;
+    return tables;
+  }
+  // ######################
+  // Private
+  // ######################
+  _ioTools;
+  _isReady = new IsReady();
+  _isOpen = false;
+  _mem = hip({});
+  // ...........................................................................
+  async _init() {
+    this._ioTools = new IoTools(this);
+    this._initTableCfgs();
+    this._updateGlobalHash();
+    await this._ioTools.initRevisionsTable();
+    hsh(this._mem);
+    this._isReady.resolve();
+  }
+  // ...........................................................................
+  _initTableCfgs = () => {
+    const tableCfg = IoTools.tableCfgsTableCfg;
+    this._mem.tableCfgs = hip({
+      _type: "tableCfgs",
+      _data: [tableCfg],
+      _tableCfg: tableCfg._hash
+    });
+  };
+  // ...........................................................................
+  _updateGlobalHash() {
+    this._mem._hash = "";
+    hip(this._mem, {
+      updateExistingHashes: false
+    });
+  }
+  // ...........................................................................
+  _updateTableHash(tableKey) {
+    const table = this._mem[tableKey];
+    table._hash = "";
+    hip(table, { updateExistingHashes: false });
+  }
+  // ...........................................................................
+  async _createOrExtendTable(request) {
+    const tableCfg = request.tableCfg;
+    await this._ioTools.throwWhenTableIsNotCompatible(tableCfg);
+    const { key } = tableCfg;
+    const newConfig = hsh(tableCfg);
+    const existingConfig = await this._ioTools.tableCfgOrNull(key);
+    if (!existingConfig) {
+      this._createTable(newConfig, key);
+    } else {
+      this._extendTable(existingConfig, newConfig);
+    }
+  }
+  // ...........................................................................
+  _createTable(newConfig, tableKey) {
+    newConfig = hsh(newConfig);
+    this._mem.tableCfgs._data.push(newConfig);
+    this._ioTools.sortTableDataAndUpdateHash(this._mem.tableCfgs);
+    const table = {
+      _type: newConfig.type,
+      _data: [],
+      _tableCfg: newConfig._hash
+    };
+    this._mem[tableKey] ??= hip(table);
+    this._updateTableHash(tableKey);
+    this._updateGlobalHash();
+  }
+  // ...........................................................................
+  _extendTable(existingConfig, newConfig) {
+    if (existingConfig.columns.length === newConfig.columns.length) {
+      return;
+    }
+    newConfig = hsh(newConfig);
+    this._mem.tableCfgs._data.push(newConfig);
+    this._ioTools.sortTableDataAndUpdateHash(this._mem.tableCfgs);
+    const table = this._mem[newConfig.key];
+    table._tableCfg = newConfig._hash;
+    this._updateTableHash(newConfig.key);
+    this._updateGlobalHash();
+  }
+  // ...........................................................................
+  async _dump() {
+    return copy(this._mem);
+  }
+  // ...........................................................................
+  async _dumpTable(request) {
+    await this._ioTools.throwWhenTableDoesNotExist(request.table);
+    const table = this._mem[request.table];
+    return {
+      [request.table]: copy(table)
+    };
+  }
+  // ...........................................................................
+  async _contentType(request) {
+    await this._ioTools.throwWhenTableDoesNotExist(request.table);
+    return this._mem[request.table]._type;
+  }
+  // ...........................................................................
+  async _write(request) {
+    const addedData = hsh(request.data);
+    this._removeNullValues(addedData);
+    const tables = Object.keys(addedData);
+    hsh(addedData);
+    await this._ioTools.throwWhenTablesDoNotExist(request.data);
+    await this._ioTools.throwWhenTableDataDoesNotMatchCfg(request.data);
+    for (const table of tables) {
+      if (table.startsWith("_")) {
+        continue;
+      }
+      const oldTable = this._mem[table];
+      const newTable = addedData[table];
+      for (const item of newTable._data) {
+        const hash = item._hash;
+        const exists = oldTable._data.find((i) => i._hash === hash);
+        if (!exists) {
+          oldTable._data.push(item);
+        }
+      }
+      this._ioTools.sortTableDataAndUpdateHash(oldTable);
+    }
+    this._updateGlobalHash();
+  }
+  // ...........................................................................
+  async _readRows(request) {
+    await this._ioTools.throwWhenTableDoesNotExist(request.table);
+    await this._ioTools.throwWhenColumnDoesNotExist(
+      request.table,
+      Object.keys(request.where)
+    );
+    const table = this._mem[request.table];
+    const tableDataFiltered = table._data.filter((row) => {
+      for (const column in request.where) {
+        const a = row[column];
+        const b = request.where[column];
+        if (b === null && a === void 0) {
+          return true;
+        }
+        if (!equals(a, b)) {
+          return false;
+        }
+      }
+      return true;
+    });
+    const tableFiltered = {
+      _type: table._type,
+      _data: tableDataFiltered
+    };
+    this._ioTools.sortTableDataAndUpdateHash(tableFiltered);
+    const result = {
+      [request.table]: tableFiltered
+    };
+    return result;
+  }
+  _removeNullValues(rljson) {
+    iterateTablesSync(rljson, (table) => {
+      const data = rljson[table]._data;
+      for (const row of data) {
+        for (const key in row) {
+          if (row[key] === null) {
+            delete row[key];
+          }
+        }
+      }
+    });
+  }
+}
+let PeerSocketMock$1 = class PeerSocketMock {
+  constructor(_io) {
+    this._io = _io;
+  }
+  _listenersMap = /* @__PURE__ */ new Map();
+  connected = false;
+  disconnected = true;
+  // ............................................................................
+  /**
+   * Removes a specific listener for the specified event.
+   * @param eventName - The name of the event.
+   * @param listener - The callback function to remove.
+   * @returns The PeerSocketMock instance for chaining.
+   */
+  off(eventName, listener) {
+    const listeners = this._listenersMap.get(eventName) || [];
+    const index = listeners.indexOf(listener);
+    if (index !== -1) {
+      listeners.splice(index, 1);
+      this._listenersMap.set(eventName, listeners);
+    }
+    return this;
+  }
+  // ............................................................................
+  /**
+   * Removes all listeners for the specified event, or all listeners if no event is specified.
+   * @param eventName - (Optional) The name of the event.
+   * @returns The PeerSocketMock instance for chaining.
+   */
+  removeAllListeners(eventName) {
+    if (eventName) {
+      this._listenersMap.delete(eventName);
+    } else {
+      this._listenersMap.clear();
+    }
+    return this;
+  }
+  // ............................................................................
+  /**
+   * Registers an event listener for the specified event.
+   * @param eventName - The name of the event to listen for.
+   * @param listener - The callback function to invoke when the event is emitted.
+   * @returns The PeerSocketMock instance for chaining.
+   */
+  on(eventName, listener) {
+    if (!this._listenersMap.has(eventName)) {
+      this._listenersMap.set(eventName, []);
+    }
+    this._listenersMap.get(eventName).push(listener);
+    return this;
+  }
+  // ...........................................................................
+  /**
+   * Simulates a connection event.
+   *
+   * Emits the 'connect' event to all registered listeners.
+   */
+  connect() {
+    this.connected = true;
+    this.disconnected = false;
+    const listeners = this._listenersMap.get("connect") || [];
+    for (const cb of listeners) {
+      cb({});
+    }
+  }
+  // ...........................................................................
+  /**
+   * Simulates a disconnection event.
+   *
+   * Emits the 'disconnect' event to all registered listeners.
+   */
+  disconnect() {
+    this.connected = false;
+    this.disconnected = true;
+    const listeners = this._listenersMap.get("disconnect") || [];
+    for (const cb of listeners) {
+      cb({});
+    }
+  }
+  // ............................................................................
+  /**
+   * Emits an event, invoking the corresponding method on the Io instance.
+   * @param eventName - The name of the event to emit.
+   * @param args - The arguments to pass to the event listener.
+   * @returns
+   */
+  emit(eventName, ...args) {
+    const fn = this._io[eventName];
+    if (typeof fn !== "function") {
+      throw new Error(`Event ${eventName.toString()} not supported`);
+    }
+    const cb = args[args.length - 1];
+    fn.apply(this._io, args.slice(0, -1)).then((result) => {
+      cb(result, null);
+    }).catch((err) => {
+      cb(null, err);
+    });
+    return true;
+  }
+};
+class IoPeer {
+  constructor(_socket) {
+    this._socket = _socket;
+  }
+  isOpen = false;
+  // ...........................................................................
+  /**
+   *
+   * Initializes the Peer connection.
+   * @returns
+   */
+  async init() {
+    this._socket.on("connect", () => {
+      this.isOpen = true;
+    });
+    this._socket.on("disconnect", () => {
+      this.isOpen = false;
+    });
+    this._socket.connect();
+    return new Promise((resolve) => {
+      if (this._socket.connected) {
+        this.isOpen = true;
+        resolve();
+      } else {
+        this._socket.on("connect", () => {
+          resolve();
+        });
+      }
+    });
+  }
+  // ...........................................................................
+  /**
+   * Closes the Peer connection.
+   * @returns
+   */
+  async close() {
+    if (!this._socket.connected) return;
+    return new Promise((resolve) => {
+      this._socket.on("disconnect", () => {
+        resolve();
+      });
+      this._socket.disconnect();
+    });
+  }
+  // ...........................................................................
+  /**
+   * Returns a promise that resolves once the Peer connection is ready.
+   * @returns
+   */
+  async isReady() {
+    if (!!this._socket && this._socket.connected === true) this.isOpen = true;
+    else this.isOpen = false;
+    return !!this.isOpen ? Promise.resolve() : Promise.reject();
+  }
+  // ...........................................................................
+  /**
+   * Dumps the entire database content.
+   * @returns A promise that resolves to the dumped database content.
+   */
+  async dump() {
+    return new Promise((resolve) => {
+      this._socket.emit("dump", (data) => {
+        resolve(data);
+      });
+    });
+  }
+  // ...........................................................................
+  /**
+   * Dumps a specific table from the database.
+   * @param request An object containing the table name to dump.
+   * @returns A promise that resolves to the dumped table data.
+   */
+  dumpTable(request) {
+    return new Promise((resolve, reject) => {
+      this._socket.emit("dumpTable", request, (data, error) => {
+        if (error) reject(error);
+        resolve(data);
+      });
+    });
+  }
+  // ...........................................................................
+  /**
+   * Gets the content type of a specific table.
+   * @param request An object containing the table name to get the content type for.
+   * @returns A promise that resolves to the content type of the specified table.
+   */
+  contentType(request) {
+    return new Promise((resolve, reject) => {
+      this._socket.emit(
+        "contentType",
+        request,
+        (data, error) => {
+          if (error) reject(error);
+          resolve(data);
+        }
+      );
+    });
+  }
+  // ...........................................................................
+  /**
+   * Checks if a specific table exists in the database.
+   * @param tableKey The key of the table to check for existence.
+   * @returns A promise that resolves to true if the table exists, false otherwise.
+   */
+  tableExists(tableKey) {
+    return new Promise((resolve) => {
+      this._socket.emit("tableExists", tableKey, (exists) => {
+        resolve(exists);
+      });
+    });
+  }
+  // ...........................................................................
+  /**
+   * Creates or extends a table with the given configuration.
+   * @param request An object containing the table configuration.
+   * @returns A promise that resolves once the table is created or extended.
+   */
+  createOrExtendTable(request) {
+    return new Promise((resolve, reject) => {
+      this._socket.emit(
+        "createOrExtendTable",
+        request,
+        (_, error) => {
+          if (error) reject(error);
+          resolve();
+        }
+      );
+    });
+  }
+  // ...........................................................................
+  /**
+   * Retrieves the raw table configurations from the database.
+   * @returns A promise that resolves to an array of table configurations.
+   */
+  rawTableCfgs() {
+    return new Promise((resolve) => {
+      this._socket.emit("rawTableCfgs", (data) => {
+        resolve(data);
+      });
+    });
+  }
+  // ...........................................................................
+  /**
+   * Writes data to the database.
+   * @param request An object containing the data to write.
+   * @returns A promise that resolves once the data is written.
+   */
+  write(request) {
+    return new Promise((resolve, reject) => {
+      this._socket.emit("write", request, (_, error) => {
+        if (error) reject(error);
+        resolve();
+      });
+    });
+  }
+  // ...........................................................................
+  /**
+   * Reads rows from a specific table that match the given criteria.
+   * @param request An object containing the table name and the criteria for selecting rows.
+   * @returns A promise that resolves to the selected rows.
+   */
+  readRows(request) {
+    return new Promise((resolve, reject) => {
+      this._socket.emit(
+        "readRows",
+        request,
+        (result, error) => {
+          if (error) reject(error);
+          resolve(result);
+        }
+      );
+    });
+  }
+  // ...........................................................................
+  /**
+   * Retrieves the number of rows in a specific table.
+   * @param table The name of the table to count rows in.
+   * @returns A promise that resolves to the number of rows in the specified table.
+   */
+  rowCount(table) {
+    return new Promise((resolve, reject) => {
+      this._socket.emit("rowCount", table, (count, error) => {
+        if (error) reject(error);
+        resolve(count);
+      });
+    });
+  }
+  // ...........................................................................
+  static example = async () => {
+    const ioMem = await IoMem.example();
+    const socket = new PeerSocketMock$1(ioMem);
+    const io = new IoPeer(socket);
+    await io.init();
+    return io;
+  };
+}
+class IoMulti {
+  constructor(_ios) {
+    this._ios = _ios;
+  }
+  isOpen = false;
+  // ...........................................................................
+  /**
+   *
+   * Initializes all underlying Io instances.
+   * @returns
+   */
+  async init() {
+    for (let idx = 0; idx < this._ios.length; idx++) {
+      const { io } = this._ios[idx];
+      if (io.isOpen === false) {
+        throw new Error(
+          "All underlying Io instances must be initialized before initializing IoMulti"
+        );
+      }
+      this._ios[idx] = { ...this._ios[idx], id: `io-${idx}` };
+    }
+    this.isOpen = true;
+    return Promise.resolve();
+  }
+  // ...........................................................................
+  /**
+   * Closes all underlying Io instances.
+   * @returns
+   */
+  async close() {
+    await Promise.all(this._ios.map((ioMultiIo) => ioMultiIo.io.close()));
+    this.isOpen = false;
+    return Promise.resolve();
+  }
+  // ...........................................................................
+  /**
+   * Returns a promise that resolves once all underlying Io instances are ready.
+   * @returns
+   */
+  isReady() {
+    return Promise.all(
+      this._ios.map((ioMultiIo) => ioMultiIo.io.isReady())
+    ).then(() => Promise.resolve());
+  }
+  // ...........................................................................
+  /**
+   * Dumps the entire database content by merging dumps from all dumpable underlying Io instances.
+   * @returns
+   */
+  async dump() {
+    if (this.dumpables.length === 0) {
+      throw new Error("No dumpable Io available");
+    }
+    const dumps = await Promise.all(
+      this.dumpables.map(({ io: dumpable }) => dumpable.dump())
+    );
+    return merge(...dumps);
+  }
+  // ...........................................................................
+  /**
+   * Dumps a specific table by merging dumps from all dumpable underlying Io instances that contain the table.
+   * @param request An object containing the table name to dump.
+   * @returns A promise that resolves to the dumped table data.
+   */
+  async dumpTable(request) {
+    if (this.dumpables.length === 0) {
+      throw new Error("No dumpable Io available");
+    }
+    const dumps = [];
+    for (const { io: dumpable } of this.dumpables) {
+      try {
+        const dump = await dumpable.dumpTable(request);
+        dumps.push(dump);
+      } catch {
+        continue;
+      }
+    }
+    if (dumps.length === 0) {
+      throw new Error(`Table "${request.table}" not found`);
+    }
+    return merge(...dumps);
+  }
+  // ...........................................................................
+  /**
+   * Retrieves the content type of a specific table from the first underlying readable Io instance that contains the table.
+   * @param request An object containing the table name.
+   * @returns A promise that resolves to the content type of the table.
+   */
+  async contentType(request) {
+    if (this.readables.length === 0) {
+      throw new Error("No readable Io available");
+    }
+    for (const { io: readable } of this.readables) {
+      return readable.contentType(request);
+    }
+    throw new Error(`Table "${request.table}" not found`);
+  }
+  // ...........................................................................
+  /**
+   * Checks if a specific table exists in any of the underlying readable Io instances.
+   * @param tableKey The key of the table to check.
+   * @returns A promise that resolves to true if the table exists in any readable Io, false otherwise.
+   */
+  async tableExists(tableKey) {
+    if (this.readables.length === 0) {
+      throw new Error("No readable Io available");
+    }
+    for (let i = 0; i < this.readables.length; i++) {
+      const readable = this.readables[i].io;
+      const exists = await readable.tableExists(tableKey);
+      if (exists) {
+        return true;
+      }
+    }
+    return false;
+  }
+  // ...........................................................................
+  /**
+   * Creates or extends a table in all underlying writable Io instances.
+   * @param request An object containing the table configuration.
+   * @returns A promise that resolves once the table has been created or extended in all writable Io instances.
+   */
+  createOrExtendTable(request) {
+    if (this.writables.length === 0) {
+      throw new Error("No writable Io available");
+    }
+    const creations = this.writables.map(
+      ({ io: writable }) => writable.createOrExtendTable(request)
+    );
+    return Promise.all(creations).then(() => Promise.resolve());
+  }
+  // ...........................................................................
+  /**
+   * Retrieves the raw table configurations from the highest priority underlying readable Io instance.
+   * @returns A promise that resolves to an array of table configurations.
+   */
+  async rawTableCfgs() {
+    if (this.readables.length === 0) {
+      throw new Error("No readable Io available");
+    }
+    const rawTableCfgs = /* @__PURE__ */ new Map();
+    for (const { io: readable } of this.readables) {
+      const cfgs = await readable.rawTableCfgs();
+      if (cfgs.length > 0) {
+        for (const tableCfg of cfgs) {
+          if (!rawTableCfgs.has(tableCfg.key)) {
+            rawTableCfgs.set(tableCfg.key, tableCfg);
+          }
+        }
+      }
+    }
+    return Array.from(rawTableCfgs.values());
+  }
+  // ...........................................................................
+  /**
+   * Writes data to all underlying writable Io instances.
+   * @param request - An object containing the data to write.
+   * @returns A promise that resolves once the data has been written to all writable Io instances.
+   */
+  write(request) {
+    if (this.writables.length === 0) {
+      throw new Error("No writable Io available");
+    }
+    const writes = this.writables.map(
+      ({ io: writable }) => writable.write(request)
+    );
+    return Promise.all(writes).then(() => Promise.resolve());
+  }
+  // ...........................................................................
+  /**
+   * Reads rows from a specific table by merging rows from all underlying readable Io instances.
+   * @param request An object containing the table name and where clause.
+   * @returns A promise that resolves to the read rows.
+   */
+  async readRows(request) {
+    if (this.readables.length === 0) {
+      throw new Error("No readable Io available");
+    }
+    let tableExistsAny = false;
+    const rows = /* @__PURE__ */ new Map();
+    let type = void 0;
+    let readFrom = "";
+    const errors = [];
+    for (const readable of this.readables) {
+      let tableRows = [];
+      let tableType;
+      try {
+        const { [request.table]: tableData } = await readable.io.readRows(
+          request
+        );
+        tableRows = tableData._data;
+        tableType = tableData._type;
+        tableExistsAny = true;
+        readFrom = readable.id ?? "";
+      } catch (e) {
+        errors.push(e);
+        continue;
+      }
+      type ??= tableType;
+      if (tableRows.length === 0) {
+        continue;
+      }
+      for (const tableRow of tableRows) {
+        const ref = tableRow._hash;
+        rows.set(ref, tableRow);
+      }
+      break;
+    }
+    if (!tableExistsAny) {
+      if (errors.length === 0) {
+        throw new Error(`Table "${request.table}" not found`);
+      } else {
+        const preciseErrors = errors.filter(
+          (err) => !err.message.includes(`Table "${request.table}" not found`)
+        );
+        if (preciseErrors.length > 0) {
+          throw preciseErrors[0];
+        } else {
+          throw errors[0];
+        }
+      }
+    } else {
+      const rljson = {
+        [request.table]: hip({ _data: Array.from(rows.values()), _type: type })
+      };
+      if (this.writables.length > 0 && rows.size > 0) {
+        for (const writeable of this.writables) {
+          if (writeable.id === readFrom) {
+            continue;
+          }
+          try {
+            await writeable.io.write({
+              data: rljson
+            });
+          } catch {
+            continue;
+          }
+        }
+      }
+      return rljson;
+    }
+  }
+  // ...........................................................................
+  /**
+   * Retrieves the row count of a specific table by aggregating row counts from all dumpable underlying Io instances.
+   * @param table The name of the table.
+   * @returns A promise that resolves to the row count of the table.
+   */
+  async rowCount(table) {
+    if (this.dumpables.length === 0) {
+      throw new Error("No dumpable Io available");
+    }
+    const dumpTable = await this.dumpTable({ table });
+    const tableData = dumpTable[table];
+    if (!tableData) {
+      throw new Error(`Table "${table}" not found`);
+    }
+    return Promise.resolve(tableData._data.length);
+  }
+  // ...........................................................................
+  /**
+   * Gets the list of underlying readable Io instances, sorted by priority.
+   */
+  get readables() {
+    return this._ios.filter((ioMultiIo) => ioMultiIo.read).sort((a, b) => a.priority - b.priority);
+  }
+  // ...........................................................................
+  /**
+   * Gets the list of underlying writable Io instances, sorted by priority.
+   */
+  get writables() {
+    return this._ios.filter((ioMultiIo) => ioMultiIo.write).sort((a, b) => a.priority - b.priority);
+  }
+  // ...........................................................................
+  /**
+   * Gets the list of underlying dumpable Io instances, sorted by priority.
+   */
+  get dumpables() {
+    return this._ios.filter((ioMultiIo) => ioMultiIo.dump).sort((a, b) => a.priority - b.priority);
+  }
+  // ...........................................................................
+  static example = async () => {
+    const ioPeerMem = await IoMem.example();
+    await ioPeerMem.init();
+    const ioPeerSocket = new PeerSocketMock$1(ioPeerMem);
+    const ioPeer = new IoPeer(ioPeerSocket);
+    await ioPeer.init();
+    const ioMem = await IoMem.example();
+    await ioMem.init();
+    const ios = [
+      { io: ioPeer, priority: 1, read: true, write: false, dump: false },
+      { io: ioMem, priority: 0, read: true, write: true, dump: true }
+    ];
+    const ioMulti = new IoMulti(ios);
+    await ioMulti.init();
+    return ioMulti;
+  };
+}
+class IoPeerBridge {
+  constructor(_io, _socket) {
+    this._io = _io;
+    this._socket = _socket;
+  }
+  _eventHandlers = /* @__PURE__ */ new Map();
+  /**
+   * Starts the bridge by setting up connection event handlers and
+   * automatically registering all Io methods.
+   */
+  start() {
+    this._socket.on("connect", () => this._handleConnect());
+    this._socket.on("disconnect", () => this._handleDisconnect());
+    this._registerIoMethods();
+  }
+  /**
+   * Stops the bridge by removing all event handlers.
+   */
+  stop() {
+    this._socket.off("connect", () => this._handleConnect());
+    this._socket.off("disconnect", () => this._handleDisconnect());
+    for (const [eventName, handler] of this._eventHandlers) {
+      this._socket.off(eventName, handler);
+    }
+    this._eventHandlers.clear();
+  }
+  /**
+   * Automatically registers all Io interface methods as socket event handlers.
+   */
+  _registerIoMethods() {
+    const ioMethods = [
+      "init",
+      "isReady",
+      "close",
+      "tableExists",
+      "createOrExtendTable",
+      "write",
+      "readRows",
+      "rowCount",
+      "dumpTable",
+      "dump",
+      "contentType",
+      "rawTableCfgs"
+    ];
+    for (const methodName of ioMethods) {
+      this.registerEvent(methodName);
+    }
+  }
+  /**
+   * Registers a socket event to be translated to an Io method call.
+   *
+   * @param eventName - The socket event name (should match an Io method name)
+   * @param ioMethodName - (Optional) The Io method name if different from eventName
+   */
+  registerEvent(eventName, ioMethodName) {
+    const methodName = ioMethodName || eventName;
+    const handler = (...args) => {
+      const callback = args[args.length - 1];
+      const methodArgs = args.slice(0, -1);
+      const ioMethod = this._io[methodName];
+      if (typeof ioMethod !== "function") {
+        const error = new Error(
+          `Method "${methodName}" not found on Io instance`
+        );
+        if (typeof callback === "function") {
+          callback(null, error);
+        }
+        return;
+      }
+      ioMethod.apply(this._io, methodArgs).then((result) => {
+        if (typeof callback === "function") {
+          callback(result, null);
+        }
+      }).catch((error) => {
+        if (typeof callback === "function") {
+          callback(null, error);
+        }
+      });
+    };
+    this._eventHandlers.set(eventName, handler);
+    this._socket.on(eventName, handler);
+  }
+  /**
+   * Registers multiple socket events at once.
+   *
+   * @param eventNames - Array of event names to register
+   */
+  registerEvents(eventNames) {
+    for (const eventName of eventNames) {
+      this.registerEvent(eventName);
+    }
+  }
+  /**
+   * Unregisters a socket event handler.
+   *
+   * @param eventName - The event name to unregister
+   */
+  unregisterEvent(eventName) {
+    const handler = this._eventHandlers.get(eventName);
+    if (handler) {
+      this._socket.off(eventName, handler);
+      this._eventHandlers.delete(eventName);
+    }
+  }
+  /**
+   * Emits a result back through the socket.
+   *
+   * @param eventName - The event name to emit
+   * @param data - The data to send
+   */
+  emitToSocket(eventName, ...data) {
+    this._socket.emit(eventName, ...data);
+  }
+  /**
+   * Calls an Io method directly and emits the result through the socket.
+   *
+   * @param ioMethodName - The Io method to call
+   * @param socketEventName - The socket event to emit with the result
+   * @param args - Arguments to pass to the Io method
+   */
+  async callIoAndEmit(ioMethodName, socketEventName, ...args) {
+    try {
+      const ioMethod = this._io[ioMethodName];
+      if (typeof ioMethod !== "function") {
+        throw new Error(`Method "${ioMethodName}" not found on Io instance`);
+      }
+      const result = await ioMethod.apply(this._io, args);
+      this._socket.emit(socketEventName, result, null);
+    } catch (error) {
+      this._socket.emit(socketEventName, null, error);
+    }
+  }
+  /* v8 ignore next -- @preserve */
+  _handleConnect() {
+  }
+  /* v8 ignore next -- @preserve */
+  _handleDisconnect() {
+  }
+  /**
+   * Gets the current socket instance.
+   */
+  get socket() {
+    return this._socket;
+  }
+  /**
+   * Gets the current Io instance.
+   */
+  get io() {
+    return this._io;
+  }
+  /**
+   * Returns whether the socket is currently connected.
+   */
+  get isConnected() {
+    return this._socket.connected;
+  }
+}
+class IoServer {
+  constructor(_io) {
+    this._io = _io;
+  }
+  _sockets = [];
+  // ...........................................................................
+  /**
+   * Adds a socket to the IoServer instance.
+   * @param socket - The socket to add.
+   */
+  async addSocket(socket) {
+    await this._addTransportLayer(socket);
+    this._sockets.push(socket);
+  }
+  // ...........................................................................
+  /**
+   * Removes a transport layer from the given socket.
+   * @param socket - The socket to remove the transport layer from.
+   */
+  removeSocket(socket) {
+    this._sockets = this._sockets.filter((s) => s !== socket);
+  }
+  // ...........................................................................
+  /**
+   * Adds a transport layer to the given socket.
+   * @param socket - The socket to add the transport layer to.
+   */
+  async _addTransportLayer(socket) {
+    const crud = this._generateTransportLayerCRUD(this._io);
+    for (const [key, fn] of Object.entries(crud)) {
+      socket.on(key, (...args) => {
+        const cb = args[args.length - 1];
+        fn.apply(this, args.slice(0, -1)).then((result) => {
+          cb(result, null);
+        }).catch((err) => {
+          cb(null, err);
+        });
+      });
+    }
+  }
+  // ...........................................................................
+  /**
+   * Creates or extends a table with the given configuration.
+   * @param request - An object containing the table configuration.
+   */
+  async createOrExtendTable(request) {
+    return this._io.createOrExtendTable(request);
+  }
+  // ...........................................................................
+  /**
+   * Generates a transport layer object for the given Io instance.
+   * @param io - The Io instance to generate the transport layer for.
+   * @returns An object containing methods that correspond to the Io interface.
+   */
+  _generateTransportLayerCRUD = (io) => ({
+    init: () => io.init(),
+    close: () => io.close(),
+    isOpen: () => new Promise((resolve) => resolve(io.isOpen)),
+    isReady: () => io.isReady(),
+    dump: () => io.dump(),
+    dumpTable: (request) => io.dumpTable(request),
+    contentType: (request) => io.contentType(request),
+    tableExists: (tableKey) => io.tableExists(tableKey),
+    createOrExtendTable: (request) => this.createOrExtendTable(request),
+    rawTableCfgs: () => io.rawTableCfgs(),
+    write: (request) => io.write(request),
+    readRows: (request) => io.readRows(request),
+    rowCount: (table) => io.rowCount(table)
+  });
+}
+class SocketMock {
+  connected = false;
+  disconnected = true;
+  _listeners = /* @__PURE__ */ new Map();
+  _onceListeners = /* @__PURE__ */ new Map();
+  connect() {
+    if (!this.connected) {
+      this.connected = true;
+      this.disconnected = false;
+      this.emit("connect");
+    }
+  }
+  disconnect() {
+    if (this.connected) {
+      this.connected = false;
+      this.disconnected = true;
+      this.emit("disconnect");
+    }
+  }
+  on(eventName, listener) {
+    if (!this._listeners.has(eventName)) {
+      this._listeners.set(eventName, []);
+    }
+    this._listeners.get(eventName).push(listener);
+    return this;
+  }
+  once(eventName, listener) {
+    if (!this._onceListeners.has(eventName)) {
+      this._onceListeners.set(eventName, []);
+    }
+    this._onceListeners.get(eventName).push(listener);
+    return this;
+  }
+  off(eventName, listener) {
+    if (listener) {
+      const regularListeners = this._listeners.get(eventName);
+      if (regularListeners) {
+        const index = regularListeners.indexOf(listener);
+        if (index > -1) {
+          regularListeners.splice(index, 1);
+        }
+      }
+      const onceListeners = this._onceListeners.get(eventName);
+      if (onceListeners) {
+        const index = onceListeners.indexOf(listener);
+        if (index > -1) {
+          onceListeners.splice(index, 1);
+        }
+      }
+    } else {
+      this._listeners.delete(eventName);
+      this._onceListeners.delete(eventName);
+    }
+    return this;
+  }
+  emit(eventName, ...args) {
+    let hasListeners = false;
+    const regularListeners = this._listeners.get(eventName);
+    if (regularListeners && regularListeners.length > 0) {
+      hasListeners = true;
+      [...regularListeners].forEach((listener) => {
+        try {
+          listener(...args);
+        } catch (error) {
+          console.error(
+            `Error in listener for event ${String(eventName)}:`,
+            error
+          );
+        }
+      });
+    }
+    const onceListeners = this._onceListeners.get(eventName);
+    if (onceListeners && onceListeners.length > 0) {
+      hasListeners = true;
+      const listenersToCall = [...onceListeners];
+      this._onceListeners.delete(eventName);
+      listenersToCall.forEach((listener) => {
+        try {
+          listener(...args);
+        } catch (error) {
+          console.error(
+            `Error in once listener for event ${String(eventName)}:`,
+            error
+          );
+        }
+      });
+    }
+    return hasListeners;
+  }
+  removeAllListeners(eventName) {
+    if (eventName !== void 0) {
+      this._listeners.delete(eventName);
+      this._onceListeners.delete(eventName);
+    } else {
+      this._listeners.clear();
+      this._onceListeners.clear();
+    }
+    return this;
+  }
+  listenerCount(eventName) {
+    const regularCount = this._listeners.get(eventName)?.length || 0;
+    const onceCount = this._onceListeners.get(eventName)?.length || 0;
+    return regularCount + onceCount;
+  }
+  listeners(eventName) {
+    const regularListeners = this._listeners.get(eventName) || [];
+    const onceListeners = this._onceListeners.get(eventName) || [];
+    return [...regularListeners, ...onceListeners];
+  }
+  eventNames() {
+    const allEvents = /* @__PURE__ */ new Set([
+      ...this._listeners.keys(),
+      ...this._onceListeners.keys()
+    ]);
+    return Array.from(allEvents);
+  }
+  // Test helper methods
+  reset() {
+    this.connected = false;
+    this.disconnected = true;
+    this.removeAllListeners();
+  }
+  simulateError(error) {
+    this.emit("error", error);
+  }
+  simulateMessage(message) {
+    this.emit("message", message);
+  }
+  // Get internal state for testing
+  getListeners() {
+    return new Map(this._listeners);
+  }
+  getOnceListeners() {
+    return new Map(this._onceListeners);
+  }
+}
+function createSocketPair() {
+  const socketA = new DirectionalSocketMock();
+  const socketB = new DirectionalSocketMock();
+  socketA._setPeer(socketB);
+  socketB._setPeer(socketA);
+  return [socketA, socketB];
+}
+class DirectionalSocketMock {
+  connected = false;
+  disconnected = true;
+  _peer;
+  _listeners = /* @__PURE__ */ new Map();
+  _onceListeners = /* @__PURE__ */ new Map();
+  _setPeer(peer) {
+    this._peer = peer;
+  }
+  connect() {
+    if (!this.connected) {
+      this.connected = true;
+      this.disconnected = false;
+      this._triggerLocal("connect");
+      if (this._peer) {
+        this._peer._triggerLocal("connect");
+      }
+    }
+  }
+  disconnect() {
+    if (this.connected) {
+      this.connected = false;
+      this.disconnected = true;
+      this._triggerLocal("disconnect");
+      if (this._peer) {
+        this._peer._triggerLocal("disconnect");
+      }
+    }
+  }
+  on(eventName, listener) {
+    if (!this._listeners.has(eventName)) {
+      this._listeners.set(eventName, []);
+    }
+    this._listeners.get(eventName).push(listener);
+    return this;
+  }
+  once(eventName, listener) {
+    if (!this._onceListeners.has(eventName)) {
+      this._onceListeners.set(eventName, []);
+    }
+    this._onceListeners.get(eventName).push(listener);
+    return this;
+  }
+  off(eventName, listener) {
+    if (listener) {
+      const regularListeners = this._listeners.get(eventName);
+      if (regularListeners) {
+        const index = regularListeners.indexOf(listener);
+        if (index > -1) regularListeners.splice(index, 1);
+      }
+      const onceListeners = this._onceListeners.get(eventName);
+      if (onceListeners) {
+        const index = onceListeners.indexOf(listener);
+        if (index > -1) onceListeners.splice(index, 1);
+      }
+    } else {
+      this._listeners.delete(eventName);
+      this._onceListeners.delete(eventName);
+    }
+    return this;
+  }
+  /**
+   * Emits an event to the PEER socket (cross-socket emission).
+   * This is the key difference from SocketMock - emit() sends to the other side,
+   * not to local listeners.
+   *
+   * Implements Socket.IO acknowledgement pattern: the last argument can be a callback
+   * that the peer will invoke to send a response back.
+   */
+  emit(eventName, ...args) {
+    if (!this._peer) {
+      console.warn(
+        `DirectionalSocketMock.emit: No peer connected for event ${String(eventName)}`
+      );
+      return false;
+    }
+    this._peer._triggerLocal(eventName, ...args);
+    return true;
+  }
+  /**
+   * Triggers listeners on THIS socket (local emission).
+   * Used internally when receiving events from peer.
+   */
+  _triggerLocal(eventName, ...args) {
+    const regularListeners = this._listeners.get(eventName);
+    if (regularListeners) {
+      [...regularListeners].forEach((listener) => {
+        try {
+          listener(...args);
+        } catch (error) {
+          console.error(`Error in listener for ${String(eventName)}:`, error);
+        }
+      });
+    }
+    const onceListeners = this._onceListeners.get(eventName);
+    if (onceListeners) {
+      const listenersToCall = [...onceListeners];
+      this._onceListeners.delete(eventName);
+      listenersToCall.forEach((listener) => {
+        try {
+          listener(...args);
+        } catch (error) {
+          console.error(
+            `Error in once listener for ${String(eventName)}:`,
+            error
+          );
+        }
+      });
+    }
+  }
+  removeAllListeners(eventName) {
+    if (eventName !== void 0) {
+      this._listeners.delete(eventName);
+      this._onceListeners.delete(eventName);
+    } else {
+      this._listeners.clear();
+      this._onceListeners.clear();
+    }
+    return this;
+  }
+  listenerCount(eventName) {
+    const regularCount = this._listeners.get(eventName)?.length || 0;
+    const onceCount = this._onceListeners.get(eventName)?.length || 0;
+    return regularCount + onceCount;
+  }
+  listeners(eventName) {
+    const regularListeners = this._listeners.get(eventName) || [];
+    const onceListeners = this._onceListeners.get(eventName) || [];
+    return [...regularListeners, ...onceListeners];
+  }
+  eventNames() {
+    const allEvents = /* @__PURE__ */ new Set([
+      ...this._listeners.keys(),
+      ...this._onceListeners.keys()
+    ]);
+    return Array.from(allEvents);
+  }
+}
+class BsMem {
+  blobs = /* @__PURE__ */ new Map();
+  /**
+   * Convert content to Buffer
+   * @param content - Content to convert (Buffer, string, or ReadableStream)
+   */
+  async toBuffer(content) {
+    if (Buffer.isBuffer(content)) {
+      return content;
+    }
+    if (typeof content === "string") {
+      return Buffer.from(content, "utf8");
+    }
+    const reader = content.getReader();
+    const chunks = [];
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      chunks.push(value);
+    }
+    return Buffer.concat(chunks);
+  }
+  async setBlob(content) {
+    const buffer = await this.toBuffer(content);
+    const blobId = hshBuffer(buffer);
+    const existing = this.blobs.get(blobId);
+    if (existing) {
+      return existing.properties;
+    }
+    const properties = {
+      blobId,
+      size: buffer.length,
+      createdAt: /* @__PURE__ */ new Date()
+    };
+    this.blobs.set(blobId, {
+      content: buffer,
+      properties
+    });
+    return properties;
+  }
+  async getBlob(blobId, options) {
+    const stored = this.blobs.get(blobId);
+    if (!stored) {
+      throw new Error(`Blob not found: ${blobId}`);
+    }
+    let content = stored.content;
+    if (options?.range) {
+      const { start, end } = options.range;
+      content = stored.content.subarray(start, end);
+    }
+    return {
+      content,
+      properties: stored.properties
+    };
+  }
+  async getBlobStream(blobId) {
+    const stored = this.blobs.get(blobId);
+    if (!stored) {
+      throw new Error(`Blob not found: ${blobId}`);
+    }
+    const nodeStream = Readable.from(stored.content);
+    return Readable.toWeb(nodeStream);
+  }
+  async deleteBlob(blobId) {
+    const deleted = this.blobs.delete(blobId);
+    if (!deleted) {
+      throw new Error(`Blob not found: ${blobId}`);
+    }
+  }
+  async blobExists(blobId) {
+    return this.blobs.has(blobId);
+  }
+  async getBlobProperties(blobId) {
+    const stored = this.blobs.get(blobId);
+    if (!stored) {
+      throw new Error(`Blob not found: ${blobId}`);
+    }
+    return stored.properties;
+  }
+  async listBlobs(options) {
+    let blobs = Array.from(this.blobs.values()).map(
+      (stored) => stored.properties
+    );
+    if (options?.prefix) {
+      blobs = blobs.filter((blob) => blob.blobId.startsWith(options.prefix));
+    }
+    blobs.sort((a, b) => a.blobId.localeCompare(b.blobId));
+    const maxResults = options?.maxResults ?? blobs.length;
+    let startIndex = 0;
+    if (options?.continuationToken) {
+      const tokenIndex = blobs.findIndex(
+        (blob) => blob.blobId === options.continuationToken
+      );
+      startIndex = tokenIndex === -1 ? 0 : tokenIndex + 1;
+    }
+    const endIndex = Math.min(startIndex + maxResults, blobs.length);
+    const pageBlobs = blobs.slice(startIndex, endIndex);
+    const continuationToken = endIndex < blobs.length ? pageBlobs[pageBlobs.length - 1]?.blobId : void 0;
+    return {
+      blobs: pageBlobs,
+      continuationToken
+    };
+  }
+  async generateSignedUrl(blobId, expiresIn, permissions) {
+    if (!this.blobs.has(blobId)) {
+      throw new Error(`Blob not found: ${blobId}`);
+    }
+    const expires = Date.now() + expiresIn * 1e3;
+    const perm = permissions ?? "read";
+    return `mem://${blobId}?expires=${expires}&permissions=${perm}`;
+  }
+  /**
+   * Clear all blobs from storage (useful for testing)
+   */
+  clear() {
+    this.blobs.clear();
+  }
+  /**
+   * Get the number of blobs in storage
+   */
+  get size() {
+    return this.blobs.size;
+  }
+}
+class BsPeer {
+  constructor(_socket) {
+    this._socket = _socket;
+  }
+  isOpen = false;
+  // ...........................................................................
+  /**
+   * Initializes the Peer connection.
+   */
+  async init() {
+    this._socket.on("connect", () => {
+      this.isOpen = true;
+    });
+    this._socket.on("disconnect", () => {
+      this.isOpen = false;
+    });
+    this._socket.connect();
+    return new Promise((resolve) => {
+      if (this._socket.connected) {
+        this.isOpen = true;
+        resolve();
+      } else {
+        this._socket.on("connect", () => {
+          resolve();
+        });
+      }
+    });
+  }
+  // ...........................................................................
+  /**
+   * Closes the Peer connection.
+   */
+  async close() {
+    if (!this._socket.connected) return;
+    return new Promise((resolve) => {
+      this._socket.on("disconnect", () => {
+        resolve();
+      });
+      this._socket.disconnect();
+    });
+  }
+  // ...........................................................................
+  /**
+   * Returns a promise that resolves once the Peer connection is ready.
+   */
+  async isReady() {
+    if (!!this._socket && this._socket.connected === true) this.isOpen = true;
+    else this.isOpen = false;
+    return !!this.isOpen ? Promise.resolve() : Promise.reject();
+  }
+  // ...........................................................................
+  /**
+   * Stores a blob from Buffer, string, or ReadableStream and returns properties.
+   * @param content - The blob content to store
+   * @returns Promise resolving to blob properties
+   */
+  setBlob(content) {
+    return new Promise((resolve, reject) => {
+      if (content instanceof ReadableStream) {
+        const reader = content.getReader();
+        const chunks = [];
+        const readStream = async () => {
+          try {
+            while (true) {
+              const { done, value } = await reader.read();
+              if (done) break;
+              chunks.push(value);
+            }
+            const totalLength = chunks.reduce(
+              (sum, chunk) => sum + chunk.length,
+              0
+            );
+            const buffer = Buffer.concat(
+              chunks.map((chunk) => Buffer.from(chunk)),
+              totalLength
+            );
+            this._socket.emit(
+              "setBlob",
+              buffer,
+              (error, result) => {
+                if (error) reject(error);
+                else resolve(result);
+              }
+            );
+          } catch (err) {
+            reject(err);
+          }
+        };
+        readStream();
+      } else {
+        this._socket.emit(
+          "setBlob",
+          content,
+          (error, result) => {
+            if (error) reject(error);
+            else resolve(result);
+          }
+        );
+      }
+    });
+  }
+  // ...........................................................................
+  /**
+   * Retrieves a blob by its ID as a Buffer.
+   * @param blobId - The unique identifier of the blob
+   * @param options - Download options
+   * @returns Promise resolving to blob content and properties
+   */
+  getBlob(blobId, options) {
+    return new Promise((resolve, reject) => {
+      this._socket.emit(
+        "getBlob",
+        blobId,
+        options,
+        (error, result) => {
+          if (error) reject(error);
+          else resolve(result);
+        }
+      );
+    });
+  }
+  // ...........................................................................
+  /**
+   * Retrieves a blob by its ID as a ReadableStream.
+   * @param blobId - The unique identifier of the blob
+   * @returns Promise resolving to readable stream
+   */
+  getBlobStream(blobId) {
+    return new Promise((resolve, reject) => {
+      this._socket.emit(
+        "getBlobStream",
+        blobId,
+        (error, result) => {
+          if (error) reject(error);
+          else resolve(result);
+        }
+      );
+    });
+  }
+  // ...........................................................................
+  /**
+   * Deletes a blob by its ID.
+   * @param blobId - The unique identifier of the blob
+   * @returns Promise that resolves when deletion is complete
+   */
+  deleteBlob(blobId) {
+    return new Promise((resolve, reject) => {
+      this._socket.emit("deleteBlob", blobId, (error) => {
+        if (error) reject(error);
+        else resolve();
+      });
+    });
+  }
+  // ...........................................................................
+  /**
+   * Checks if a blob exists.
+   * @param blobId - The unique identifier of the blob
+   * @returns Promise resolving to true if blob exists
+   */
+  blobExists(blobId) {
+    return new Promise((resolve, reject) => {
+      this._socket.emit(
+        "blobExists",
+        blobId,
+        (error, exists) => {
+          if (error) reject(error);
+          else resolve(exists);
+        }
+      );
+    });
+  }
+  // ...........................................................................
+  /**
+   * Gets blob properties (size, createdAt) without retrieving content.
+   * @param blobId - The unique identifier of the blob
+   * @returns Promise resolving to blob properties
+   */
+  getBlobProperties(blobId) {
+    return new Promise((resolve, reject) => {
+      this._socket.emit(
+        "getBlobProperties",
+        blobId,
+        (error, result) => {
+          if (error) reject(error);
+          else resolve(result);
+        }
+      );
+    });
+  }
+  // ...........................................................................
+  /**
+   * Lists all blobs with optional filtering and pagination.
+   * @param options - Optional listing configuration
+   * @returns Promise resolving to list of blobs
+   */
+  listBlobs(options) {
+    return new Promise((resolve, reject) => {
+      this._socket.emit(
+        "listBlobs",
+        options || {},
+        (error, result) => {
+          if (error) reject(error);
+          else resolve(result);
+        }
+      );
+    });
+  }
+  // ...........................................................................
+  /**
+   * Generates a signed URL for temporary blob access.
+   * @param blobId - The unique identifier of the blob
+   * @param expiresIn - Expiration time in seconds
+   * @param permissions - Permissions for the URL
+   * @returns Promise resolving to signed URL
+   */
+  generateSignedUrl(blobId, expiresIn, permissions) {
+    return new Promise((resolve, reject) => {
+      this._socket.emit(
+        "generateSignedUrl",
+        blobId,
+        expiresIn,
+        permissions,
+        (error, url) => {
+          if (error) reject(error);
+          else resolve(url);
+        }
+      );
+    });
+  }
+}
+class PeerSocketMock2 {
+  constructor(_bs) {
+    this._bs = _bs;
+  }
+  _listenersMap = /* @__PURE__ */ new Map();
+  connected = false;
+  disconnected = true;
+  // ............................................................................
+  /**
+   * Removes a specific listener for the specified event.
+   * @param eventName - The event name
+   * @param listener - The listener function to remove
+   * @returns This socket instance for chaining
+   */
+  off(eventName, listener) {
+    const listeners = this._listenersMap.get(eventName) || [];
+    const index = listeners.indexOf(listener);
+    if (index !== -1) {
+      listeners.splice(index, 1);
+      this._listenersMap.set(eventName, listeners);
+    }
+    return this;
+  }
+  // ............................................................................
+  /**
+   * Removes all listeners for the specified event, or all listeners if no event is specified.
+   * @param eventName - Optional event name
+   * @returns This socket instance for chaining
+   */
+  removeAllListeners(eventName) {
+    if (eventName) {
+      this._listenersMap.delete(eventName);
+    } else {
+      this._listenersMap.clear();
+    }
+    return this;
+  }
+  // ............................................................................
+  /**
+   * Registers an event listener for the specified event.
+   * @param eventName - The event name
+   * @param listener - The listener function to register
+   * @returns This socket instance for chaining
+   */
+  on(eventName, listener) {
+    if (!this._listenersMap.has(eventName)) {
+      this._listenersMap.set(eventName, []);
+    }
+    this._listenersMap.get(eventName).push(listener);
+    return this;
+  }
+  // ...........................................................................
+  /**
+   * Simulates a connection event.
+   */
+  connect() {
+    this.connected = true;
+    this.disconnected = false;
+    const listeners = this._listenersMap.get("connect") || [];
+    for (const cb of listeners) {
+      cb({});
+    }
+    return this;
+  }
+  // ...........................................................................
+  /**
+   * Simulates a disconnection event.
+   */
+  disconnect() {
+    this.connected = false;
+    this.disconnected = true;
+    const listeners = this._listenersMap.get("disconnect") || [];
+    for (const cb of listeners) {
+      cb({});
+    }
+    return this;
+  }
+  // ............................................................................
+  /**
+   * Emits an event, invoking the corresponding method on the Bs instance.
+   * @param eventName - The event name
+   * @param args - Event arguments
+   * @returns True if the event was handled
+   */
+  emit(eventName, ...args) {
+    const fn = this._bs[eventName];
+    if (typeof fn !== "function") {
+      throw new Error(`Event ${eventName.toString()} not supported`);
+    }
+    const cb = args[args.length - 1];
+    fn.apply(this._bs, args.slice(0, -1)).then((result) => {
+      cb(null, result);
+    }).catch((err) => {
+      cb(err);
+    });
+    return true;
+  }
+}
+class BsMulti {
+  constructor(_stores) {
+    this._stores = _stores;
+  }
+  // ...........................................................................
+  /**
+   * Initializes the BsMulti by assigning IDs to all underlying Bs instances.
+   * All underlying Bs instances must already be initialized.
+   */
+  async init() {
+    for (let idx = 0; idx < this._stores.length; idx++) {
+      this._stores[idx] = { ...this._stores[idx], id: `bs-${idx}` };
+    }
+    return Promise.resolve();
+  }
+  // ...........................................................................
+  /**
+   * Stores a blob in all writable Bs instances in parallel.
+   * @param content - The blob content to store
+   * @returns Promise resolving to blob properties from the first successful write
+   */
+  async setBlob(content) {
+    if (this.writables.length === 0) {
+      throw new Error("No writable Bs available");
+    }
+    const writes = this.writables.map(({ bs }) => bs.setBlob(content));
+    const results = await Promise.all(writes);
+    return results[0];
+  }
+  // ...........................................................................
+  /**
+   * Retrieves a blob from the highest priority readable Bs instance.
+   * Hot-swaps the blob to all writable instances for caching.
+   * @param blobId - The blob identifier
+   * @param options - Download options
+   * @returns Promise resolving to blob content and properties
+   */
+  async getBlob(blobId, options) {
+    if (this.readables.length === 0) {
+      throw new Error("No readable Bs available");
+    }
+    let result;
+    let readFrom = "";
+    const errors = [];
+    for (const readable of this.readables) {
+      try {
+        result = await readable.bs.getBlob(blobId, options);
+        readFrom = readable.id ?? "";
+        break;
+      } catch (e) {
+        errors.push(e);
+        continue;
+      }
+    }
+    if (!result) {
+      const notFoundErrors = errors.filter(
+        (err) => err.message.includes("Blob not found")
+      );
+      if (notFoundErrors.length === errors.length) {
+        throw new Error(`Blob not found: ${blobId}`);
+      } else {
+        throw errors[0];
+      }
+    }
+    if (this.writables.length > 0) {
+      const hotSwapWrites = this.writables.filter((writable) => writable.id !== readFrom).map(({ bs }) => bs.setBlob(result.content).catch(() => {
+      }));
+      await Promise.all(hotSwapWrites);
+    }
+    return result;
+  }
+  // ...........................................................................
+  /**
+   * Retrieves a blob as a ReadableStream from the highest priority readable Bs instance.
+   * @param blobId - The blob identifier
+   * @returns Promise resolving to a ReadableStream
+   */
+  async getBlobStream(blobId) {
+    if (this.readables.length === 0) {
+      throw new Error("No readable Bs available");
+    }
+    const errors = [];
+    for (const readable of this.readables) {
+      try {
+        return await readable.bs.getBlobStream(blobId);
+      } catch (e) {
+        errors.push(e);
+        continue;
+      }
+    }
+    const notFoundErrors = errors.filter(
+      (err) => err.message.includes("Blob not found")
+    );
+    if (notFoundErrors.length === errors.length) {
+      throw new Error(`Blob not found: ${blobId}`);
+    } else {
+      throw errors[0];
+    }
+  }
+  // ...........................................................................
+  /**
+   * Deletes a blob from all writable Bs instances in parallel.
+   * @param blobId - The blob identifier
+   */
+  async deleteBlob(blobId) {
+    if (this.writables.length === 0) {
+      throw new Error("No writable Bs available");
+    }
+    const deletes = this.writables.map(({ bs }) => bs.deleteBlob(blobId));
+    await Promise.all(deletes);
+  }
+  // ...........................................................................
+  /**
+   * Checks if a blob exists in any readable Bs instance.
+   * @param blobId - The blob identifier
+   * @returns Promise resolving to true if blob exists in any readable
+   */
+  async blobExists(blobId) {
+    if (this.readables.length === 0) {
+      throw new Error("No readable Bs available");
+    }
+    for (const readable of this.readables) {
+      try {
+        const exists = await readable.bs.blobExists(blobId);
+        if (exists) {
+          return true;
+        }
+      } catch {
+        continue;
+      }
+    }
+    return false;
+  }
+  // ...........................................................................
+  /**
+   * Gets blob properties from the highest priority readable Bs instance.
+   * @param blobId - The blob identifier
+   * @returns Promise resolving to blob properties
+   */
+  async getBlobProperties(blobId) {
+    if (this.readables.length === 0) {
+      throw new Error("No readable Bs available");
+    }
+    const errors = [];
+    for (const readable of this.readables) {
+      try {
+        return await readable.bs.getBlobProperties(blobId);
+      } catch (e) {
+        errors.push(e);
+        continue;
+      }
+    }
+    const notFoundErrors = errors.filter(
+      (err) => err.message.includes("Blob not found")
+    );
+    if (notFoundErrors.length === errors.length) {
+      throw new Error(`Blob not found: ${blobId}`);
+    } else {
+      throw errors[0];
+    }
+  }
+  // ...........................................................................
+  /**
+   * Lists blobs by merging results from all readable Bs instances.
+   * Deduplicates by blobId (content-addressable).
+   * @param options - Listing options
+   * @returns Promise resolving to list of blobs
+   */
+  async listBlobs(options) {
+    if (this.readables.length === 0) {
+      throw new Error("No readable Bs available");
+    }
+    const blobMap = /* @__PURE__ */ new Map();
+    for (const readable of this.readables) {
+      try {
+        let continuationToken2;
+        do {
+          const result = await readable.bs.listBlobs({
+            prefix: options?.prefix,
+            // Apply prefix filter during collection
+            continuationToken: continuationToken2,
+            maxResults: 1e3
+            // Fetch in chunks from each store
+          });
+          for (const blob of result.blobs) {
+            if (!blobMap.has(blob.blobId)) {
+              blobMap.set(blob.blobId, blob);
+            }
+          }
+          continuationToken2 = result.continuationToken;
+        } while (continuationToken2);
+      } catch {
+        continue;
+      }
+    }
+    const blobs = Array.from(blobMap.values());
+    blobs.sort((a, b) => a.blobId.localeCompare(b.blobId));
+    const maxResults = options?.maxResults ?? blobs.length;
+    let startIndex = 0;
+    if (options?.continuationToken) {
+      const tokenIndex = blobs.findIndex(
+        (blob) => blob.blobId === options.continuationToken
+      );
+      startIndex = tokenIndex === -1 ? 0 : tokenIndex + 1;
+    }
+    const endIndex = Math.min(startIndex + maxResults, blobs.length);
+    const pageBlobs = blobs.slice(startIndex, endIndex);
+    const continuationToken = endIndex < blobs.length ? pageBlobs[pageBlobs.length - 1]?.blobId : void 0;
+    return {
+      blobs: pageBlobs,
+      continuationToken
+    };
+  }
+  // ...........................................................................
+  /**
+   * Generates a signed URL from the highest priority readable Bs instance.
+   * @param blobId - The blob identifier
+   * @param expiresIn - Expiration time in seconds
+   * @param permissions - Access permissions
+   * @returns Promise resolving to signed URL
+   */
+  async generateSignedUrl(blobId, expiresIn, permissions = "read") {
+    if (this.readables.length === 0) {
+      throw new Error("No readable Bs available");
+    }
+    const errors = [];
+    for (const readable of this.readables) {
+      try {
+        return await readable.bs.generateSignedUrl(
+          blobId,
+          expiresIn,
+          permissions
+        );
+      } catch (e) {
+        errors.push(e);
+        continue;
+      }
+    }
+    const notFoundErrors = errors.filter(
+      (err) => err.message.includes("Blob not found")
+    );
+    if (notFoundErrors.length === errors.length) {
+      throw new Error(`Blob not found: ${blobId}`);
+    } else {
+      throw errors[0];
+    }
+  }
+  // ...........................................................................
+  /**
+   * Gets the list of underlying readable Bs instances, sorted by priority.
+   */
+  get readables() {
+    return this._stores.filter((store) => store.read).sort((a, b) => a.priority - b.priority);
+  }
+  // ...........................................................................
+  /**
+   * Gets the list of underlying writable Bs instances, sorted by priority.
+   */
+  get writables() {
+    return this._stores.filter((store) => store.write).sort((a, b) => a.priority - b.priority);
+  }
+  // ...........................................................................
+  /**
+   * Example: Local cache (BsMem) + Remote server (BsPeer)
+   */
+  static example = async () => {
+    const bsRemoteMem = new BsMem();
+    const bsRemoteSocket = new PeerSocketMock2(bsRemoteMem);
+    const bsRemote = new BsPeer(bsRemoteSocket);
+    await bsRemote.init();
+    const bsLocal = new BsMem();
+    const stores = [
+      { bs: bsLocal, priority: 0, read: true, write: true },
+      // Cache first
+      { bs: bsRemote, priority: 1, read: true, write: false }
+      // Remote fallback
+    ];
+    const bsMulti = new BsMulti(stores);
+    await bsMulti.init();
+    return bsMulti;
+  };
+}
+class BsPeerBridge {
+  constructor(_bs, _socket) {
+    this._bs = _bs;
+    this._socket = _socket;
+  }
+  _eventHandlers = /* @__PURE__ */ new Map();
+  _handleConnectBound = this._handleConnect.bind(this);
+  _handleDisconnectBound = this._handleDisconnect.bind(this);
+  /**
+   * Starts the bridge by setting up connection event handlers and
+   * automatically registering all Bs methods.
+   */
+  start() {
+    this._socket.on("connect", this._handleConnectBound);
+    this._socket.on("disconnect", this._handleDisconnectBound);
+    this._registerBsMethods();
+  }
+  /**
+   * Stops the bridge by removing all event handlers.
+   */
+  stop() {
+    this._socket.off("connect", this._handleConnectBound);
+    this._socket.off("disconnect", this._handleDisconnectBound);
+    for (const [eventName, handler] of this._eventHandlers) {
+      this._socket.off(eventName, handler);
+    }
+    this._eventHandlers.clear();
+  }
+  /**
+   * Automatically registers all Bs interface methods as socket event handlers.
+   */
+  _registerBsMethods() {
+    const bsMethods = [
+      "getBlob",
+      "getBlobStream",
+      "blobExists",
+      "getBlobProperties",
+      "listBlobs"
+    ];
+    for (const methodName of bsMethods) {
+      this.registerEvent(methodName);
+    }
+  }
+  /**
+   * Registers a socket event to be translated to a Bs method call.
+   * @param eventName - The socket event name (should match a Bs method name)
+   * @param bsMethodName - (Optional) The Bs method name if different from eventName
+   */
+  registerEvent(eventName, bsMethodName) {
+    const methodName = bsMethodName || eventName;
+    const handler = (...args) => {
+      const callback = args[args.length - 1];
+      const methodArgs = args.slice(0, -1);
+      const bsMethod = this._bs[methodName];
+      if (typeof bsMethod !== "function") {
+        const error = new Error(
+          `Method "${methodName}" not found on Bs instance`
+        );
+        if (typeof callback === "function") {
+          callback(error, null);
+        }
+        return;
+      }
+      bsMethod.apply(this._bs, methodArgs).then((result) => {
+        if (typeof callback === "function") {
+          callback(null, result);
+        }
+      }).catch((error) => {
+        if (typeof callback === "function") {
+          callback(error, null);
+        }
+      });
+    };
+    this._eventHandlers.set(eventName, handler);
+    this._socket.on(eventName, handler);
+  }
+  /**
+   * Registers multiple socket events at once.
+   * @param eventNames - Array of event names to register
+   */
+  registerEvents(eventNames) {
+    for (const eventName of eventNames) {
+      this.registerEvent(eventName);
+    }
+  }
+  /**
+   * Unregisters a socket event handler.
+   * @param eventName - The event name to unregister
+   */
+  unregisterEvent(eventName) {
+    const handler = this._eventHandlers.get(eventName);
+    if (handler) {
+      this._socket.off(eventName, handler);
+      this._eventHandlers.delete(eventName);
+    }
+  }
+  /**
+   * Emits a result back through the socket.
+   * @param eventName - The event name to emit
+   * @param data - The data to send
+   */
+  emitToSocket(eventName, ...data) {
+    this._socket.emit(eventName, ...data);
+  }
+  /**
+   * Calls a Bs method directly and emits the result through the socket.
+   * @param bsMethodName - The Bs method to call
+   * @param socketEventName - The socket event to emit with the result
+   * @param args - Arguments to pass to the Bs method
+   */
+  async callBsAndEmit(bsMethodName, socketEventName, ...args) {
+    try {
+      const bsMethod = this._bs[bsMethodName];
+      if (typeof bsMethod !== "function") {
+        throw new Error(`Method "${bsMethodName}" not found on Bs instance`);
+      }
+      const result = await bsMethod.apply(this._bs, args);
+      this._socket.emit(socketEventName, null, result);
+    } catch (error) {
+      this._socket.emit(socketEventName, error, null);
+    }
+  }
+  /* v8 ignore next -- @preserve */
+  _handleConnect() {
+  }
+  /* v8 ignore next -- @preserve */
+  _handleDisconnect() {
+  }
+  /**
+   * Gets the current socket instance.
+   */
+  get socket() {
+    return this._socket;
+  }
+  /**
+   * Gets the current Bs instance.
+   */
+  get bs() {
+    return this._bs;
+  }
+  /**
+   * Returns whether the socket is currently connected.
+   */
+  get isConnected() {
+    return this._socket.connected;
+  }
+}
+class BsServer {
+  constructor(_bs) {
+    this._bs = _bs;
+  }
+  _sockets = [];
+  // ...........................................................................
+  /**
+   * Adds a socket to the BsServer instance.
+   * @param socket - The socket to add.
+   */
+  async addSocket(socket) {
+    await this._addTransportLayer(socket);
+    this._sockets.push(socket);
+  }
+  // ...........................................................................
+  /**
+   * Removes a socket from the BsServer instance.
+   * @param socket - The socket to remove.
+   */
+  removeSocket(socket) {
+    this._sockets = this._sockets.filter((s) => s !== socket);
+  }
+  // ...........................................................................
+  /**
+   * Adds a transport layer to the given socket.
+   * @param socket - The socket to add the transport layer to.
+   */
+  async _addTransportLayer(socket) {
+    const methods = this._generateTransportLayer(this._bs);
+    for (const [key, fn] of Object.entries(methods)) {
+      socket.on(key, (...args) => {
+        const cb = args[args.length - 1];
+        fn.apply(this, args.slice(0, -1)).then((result) => {
+          cb(null, result);
+        }).catch((err) => {
+          cb(err);
+        });
+      });
+    }
+  }
+  // ...........................................................................
+  /**
+   * Generates a transport layer object for the given Bs instance.
+   * @param bs - The Bs instance to generate the transport layer for.
+   * @returns An object containing methods that correspond to the Bs interface.
+   */
+  _generateTransportLayer = (bs) => ({
+    setBlob: (content) => bs.setBlob(content),
+    getBlob: (blobId, options) => bs.getBlob(blobId, options),
+    getBlobStream: (blobId) => bs.getBlobStream(blobId),
+    deleteBlob: (blobId) => bs.deleteBlob(blobId),
+    blobExists: (blobId) => bs.blobExists(blobId),
+    getBlobProperties: (blobId) => bs.getBlobProperties(blobId),
+    listBlobs: (options) => bs.listBlobs(options),
+    generateSignedUrl: (blobId, expiresIn, permissions) => bs.generateSignedUrl(blobId, expiresIn, permissions)
+  });
+}
+class BaseNode {
+  constructor(_localIo) {
+    this._localIo = _localIo;
+    if (!_localIo.isOpen) {
+      throw new Error("Local Io must be initialized and open");
+    }
+    this._localDb = new Db(this._localIo);
+  }
+  _localDb;
+  // ...........................................................................
+  /**
+   *  Creates tables in the local Db.
+   * @param cfgs - Table configurations
+   * @param cfgs.withInsertHistory - TableCfgs for tables with InsertHistory
+   * @param cfgs.withoutInsertHistory - TableCfgs for tables without InsertHistory
+   */
+  async createTables(cfgs) {
+    if (!this._localDb) throw new Error("Local Db not initialized");
+    for (const tableCfg of cfgs.withoutInsertHistory || []) {
+      await this._localDb.core.createTable(tableCfg);
+    }
+    for (const tableCfg of cfgs.withInsertHistory || []) {
+      await this._localDb.core.createTableWithInsertHistory(tableCfg);
+    }
+  }
+  // ...........................................................................
+  /**
+   * Imports Rljson data into the local Db.
+   * @param data - Rljson data to import
+   */
+  /* v8 ignore next -- @preserve */
+  async import(data) {
+    if (!this._localDb) throw new Error("Local Db not initialized");
+    await this._localDb.core.import(data);
+  }
+}
+function normalizeSocketBundle(socket) {
+  const bundle = socket;
+  if (bundle.ioUp && bundle.ioDown && bundle.bsUp && bundle.bsDown) {
+    return bundle;
+  }
+  const single = socket;
+  return {
+    ioUp: single,
+    ioDown: single,
+    bsUp: single,
+    bsDown: single
+  };
+}
+class Client extends BaseNode {
+  // ...........................................................................
+  /**
+   * Creates a Client instance
+   * @param _socketToServer - Socket or namespace bundle to connect to server
+   * @param _localIo - Local Io for local storage
+   * @param _localBs - Local Bs for local blob storage
+   */
+  constructor(_socketToServer, _localIo, _localBs) {
+    super(_localIo);
+    this._socketToServer = _socketToServer;
+    this._localIo = _localIo;
+    this._localBs = _localBs;
+  }
+  _ioMultiIos = [];
+  _ioMulti;
+  _bsMultiBss = [];
+  _bsMulti;
+  /**
+   * Initializes Io and Bs multis and their peer bridges.
+   * @returns The initialized Io implementation.
+   */
+  async init() {
+    await this._setupIo();
+    await this._setupBs();
+    await this.ready();
+    return this._ioMulti;
+  }
+  /**
+   * Resolves once the Io implementation is ready.
+   */
+  async ready() {
+    if (this._ioMulti) {
+      await this._ioMulti.isReady();
+    }
+  }
+  /**
+   * Closes client resources and clears internal state.
+   */
+  async tearDown() {
+    if (this._ioMulti && this._ioMulti.isOpen) {
+      this._ioMulti.close();
+    }
+    if (this._bsMulti) ;
+    this._ioMultiIos = [];
+    this._bsMultiBss = [];
+    this._ioMulti = void 0;
+    this._bsMulti = void 0;
+  }
+  /**
+   * Returns the Io implementation.
+   */
+  get io() {
+    return this._ioMulti;
+  }
+  /**
+   * Returns the Bs implementation.
+   */
+  get bs() {
+    return this._bsMulti;
+  }
+  /**
+   * Builds the Io multi with local and peer layers.
+   */
+  async _setupIo() {
+    const sockets = normalizeSocketBundle(this._socketToServer);
+    this._ioMultiIos.push({
+      io: this._localIo,
+      dump: true,
+      read: true,
+      write: true,
+      priority: 1
+    });
+    const ioPeerBridge = new IoPeerBridge(this._localIo, sockets.ioUp);
+    ioPeerBridge.start();
+    const ioPeer = await this._createIoPeer(sockets.ioDown);
+    this._ioMultiIos.push({
+      io: ioPeer,
+      dump: false,
+      read: true,
+      write: false,
+      priority: 2
+    });
+    this._ioMulti = new IoMulti(this._ioMultiIos);
+    await this._ioMulti.init();
+    await this._ioMulti.isReady();
+  }
+  /**
+   * Builds the Bs multi with local and peer layers.
+   */
+  async _setupBs() {
+    const sockets = normalizeSocketBundle(this._socketToServer);
+    this._bsMultiBss.push({
+      bs: this._localBs,
+      read: true,
+      write: true,
+      priority: 1
+    });
+    const bsPeerBridge = new BsPeerBridge(this._localBs, sockets.bsUp);
+    bsPeerBridge.start();
+    const bsPeer = await this._createBsPeer(sockets.bsDown);
+    this._bsMultiBss.push({
+      bs: bsPeer,
+      read: true,
+      write: false,
+      priority: 2
+    });
+    this._bsMulti = new BsMulti(this._bsMultiBss);
+    await this._bsMulti.init();
+  }
+  /**
+   * Creates and initializes a downstream Io peer.
+   * @param socket - Downstream socket to the server Io namespace.
+   */
+  async _createIoPeer(socket) {
+    const ioPeer = new IoPeer(socket);
+    await ioPeer.init();
+    await ioPeer.isReady();
+    return ioPeer;
+  }
+  /**
+   * Creates and initializes a downstream Bs peer.
+   * @param socket - Downstream socket to the server Bs namespace.
+   */
+  async _createBsPeer(socket) {
+    const bsPeer = new BsPeer(socket);
+    await bsPeer.init();
+    return bsPeer;
+  }
+}
+class Server extends BaseNode {
+  constructor(_route, _localIo, _localBs) {
+    super(_localIo);
+    this._route = _route;
+    this._localIo = _localIo;
+    this._localBs = _localBs;
+    const ioMultiIoLocal = {
+      io: this._localIo,
+      dump: true,
+      read: true,
+      write: true,
+      priority: 1
+    };
+    this._ios.push(ioMultiIoLocal);
+    this._ioMulti = new IoMulti(this._ios);
+    this._ioServer = new IoServer(this._ioMulti);
+    const bsMultiBsLocal = {
+      bs: this._localBs,
+      read: true,
+      write: true,
+      priority: 1
+    };
+    this._bss.push(bsMultiBsLocal);
+    this._bsMulti = new BsMulti(this._bss);
+    this._bsServer = new BsServer(this._bsMulti);
+  }
+  // Map of connected clients
+  // socket => Push: Send new Refs through Route
+  // io => Pull: Read from Clients Io
+  _clients = /* @__PURE__ */ new Map();
+  _ios = [];
+  _ioMulti;
+  // Storage => Let Clients read from Servers Io
+  _ioServer;
+  _bss = [];
+  _bsMulti;
+  // Storage => Let Clients read from Servers Bs
+  _bsServer;
+  // To avoid rebroadcasting the same edit refs multiple times
+  _multicastedRefs = /* @__PURE__ */ new Set();
+  _refreshPromise;
+  _pendingSockets = [];
+  /**
+   * Initializes Io and Bs multis on the server.
+   */
+  async init() {
+    await this._ioMulti.init();
+    await this._ioMulti.isReady();
+    await this._bsMulti.init();
+    await this.ready();
+  }
+  /**
+   * Resolves once the Io implementation is ready.
+   */
+  async ready() {
+    await this._ioMulti.isReady();
+  }
+  /**
+   * Adds a client socket, rebuilds multis, and refreshes servers.
+   * @param socket - Client socket to register.
+   * @returns The server instance.
+   */
+  async addSocket(socket) {
+    const sockets = normalizeSocketBundle(socket);
+    const clientId = `client_${this._clients.size}_${Math.random().toString(36).slice(2)}`;
+    const ioUp = sockets.ioUp;
+    const ioDown = sockets.ioDown;
+    const bsUp = sockets.bsUp;
+    const bsDown = sockets.bsDown;
+    ioUp.__clientId = clientId;
+    ioDown.__clientId = clientId;
+    bsUp.__clientId = clientId;
+    bsDown.__clientId = clientId;
+    const ioPeer = await this._createIoPeer(ioUp);
+    const bsPeer = await this._createBsPeer(bsUp);
+    this._registerClient(
+      clientId,
+      { ioUp, ioDown, bsUp, bsDown },
+      ioPeer,
+      bsPeer
+    );
+    this._pendingSockets.push({ ioDown, bsDown });
+    this._queueIoPeer(ioPeer);
+    this._queueBsPeer(bsPeer);
+    await this._queueRefresh();
+    this._removeAllListeners();
+    this._multicastRefs();
+    return this;
+  }
+  // ...........................................................................
+  /**
+   * Removes all listeners from all connected clients.
+   */
+  _removeAllListeners() {
+    for (const { ioUp } of this._clients.values()) {
+      ioUp.removeAllListeners(this._route.flat);
+    }
+  }
+  // ...........................................................................
+  /**
+   * Broadcasts incoming payloads from any client to all other connected clients.
+   * Ensures the sender is filtered out when broadcasting.
+   */
+  _multicastRefs = () => {
+    for (const [clientIdA, { ioUp: socketA }] of this._clients.entries()) {
+      socketA.on(this._route.flat, (payload) => {
+        const ref = payload.r;
+        if (this._multicastedRefs.has(ref)) {
+          return;
+        }
+        this._multicastedRefs.add(ref);
+        const p = payload;
+        if (p && p.__origin) {
+          return;
+        }
+        for (const [
+          clientIdB,
+          { ioDown: socketB }
+        ] of this._clients.entries()) {
+          if (clientIdA !== clientIdB) {
+            const forwarded = Object.assign({}, payload, {
+              __origin: clientIdA
+            });
+            socketB.emit(this._route.flat, forwarded);
+          }
+        }
+      });
+    }
+  };
+  get route() {
+    return this._route;
+  }
+  /**
+   * Returns the Io implementation.
+   */
+  get io() {
+    return this._ioMulti;
+  }
+  /**
+   * Returns the Bs implementation.
+   */
+  get bs() {
+    return this._bsMulti;
+  }
+  /**
+   * Returns the connected clients map.
+   */
+  get clients() {
+    return this._clients;
+  }
+  /**
+   * Creates and initializes a downstream Io peer for a socket.
+   * @param socket - Client socket to bind the peer to.
+   */
+  async _createIoPeer(socket) {
+    const ioPeer = new IoPeer(socket);
+    await ioPeer.init();
+    await ioPeer.isReady();
+    return ioPeer;
+  }
+  /**
+   * Creates and initializes a downstream Bs peer for a socket.
+   * @param socket - Client socket to bind the peer to.
+   */
+  async _createBsPeer(socket) {
+    const bsPeer = new BsPeer(socket);
+    await bsPeer.init();
+    return bsPeer;
+  }
+  /**
+   * Registers the client socket and peers.
+   * @param clientId - Stable client identifier.
+   * @param sockets - Directional sockets to register.
+   * @param io - Io peer associated with the client.
+   * @param bs - Bs peer associated with the client.
+   */
+  _registerClient(clientId, sockets, io, bs) {
+    this._clients.set(clientId, {
+      ioUp: sockets.ioUp,
+      ioDown: sockets.ioDown,
+      bsUp: sockets.bsUp,
+      bsDown: sockets.bsDown,
+      io,
+      bs
+    });
+  }
+  /**
+   * Queues an Io peer for inclusion in the Io multi.
+   * @param ioPeer - Io peer to add.
+   */
+  _queueIoPeer(ioPeer) {
+    this._ios.push({
+      io: ioPeer,
+      dump: false,
+      read: true,
+      write: false,
+      priority: 2
+    });
+  }
+  /**
+   * Queues a Bs peer for inclusion in the Bs multi.
+   * @param bsPeer - Bs peer to add.
+   */
+  _queueBsPeer(bsPeer) {
+    this._bss.push({
+      bs: bsPeer,
+      read: true,
+      write: false,
+      priority: 2
+    });
+  }
+  /**
+   * Rebuilds Io and Bs multis from queued peers.
+   */
+  async _rebuildMultis() {
+    this._ioMulti = new IoMulti(this._ios);
+    await this._ioMulti.init();
+    await this._ioMulti.isReady();
+    this._bsMulti = new BsMulti(this._bss);
+    await this._bsMulti.init();
+  }
+  /**
+   * Recreates servers and reattaches sockets.
+   */
+  async _refreshServers() {
+    this._ioServer._io = this._ioMulti;
+    this._bsServer._bs = this._bsMulti;
+    for (const pending of this._pendingSockets) {
+      await this._ioServer.addSocket(pending.ioDown);
+      await this._bsServer.addSocket(pending.bsDown);
+    }
+    this._pendingSockets = [];
+  }
+  /**
+   * Batches multi/server refreshes into a single queued task.
+   */
+  _queueRefresh() {
+    if (!this._refreshPromise) {
+      this._refreshPromise = Promise.resolve().then(async () => {
+        await this._rebuildMultis();
+        await this._refreshServers();
+      }).finally(() => {
+        this._refreshPromise = void 0;
+      });
+    }
+    return this._refreshPromise;
+  }
+  /** Example instance for test purposes */
+  static async example() {
+    const route = Route.fromFlat("example.route");
+    const io = new IoMem();
+    await io.init();
+    await io.isReady();
+    const bs = new BsMem();
+    const socket = new SocketMock();
+    socket.connect();
+    return new Server(route, io, bs).addSocket(socket);
+  }
+}
+async function createSharedTreeTable(io, treeKey) {
+  const db = new Db(io);
+  const treeCfg = createTreesTableCfg(treeKey);
+  await db.core.createTableWithInsertHistory(treeCfg);
+}
+async function runClientServerSetup(opts = {}) {
+  const baseDir = opts.baseDir || join(process.cwd(), "demo", "client-server");
+  const folderA = join(baseDir, "folder-a");
+  const folderB = join(baseDir, "folder-b");
+  const treeKey = opts.treeKey || "sharedTree";
+  await rm(baseDir, { recursive: true, force: true });
+  await mkdir(folderA, { recursive: true });
+  await mkdir(folderB, { recursive: true });
+  const route = Route.fromFlat(`/${treeKey}`);
+  const serverIo = new IoMem();
+  await serverIo.init();
+  await serverIo.isReady();
+  const { BsMem: BsMem2 } = await import("@rljson/bs");
+  const serverBsMem = new BsMem2();
+  await createSharedTreeTable(serverIo, treeKey);
+  const server = new Server(route, serverIo, serverBsMem);
+  await server.init();
+  const [serverSocketA, clientSocketA] = createSocketPair();
+  serverSocketA.connect();
+  await server.addSocket(serverSocketA);
+  const localIoA = new IoMem();
+  await localIoA.init();
+  await localIoA.isReady();
+  await createSharedTreeTable(localIoA, treeKey);
+  const localBsA = new BsMem2();
+  const clientA = new Client(clientSocketA, localIoA, localBsA);
+  await clientA.init();
+  const clientDbA = new Db(clientA.io);
+  const agentA = new FsAgent(folderA, clientA.bs);
+  const [serverSocketB, clientSocketB] = createSocketPair();
+  serverSocketB.connect();
+  await server.addSocket(serverSocketB);
+  const localIoB = new IoMem();
+  await localIoB.init();
+  await localIoB.isReady();
+  await createSharedTreeTable(localIoB, treeKey);
+  const localBsB = new BsMem2();
+  const clientB = new Client(clientSocketB, localIoB, localBsB);
+  await clientB.init();
+  const clientDbB = new Db(clientB.io);
+  const agentB = new FsAgent(folderB, clientB.bs);
+  const helloPathA = join(folderA, "hello.txt");
+  await writeFile(helloPathA, "Hello from Client A");
+  const rootRef = await agentA.storeInDb(clientDbA, treeKey, { notify: false });
+  await agentB.loadFromDb(clientDbB, treeKey, rootRef);
+  const contentB = await readFile(join(folderB, "hello.txt"), "utf8");
+  const cleanup = async () => {
+    await rm(baseDir, { recursive: true, force: true });
+  };
+  return { baseDir, folderA, folderB, contentB, cleanup };
+}
+export {
+  FsAgent,
+  FsBlobAdapter,
+  FsDbAdapter,
+  FsScanner,
+  runClientServerSetup
+};