@rljson/server 0.0.3

package/dist/server.js

@@ -0,0 +1,1403 @@
+import { hshBuffer } from "@rljson/hash";
+import { Readable } from "node:stream";
+import { IoPeerBridge, IoMulti, IoPeer, IoServer, IoMem, SocketMock } from "@rljson/io";
+import { Db } from "@rljson/db";
+import { Route } from "@rljson/rljson";
+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 PeerSocketMock {
+  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 PeerSocketMock(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();
+  /**
+   * Starts the bridge by setting up connection event handlers and
+   * automatically registering all Bs methods.
+   */
+  start() {
+    this._socket.on("connect", () => this._handleConnect());
+    this._socket.on("disconnect", () => this._handleDisconnect());
+    this._registerBsMethods();
+  }
+  /**
+   * 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 Bs interface methods as socket event handlers.
+   */
+  _registerBsMethods() {
+    const bsMethods = [
+      "setBlob",
+      "getBlob",
+      "getBlobStream",
+      "deleteBlob",
+      "blobExists",
+      "getBlobProperties",
+      "listBlobs",
+      "generateSignedUrl"
+    ];
+    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(null, error);
+        }
+        return;
+      }
+      bsMethod.apply(this._bs, 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 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, 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 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);
+  }
+}
+class Client extends BaseNode {
+  // ...........................................................................
+  /**
+   * Creates a Client instance
+   * @param _socketToServer - Socket 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() {
+    this._ioMultiIos.push({
+      io: this._localIo,
+      dump: true,
+      read: true,
+      write: true,
+      priority: 1
+    });
+    const ioPeerBridge = new IoPeerBridge(this._localIo, this._socketToServer);
+    ioPeerBridge.start();
+    const ioPeer = await this._createIoPeer();
+    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() {
+    this._bsMultiBss.push({
+      bs: this._localBs,
+      read: true,
+      write: true,
+      priority: 1
+    });
+    const bsPeerBridge = new BsPeerBridge(this._localBs, this._socketToServer);
+    bsPeerBridge.start();
+    const bsPeer = await this._createBsPeer();
+    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.
+   */
+  async _createIoPeer() {
+    const ioPeer = new IoPeer(this._socketToServer);
+    await ioPeer.init();
+    await ioPeer.isReady();
+    return ioPeer;
+  }
+  /**
+   * Creates and initializes a downstream Bs peer.
+   */
+  async _createBsPeer() {
+    const bsPeer = new BsPeer(this._socketToServer);
+    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 clientId = `client_${this._clients.size}_${Math.random().toString(36).slice(2)}`;
+    socket.__clientId = clientId;
+    const ioPeer = await this._createIoPeer(socket);
+    const bsPeer = await this._createBsPeer(socket);
+    this._registerClient(clientId, socket, ioPeer, bsPeer);
+    this._pendingSockets.push(socket);
+    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 { socket } of this._clients.values()) {
+      socket.removeAllListeners(this._route.flat);
+    }
+  }
+  // ...........................................................................
+  /**
+   * Broadcasts incoming payloads from any client to all other connected clients.
+   */
+  _multicastRefs = () => {
+    for (const { socket: socketA } of this._clients.values()) {
+      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 { socket: socketB } of this._clients.values()) {
+          if (socketA !== socketB) {
+            const forwarded = Object.assign({}, payload, {
+              __origin: socketA.__clientId
+            });
+            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 socket - Client socket to register.
+   * @param io - Io peer associated with the client.
+   * @param bs - Bs peer associated with the client.
+   */
+  _registerClient(clientId, socket, io, bs) {
+    this._clients.set(clientId, {
+      socket,
+      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 socket of this._pendingSockets) {
+      await this._ioServer.addSocket(socket);
+      await this._bsServer.addSocket(socket);
+    }
+    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);
+  }
+}
+class SocketIoBridge {
+  constructor(_socket) {
+    this._socket = _socket;
+    if ("setMaxListeners" in this._socket) {
+      this._socket.setMaxListeners(0);
+    }
+  }
+  get connected() {
+    return this._socket.connected;
+  }
+  /* v8 ignore next -- @preserve */
+  get disconnected() {
+    return this._socket.disconnected;
+  }
+  /**
+   * Connect the socket.
+   * Note: Socket.IO server sockets don't have a connect() method as they are
+   * already connected when created. This is a no-op for server sockets.
+   * For client sockets, this calls the underlying connect() method.
+   */
+  connect() {
+    if ("connect" in this._socket && typeof this._socket.connect === "function") {
+      this._socket.connect();
+    }
+  }
+  disconnect() {
+    this._socket.disconnect();
+  }
+  on(eventName, listener) {
+    this._socket.on(eventName, listener);
+    return this;
+  }
+  emit(eventName, ...args) {
+    this._socket.emit(eventName, ...args);
+    return this;
+  }
+  /* v8 ignore next -- @preserve */
+  off(eventName, listener) {
+    this._socket.off(eventName, listener);
+    return this;
+  }
+  removeAllListeners(eventName) {
+    this._socket.removeAllListeners(eventName);
+    return this;
+  }
+  /**
+   * Get the underlying Socket.IO socket instance.
+   */
+  /* v8 ignore next -- @preserve */
+  get rawSocket() {
+    return this._socket;
+  }
+}
+export {
+  Client,
+  Server,
+  SocketIoBridge
+};