@rljson/server 0.0.7 → 0.0.9

package/README.architecture.md

@@ -134,6 +134,8 @@ The `Server` class acts as a central coordination point that:
 - Broadcasts notifications between clients
 - Provides read access to its own local storage
 
+**Relay mode (`disableLocalCache: true`):** When the `disableLocalCache` option is set, the server omits the local IoMem/BsMem from its IoMulti/BsMulti stacks. In this mode the server reads all data exclusively from connected client peers, acting as a pure relay without caching any data locally. This is useful for memory-constrained deployments where the server should not retain copies of client data.
+
 **Data Flow Architecture:**
 
 ```text

package/README.public.md

@@ -176,6 +176,7 @@ This is implemented with `IoMulti` and `BsMulti` internally, but the public API
 - `bs` – Bs interface used by server
 - `clients` – `Map` of connected clients (keyed by internal clientId)
 - `isTornDown` – whether the server has been shut down
+- `isLocalCacheDisabled` – whether local caching is disabled (pure relay mode)
 - `logger` – the `ServerLogger` instance (defaults to `noopLogger`)
 
 ## Example
@@ -306,17 +307,19 @@ const server = new Server(route, io, bs, {
   logger: new ConsoleLogger(),     // Structured logging (default: NoopLogger)
   refEvictionIntervalMs: 60_000,   // Ref dedup sweep interval (default: 60 s, 0 = disable)
   peerInitTimeoutMs: 30_000,       // Peer handshake timeout (default: 30 s, 0 = disable)
+  disableLocalCache: true,         // Pure relay mode — no local Io/Bs cache (default: false)
 });
 ```
 
-| Option                  | Default    | Description                                                                                                                             |
-| ----------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| `logger`                | NoopLogger | Structured logger for lifecycle, traffic, and error events.                                                                             |
-| `refEvictionIntervalMs` | 60 000     | Two-generation sweep interval for multicast ref dedup. Refs older than two intervals are forgotten, preventing unbounded memory growth. |
-| `peerInitTimeoutMs`     | 30 000     | Maximum time `addSocket()` waits for a peer to initialize. Prevents hanging on unresponsive clients.                                    |
-| `syncConfig`            | undefined  | Sync protocol configuration (see below). Enables ACK aggregation, gap-fill, and enriched payloads.                                      |
-| `refLogSize`            | 1 000      | Maximum number of recent payloads retained in the ref log for gap-fill responses.                                                       |
-| `ackTimeoutMs`          | 10 000     | Timeout for collecting individual client ACKs before emitting the aggregated ACK. Falls back to `syncConfig.ackTimeoutMs`.              |
+| Option                  | Default    | Description                                                                                                                                                                               |
+| ----------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `logger`                | NoopLogger | Structured logger for lifecycle, traffic, and error events.                                                                                                                               |
+| `refEvictionIntervalMs` | 60 000     | Two-generation sweep interval for multicast ref dedup. Refs older than two intervals are forgotten, preventing unbounded memory growth.                                                   |
+| `peerInitTimeoutMs`     | 30 000     | Maximum time `addSocket()` waits for a peer to initialize. Prevents hanging on unresponsive clients.                                                                                      |
+| `syncConfig`            | undefined  | Sync protocol configuration (see below). Enables ACK aggregation, gap-fill, and enriched payloads.                                                                                        |
+| `refLogSize`            | 1 000      | Maximum number of recent payloads retained in the ref log for gap-fill responses.                                                                                                         |
+| `ackTimeoutMs`          | 10 000     | Timeout for collecting individual client ACKs before emitting the aggregated ACK. Falls back to `syncConfig.ackTimeoutMs`.                                                                |
+| `disableLocalCache`     | false      | When true, the server skips creating local IoMem/BsMem caches. The server acts as a pure relay, reading data only from connected client peers. Useful for memory-constrained deployments. |
 
 ## Client options
 

package/dist/README.architecture.md

@@ -134,6 +134,8 @@ The `Server` class acts as a central coordination point that:
 - Broadcasts notifications between clients
 - Provides read access to its own local storage
 
