@rljson/server 0.0.8 → 0.0.10

package/README.public.md

@@ -164,6 +164,9 @@ This is implemented with `IoMulti` and `BsMulti` internally, but the public API
 - `connector` – Connector wired to the route and socket (available when route was provided)
 - `route` – the Route passed to the constructor
 - `logger` – the `ServerLogger` instance (defaults to `noopLogger`)
+- `isConnected` – whether the socket is currently connected (tracks `disconnect`/`connect` events)
+- `onDisconnect(callback)` – registers a callback that fires when the socket disconnects (receives the reason string)
+- `onReconnect(callback)` – registers a callback that fires when the socket reconnects after a previous disconnect
 
 ### Server API
 
@@ -216,6 +219,60 @@ The same pattern is used for Bs (blob storage).
 - Peer initialization is guarded by a configurable timeout (`peerInitTimeoutMs`, default 30 s) on both server and client. On the server it prevents `addSocket()` from hanging on unresponsive clients; on the client it prevents `init()` from hanging when the server is unreachable.
 - Logging is opt-in via `{ logger }` options. Use `ConsoleLogger` for development, `BufferedLogger` for testing, `FilteredLogger` for production. Default is `NoopLogger` (zero overhead).
 
+## Reconnect handling
+
+The `Client` class tracks socket connection state and provides hooks for upper layers to react to disconnects and reconnections.
+
+### How it works
+
+Socket.IO auto-reconnects at the transport level by default. When the connection drops and is restored:
+
+1. The client-side Socket.IO socket emits `'disconnect'` then (later) `'connect'`.
+2. The `Client` class listens for these events and updates `isConnected`.
+3. Registered `onDisconnect` / `onReconnect` callbacks fire.
+4. The server auto-detects the dropped socket (`removeSocket`) and re-registers the reconnected socket via a new `'connection'` event.
+5. The server sends a bootstrap ref to the reconnected client, triggering a re-sync via the Connector's bootstrap handler.
+
+### Usage
+
+```ts
+import { Client } from '@rljson/server';
+
+const client = new Client(socket, io, bs, route, {
+  logger: new ConsoleLogger(),
+});
+await client.init();
+
+// Track connection state
+console.log(client.isConnected); // true
+
+// React to disconnects
+client.onDisconnect((reason) => {
+  console.warn(`Disconnected: ${reason}`);
+  // Pause user-facing sync indicators, queue local changes, etc.
+});
+
+// React to reconnections
+client.onReconnect(() => {
+  console.info('Reconnected to server');
+  // Resume sync, trigger re-fetch, update UI, etc.
+});
+```
+
+### What survives a reconnect
+
+| Layer             | Survives? | Details                                                           |
+| ----------------- | --------- | ----------------------------------------------------------------- |
+| Socket.IO         | ✅         | Auto-reconnects, reuses the same client-side socket object        |
+| SocketIoBridge    | ✅         | Wraps the same socket — event listeners are preserved             |
+| IoPeer / BsPeer   | ✅         | Listeners remain on the client socket; server re-creates its side |
+| Connector         | ✅         | Listeners remain; server bootstrap re-syncs state                 |
+| IoMulti / BsMulti | ✅         | Multi layers are unaffected; local Io/Bs always available         |
+
+### Cleanup
+
+All connection handlers are cleaned up automatically on `tearDown()`. After tearDown, no callbacks will fire.
+
 ## Logging
 
 Both `Server` and `Client` support structured logging via an injectable `ServerLogger` interface. Logging is opt-in — by default a zero-overhead `NoopLogger` is used.

package/dist/README.public.md

@@ -164,6 +164,9 @@ This is implemented with `IoMulti` and `BsMulti` internally, but the public API
 - `connector` – Connector wired to the route and socket (available when route was provided)
 - `route` – the Route passed to the constructor
 - `logger` – the `ServerLogger` instance (defaults to `noopLogger`)
+- `isConnected` – whether the socket is currently connected (tracks `disconnect`/`connect` events)
+- `onDisconnect(callback)` – registers a callback that fires when the socket disconnects (receives the reason string)
+- `onReconnect(callback)` – registers a callback that fires when the socket reconnects after a previous disconnect
 
 ### Server API
 
