@rljson/server 0.0.8 → 0.0.9

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.8",
+  "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",