+**Relay mode (`disableLocalCache: true`):** When the `disableLocalCache` option is set, the server omits the local IoMem/BsMem from its IoMulti/BsMulti stacks. In this mode the server reads all data exclusively from connected client peers, acting as a pure relay without caching any data locally. This is useful for memory-constrained deployments where the server should not retain copies of client data.
+
 **Data Flow Architecture:**
 
 ```text

package/dist/README.public.md

@@ -176,6 +176,7 @@ This is implemented with `IoMulti` and `BsMulti` internally, but the public API
 - `bs` – Bs interface used by server
 - `clients` – `Map` of connected clients (keyed by internal clientId)
 - `isTornDown` – whether the server has been shut down
+- `isLocalCacheDisabled` – whether local caching is disabled (pure relay mode)
 - `logger` – the `ServerLogger` instance (defaults to `noopLogger`)
 
 ## Example
@@ -306,17 +307,19 @@ const server = new Server(route, io, bs, {
   logger: new ConsoleLogger(),     // Structured logging (default: NoopLogger)
   refEvictionIntervalMs: 60_000,   // Ref dedup sweep interval (default: 60 s, 0 = disable)
   peerInitTimeoutMs: 30_000,       // Peer handshake timeout (default: 30 s, 0 = disable)
+  disableLocalCache: true,         // Pure relay mode — no local Io/Bs cache (default: false)
 });
 ```
 
-| Option                  | Default    | Description                                                                                                                             |
-| ----------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| `logger`                | NoopLogger | Structured logger for lifecycle, traffic, and error events.                                                                             |
-| `refEvictionIntervalMs` | 60 000     | Two-generation sweep interval for multicast ref dedup. Refs older than two intervals are forgotten, preventing unbounded memory growth. |
-| `peerInitTimeoutMs`     | 30 000     | Maximum time `addSocket()` waits for a peer to initialize. Prevents hanging on unresponsive clients.                                    |
-| `syncConfig`            | undefined  | Sync protocol configuration (see below). Enables ACK aggregation, gap-fill, and enriched payloads.                                      |
-| `refLogSize`            | 1 000      | Maximum number of recent payloads retained in the ref log for gap-fill responses.                                                       |
-| `ackTimeoutMs`          | 10 000     | Timeout for collecting individual client ACKs before emitting the aggregated ACK. Falls back to `syncConfig.ackTimeoutMs`.              |
+| Option                  | Default    | Description                                                                                                                                                                               |
+| ----------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `logger`                | NoopLogger | Structured logger for lifecycle, traffic, and error events.                                                                                                                               |
+| `refEvictionIntervalMs` | 60 000     | Two-generation sweep interval for multicast ref dedup. Refs older than two intervals are forgotten, preventing unbounded memory growth.                                                   |
+| `peerInitTimeoutMs`     | 30 000     | Maximum time `addSocket()` waits for a peer to initialize. Prevents hanging on unresponsive clients.                                                                                      |
+| `syncConfig`            | undefined  | Sync protocol configuration (see below). Enables ACK aggregation, gap-fill, and enriched payloads.                                                                                        |
+| `refLogSize`            | 1 000      | Maximum number of recent payloads retained in the ref log for gap-fill responses.                                                                                                         |
+| `ackTimeoutMs`          | 10 000     | Timeout for collecting individual client ACKs before emitting the aggregated ACK. Falls back to `syncConfig.ackTimeoutMs`.                                                                |
+| `disableLocalCache`     | false      | When true, the server skips creating local IoMem/BsMem caches. The server acts as a pure relay, reading data only from connected client peers. Useful for memory-constrained deployments. |
 
 ## Client options
 

package/dist/file-logger.d.ts