@@ -216,6 +219,60 @@ The same pattern is used for Bs (blob storage).
 - Peer initialization is guarded by a configurable timeout (`peerInitTimeoutMs`, default 30 s) on both server and client. On the server it prevents `addSocket()` from hanging on unresponsive clients; on the client it prevents `init()` from hanging when the server is unreachable.
 - Logging is opt-in via `{ logger }` options. Use `ConsoleLogger` for development, `BufferedLogger` for testing, `FilteredLogger` for production. Default is `NoopLogger` (zero overhead).
 
+## Reconnect handling
+
+The `Client` class tracks socket connection state and provides hooks for upper layers to react to disconnects and reconnections.
+
+### How it works
+
+Socket.IO auto-reconnects at the transport level by default. When the connection drops and is restored:
+
+1. The client-side Socket.IO socket emits `'disconnect'` then (later) `'connect'`.
+2. The `Client` class listens for these events and updates `isConnected`.
+3. Registered `onDisconnect` / `onReconnect` callbacks fire.
+4. The server auto-detects the dropped socket (`removeSocket`) and re-registers the reconnected socket via a new `'connection'` event.
+5. The server sends a bootstrap ref to the reconnected client, triggering a re-sync via the Connector's bootstrap handler.
+
+### Usage
+
+```ts
+import { Client } from '@rljson/server';
+
+const client = new Client(socket, io, bs, route, {
+  logger: new ConsoleLogger(),
+});
+await client.init();
+
+// Track connection state
+console.log(client.isConnected); // true
+
+// React to disconnects
+client.onDisconnect((reason) => {
+  console.warn(`Disconnected: ${reason}`);
+  // Pause user-facing sync indicators, queue local changes, etc.
+});
+
+// React to reconnections
+client.onReconnect(() => {
+  console.info('Reconnected to server');
+  // Resume sync, trigger re-fetch, update UI, etc.
+});
+```
+
+### What survives a reconnect
+
+| Layer             | Survives? | Details                                                           |
+| ----------------- | --------- | ----------------------------------------------------------------- |
+| Socket.IO         | ✅         | Auto-reconnects, reuses the same client-side socket object        |
+| SocketIoBridge    | ✅         | Wraps the same socket — event listeners are preserved             |
+| IoPeer / BsPeer   | ✅         | Listeners remain on the client socket; server re-creates its side |
+| Connector         | ✅         | Listeners remain; server bootstrap re-syncs state                 |
+| IoMulti / BsMulti | ✅         | Multi layers are unaffected; local Io/Bs always available         |
+
+### Cleanup
+
+All connection handlers are cleaned up automatically on `tearDown()`. After tearDown, no callbacks will fire.
+
 ## Logging
 
 Both `Server` and `Client` support structured logging via an injectable `ServerLogger` interface. Logging is opt-in — by default a zero-overhead `NoopLogger` is used.

package/dist/client.d.ts

@@ -45,6 +45,10 @@ export declare class Client extends BaseNode {
     private _syncConfig?;
     private _clientIdentity?;
     private _peerInitTimeoutMs;
+    private _isConnected;
+    private _disconnectCallbacks;
+    private _reconnectCallbacks;
+    private _connectionCleanup?;
     /**
      * Creates a Client instance
      * @param _socketToServer - Socket or namespace bundle to connect to server
@@ -91,11 +95,34 @@ export declare class Client extends BaseNode {
      * Returns the logger instance.
      */
     get logger(): ServerLogger;
+    /**
+     * Whether the client is currently connected to the server.
+     * Tracks socket-level connection state via `disconnect` and `connect` events.
+     */
+    get isConnected(): boolean;
+    /**
+     * Registers a callback that fires when the socket disconnects.
+     * The callback receives the disconnect reason string.
+     * @param callback - Invoked with the disconnect reason
+     */
+    onDisconnect(callback: (reason: string) => void): void;
+    /**
+     * Registers a callback that fires when the socket reconnects
+     * after a previous disconnect.
+     * @param callback - Invoked on reconnection
+     */
+    onReconnect(callback: () => void): void;
     /**
      * Creates Db and Connector from the route and IoMulti.
      * Called during init() when a route was provided.
      */
     private _setupDbAndConnector;
+    /**
+     * Registers socket-level disconnect/connect listeners.
+     * Logs state transitions and invokes registered callbacks.
+     * The `connect` callback only fires on RE-connections (not the initial connect).
+     */
+    private _registerConnectionHandlers;
     /**
      * Builds the Io multi with local and peer layers.
      */

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 {
@@ -1157,6 +1159,11 @@ class Client extends BaseNode {
   _syncConfig;
   _clientIdentity;
   _peerInitTimeoutMs;
+  // Connection state
+  _isConnected = true;
+  _disconnectCallbacks = [];
+  _reconnectCallbacks = [];
+  _connectionCleanup;
   /**
    * Initializes Io and Bs multis and their peer bridges.
    * @returns The initialized Io implementation.
@@ -1169,6 +1176,7 @@ class Client extends BaseNode {
       if (this._route) {
         this._setupDbAndConnector();
       }
+      this._registerConnectionHandlers();
       await this.ready();
       this._logger.info("Client", "Client initialized successfully", {
         hasRoute: !!this._route,
@@ -1194,6 +1202,12 @@ class Client extends BaseNode {
    */
   async tearDown() {
     this._logger.info("Client", "Tearing down client");
+    if (this._connectionCleanup) {
+      this._connectionCleanup();
+      this._connectionCleanup = void 0;
+    }
+    this._disconnectCallbacks = [];
+    this._reconnectCallbacks = [];
     if (this._ioMulti && this._ioMulti.isOpen) {
       this._ioMulti.close();
     }
@@ -1242,6 +1256,29 @@ class Client extends BaseNode {
   get logger() {
     return this._logger;
   }
+  /**
+   * Whether the client is currently connected to the server.
+   * Tracks socket-level connection state via `disconnect` and `connect` events.
+   */
+  get isConnected() {
+    return this._isConnected;
+  }
+  /**
+   * Registers a callback that fires when the socket disconnects.
+   * The callback receives the disconnect reason string.
+   * @param callback - Invoked with the disconnect reason
+   */
+  onDisconnect(callback) {
+    this._disconnectCallbacks.push(callback);
+  }
+  /**
+   * Registers a callback that fires when the socket reconnects
+   * after a previous disconnect.
+   * @param callback - Invoked on reconnection
+   */
+  onReconnect(callback) {
+    this._reconnectCallbacks.push(callback);
+  }
   /**
    * Creates Db and Connector from the route and IoMulti.
    * Called during init() when a route was provided.
@@ -1261,6 +1298,44 @@ class Client extends BaseNode {
     );
     this._logger.info("Client", "Db and Connector created");
   }
+  /**
+   * Registers socket-level disconnect/connect listeners.
+   * Logs state transitions and invokes registered callbacks.
+   * The `connect` callback only fires on RE-connections (not the initial connect).
+   */
+  _registerConnectionHandlers() {
+    const sockets = normalizeSocketBundle(this._socketToServer);
+    const socket = sockets.ioUp;
+    const disconnectHandler = (...args) => {
+      const reason = typeof args[0] === "string" ? args[0] : "unknown";
+      this._isConnected = false;
+      this._logger.warn("Client", "Disconnected from server", { reason });
+      for (const cb of this._disconnectCallbacks) {
+        try {
+          cb(reason);
+        } catch {
+        }
+      }
+    };
+    const reconnectHandler = () => {
+      if (!this._isConnected) {
+        this._isConnected = true;
+        this._logger.info("Client", "Reconnected to server");
+        for (const cb of this._reconnectCallbacks) {
+          try {
+            cb();
+          } catch {
+          }
+        }
+      }
+    };
+    socket.on("disconnect", disconnectHandler);
+    socket.on("connect", reconnectHandler);
+    this._connectionCleanup = () => {
+      socket.off("disconnect", disconnectHandler);
+      socket.off("connect", reconnectHandler);
+    };
+  }
   /**
    * Builds the Io multi with local and peer layers.
    */
@@ -1399,6 +1474,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 +2342,7 @@ export {
   BufferedLogger,
   Client,
   ConsoleLogger,
+  FileLogger,
   FilteredLogger,
   NoopLogger,
   Server,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rljson/server",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "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",