@@ -0,0 +1,63 @@
+import { ServerLogger } from './logger.ts';
+/**
+ * Options for creating a FileLogger.
+ */
+export interface FileLoggerOptions {
+    /**
+     * Absolute path to the log file.
+     * Parent directories are created automatically if they don't exist.
+     */
+    filePath: string;
+    /**
+     * When `true`, log entries are also written to console
+     * (info/traffic → console.log, warn → console.warn, error → console.error).
+     * Defaults to `false`.
+     */
+    echo?: boolean;
+}
+/**
+ * Appends log entries to a file. Optionally echoes to console.
+ *
+ * Each line is a self-contained JSON object for easy parsing:
+ * ```
+ * {"ts":"2026-02-25T12:00:00.000Z","level":"info","source":"Server","message":"initialized","data":{"port":3000}}
+ * ```
+ *
+ * Parent directories are created on construction if they don't exist.
+ * Uses synchronous writes (`appendFileSync`) to guarantee ordering
+ * and avoid lost entries on crash.
+ */
+export declare class FileLogger implements ServerLogger {
+    private readonly _filePath;
+    private readonly _echo;
+    constructor(options: FileLoggerOptions);
+    /** The file path this logger writes to. */
+    get filePath(): string;
+    /** Whether console echo is enabled. */
+    get echo(): boolean;
+    info(source: string, message: string, data?: Record<string, unknown>): void;
+    warn(source: string, message: string, data?: Record<string, unknown>): void;
+    error(source: string, message: string, error?: unknown, data?: Record<string, unknown>): void;
+    traffic(direction: 'in' | 'out', source: string, event: string, data?: Record<string, unknown>): void;
+    /**
+     * Build a standard log entry object.
+     * @param level - Log level string
+     * @param source - Component identifier
+     * @param message - Human-readable message
+     * @param data - Optional structured context
+     */
+    private _entry;
+    /**
+     * Append a JSON line to the log file.
+     * @param entry - The log entry object to serialize
+     */
+    private _write;
+    /**
+     * Format a human-readable console line.
+     * @param level - Display level label (e.g. 'INFO')
+     * @param source - Component identifier
+     * @param message - Human-readable message
+     * @param data - Optional structured context
+     */
+    private _format;
+}

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { Client } from './client.ts';
 export type { ClientOptions } from './client.ts';
+export { FileLogger } from './file-logger.ts';
+export type { FileLoggerOptions } from './file-logger.ts';
 export { BufferedLogger, ConsoleLogger, FilteredLogger, NoopLogger, noopLogger, } from './logger.ts';
 export type { LogEntry, ServerLogger } from './logger.ts';
 export { Server } from './server.ts';

package/dist/server.js

@@ -2,6 +2,8 @@ import { hshBuffer } from "@rljson/hash";
 import { Readable } from "node:stream";
 import { Db, Connector } from "@rljson/db";
 import { IoPeerBridge, IoMulti, IoPeer, IoServer, IoMem, SocketMock } from "@rljson/io";
+import { existsSync, mkdirSync, appendFileSync } from "node:fs";
+import { dirname } from "node:path";
 import { syncEvents, Route } from "@rljson/rljson";
 import { syncEvents as syncEvents2 } from "@rljson/rljson";
 class BsMem {
@@ -1399,6 +1401,116 @@ class Client extends BaseNode {
     );
   }
 }
+class FileLogger {
+  _filePath;
+  _echo;
+  constructor(options) {
+    this._filePath = options.filePath;
+    this._echo = options.echo ?? false;
+    const dir = dirname(this._filePath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+  }
+  /** The file path this logger writes to. */
+  get filePath() {
+    return this._filePath;
+  }
+  /** Whether console echo is enabled. */
+  get echo() {
+    return this._echo;
+  }
+  info(source, message, data) {
+    const entry = this._entry("info", source, message, data);
+    this._write(entry);
+    if (this._echo) {
+      console.log(this._format("INFO", source, message, data));
+    }
+  }
+  warn(source, message, data) {
+    const entry = this._entry("warn", source, message, data);
+    this._write(entry);
+    if (this._echo) {
+      console.warn(this._format("WARN", source, message, data));
+    }
+  }
+  error(source, message, error, data) {
+    const entry = {
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      level: "error",
+      source,
+      message
+    };
+    if (error !== void 0) {
+      entry["error"] = error instanceof Error ? { name: error.name, message: error.message, stack: error.stack } : String(error);
+    }
+    if (data !== void 0) {
+      entry["data"] = data;
+    }
+    this._write(entry);
+    if (this._echo) {
+      const errStr = error ? ` ${error}` : "";
+      const dataStr = data ? " " + JSON.stringify(data) : "";
+      console.error(`[ERROR] [${source}] ${message}${errStr}${dataStr}`);
+    }
+  }
+  traffic(direction, source, event, data) {
+    const entry = {
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      level: "traffic",
+      direction,
+      source,
+      event
+    };
+    if (data !== void 0) {
+      entry["data"] = data;
+    }
+    this._write(entry);
+    if (this._echo) {
+      const arrow = direction === "in" ? "⬅" : "➡";
+      const dataStr = data ? " " + JSON.stringify(data) : "";
+      console.log(`[TRAFFIC] ${arrow} [${source}] ${event}${dataStr}`);
+    }
+  }
+  // ...........................................................................
+  /**
+   * Build a standard log entry object.
+   * @param level - Log level string
+   * @param source - Component identifier
+   * @param message - Human-readable message
+   * @param data - Optional structured context
+   */
+  _entry(level, source, message, data) {
+    const entry = {
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      level,
+      source,
+      message
+    };
+    if (data !== void 0) {
+      entry["data"] = data;
+    }
+    return entry;
+  }
+  /**
+   * Append a JSON line to the log file.
+   * @param entry - The log entry object to serialize
+   */
+  _write(entry) {
+    appendFileSync(this._filePath, JSON.stringify(entry) + "\n", "utf-8");
+  }
+  /**
+   * Format a human-readable console line.
+   * @param level - Display level label (e.g. 'INFO')
+   * @param source - Component identifier
+   * @param message - Human-readable message
+   * @param data - Optional structured context
+   */
+  _format(level, source, message, data) {
+    const dataStr = data ? " " + JSON.stringify(data) : "";
+    return `[${level}] [${source}] ${message}${dataStr}`;
+  }
+}
 class Server extends BaseNode {
   constructor(_route, _localIo, _localBs, options) {
     super(_localIo);
@@ -2157,6 +2269,7 @@ export {
   BufferedLogger,
   Client,
   ConsoleLogger,
+  FileLogger,
   FilteredLogger,
   NoopLogger,
   Server,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rljson/server",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "description": "Rljson server description",
   "homepage": "https://github.com/rljson/server",
   "bugs": "https://github.com/rljson/server/issues",
@@ -20,21 +20,21 @@
   ],
   "type": "module",
   "devDependencies": {
-    "@types/node": "^25.2.3",
-    "@typescript-eslint/eslint-plugin": "^8.56.0",
-    "@typescript-eslint/parser": "^8.56.0",
+    "@types/node": "^25.3.0",
+    "@typescript-eslint/eslint-plugin": "^8.56.1",
+    "@typescript-eslint/parser": "^8.56.1",
     "@vitest/coverage-v8": "^4.0.18",
     "cross-env": "^10.1.0",
     "eslint": "~9.39.2",
-    "eslint-plugin-jsdoc": "^62.5.5",
-    "eslint-plugin-tsdoc": "^0.5.0",
+    "eslint-plugin-jsdoc": "^62.7.1",
+    "eslint-plugin-tsdoc": "^0.5.1",
     "globals": "^17.3.0",
     "jsdoc": "^4.0.5",
     "read-pkg": "^10.1.0",
     "socket.io": "^4.8.3",
     "socket.io-client": "^4.8.3",
     "typescript": "~5.9.3",
-    "typescript-eslint": "^8.56.0",
+    "typescript-eslint": "^8.56.1",
     "vite": "^7.3.1",
     "vite-node": "^5.3.0",
     "vite-plugin-dts": "^4.5.4",
@@ -44,11 +44,11 @@
   },
   "dependencies": {
     "@rljson/bs": "^0.0.21",
-    "@rljson/db": "^0.0.14",
+    "@rljson/db": "^0.0.15",
     "@rljson/hash": "^0.0.18",
     "@rljson/io": "^0.0.66",
     "@rljson/json": "^0.0.23",
-    "@rljson/rljson": "^0.0.76"
+    "@rljson/rljson": "^0.0.78"
   },
   "scripts": {
     "build": "pnpm exec vite build && tsc && node scripts/copy-readme-to-dist.js",