logora-websocket 1.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 boseba
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,290 @@
+# logora-websocket
+
+[![NPM version](https://img.shields.io/npm/v/logora-websocket?style=flat-square)](https://www.npmjs.com/package/logora-websocket)
+[![Coverage Status](https://coveralls.io/repos/github/boseba/logora-websocket/badge.svg?branch=main)](https://coveralls.io/github/boseba/logora-websocket?branch=main)
+
+logora-websocket is the official WebSocket output module for the [Logora](https://www.npmjs.com/package/logora) logging framework.
+
+It forwards Logora writer instructions as structured JSON messages through a broadcaster abstraction, making it easy to stream server logs to remote clients, dashboards, or custom live viewers.
+
+* * *
+
+## Features
+
+- Structured WebSocket transport for Logora writer instructions
+- Supports `log`, `print`, `title`, `empty`, and `clear`
+- Safe serialization for complex values:
+  - `Error`
+  - `Date`
+  - `BigInt`
+  - `Symbol`
+  - functions
+  - circular references
+- Broadcast-oriented design for live log viewers
+- No built-in server lifecycle logic
+- Compatible with custom broadcasters and `ws`
+- Non-blocking design aligned with the Logora plugin model
+
+* * *
+
+## Installation
+
+    npm install logora logora-websocket
+
+If you want to use the provided `ws` broadcaster helper:
+
+    npm install ws
+
+* * *
+
+## Basic Usage
+
+    import { createServer } from "node:http";
+    import { createLogger, LogLevel } from "logora";
+    import {
+      createWebSocketOutput,
+      createWsBroadcaster,
+    } from "logora-websocket";
+    import { WebSocketServer } from "ws";
+
+    const httpServer = createServer();
+    const webSocketServer = new WebSocketServer({ server: httpServer });
+
+    const logger = createLogger({ level: LogLevel.Info });
+
+    logger.addLogOutput(
+      createWebSocketOutput({
+        broadcaster: createWsBroadcaster(webSocketServer),
+      }),
+    );
+
+    logger.info("Server started on port {0}", 3000);
+
+    httpServer.listen(3000);
+
+* * *
+
+## Scoped Logging
+
+Scoped loggers are supported exactly like in the rest of the Logora ecosystem:
+
+    const apiLogger = logger.getScoped("API");
+
+    apiLogger.info("Request received: {0}", "/users");
+    apiLogger.warning("Rate limit reached for client {0}", clientId);
+
+When a scope is present, it is included in the serialized payload.
+
+* * *
+
+## How It Works
+
+logora-websocket does not create or manage a WebSocket server.
+
+Your application remains responsible for:
+
+- creating the server
+- authenticating clients
+- deciding which clients receive logs
+- closing connections
+- integrating with your HTTP server or framework
+
+The module only transforms Logora writer calls into structured JSON messages and forwards them through a `WebSocketBroadcaster`.
+
+* * *
+
+## Broadcaster Abstraction
+
+The transport relies on a very small broadcaster contract:
+
+    export interface WebSocketBroadcaster {
+      broadcast(message: string): void;
+    }
+
+This keeps the module focused and lets you adapt it to your own WebSocket infrastructure.
+
+### Example with a custom broadcaster
+
+    import { createWebSocketOutput } from "logora-websocket";
+
+    const broadcaster = {
+      broadcast(message: string): void {
+        myCustomSocketHub.sendToAll(message);
+      },
+    };
+
+    logger.addLogOutput(
+      createWebSocketOutput({
+        broadcaster,
+      }),
+    );
+
+* * *
+
+## Using the `ws` Broadcaster Helper
+
+If your server uses [`ws`](https://www.npmjs.com/package/ws), the module provides a helper that broadcasts to all open clients:
+
+    import { createServer } from "node:http";
+    import { WebSocketServer } from "ws";
+    import {
+      createWebSocketOutput,
+      createWsBroadcaster,
+    } from "logora-websocket";
+
+    const httpServer = createServer();
+    const webSocketServer = new WebSocketServer({ server: httpServer });
+
+    const output = createWebSocketOutput({
+      broadcaster: createWsBroadcaster(webSocketServer),
+    });
+
+This helper:
+
+- iterates over connected clients
+- sends only to open sockets
+- ignores failures from individual clients
+
+* * *
+
+## Message Format
+
+Each writer instruction is sent as a JSON message.
+
+### Log message
+
+    {
+      "kind": "log",
+      "entry": {
+        "timestamp": "2026-04-04T12:00:00.000Z",
+        "type": "warning",
+        "message": "Something happened",
+        "args": [123],
+        "scope": "API"
+      }
+    }
+
+### Print message
+
+    {
+      "kind": "print",
+      "message": "Server listening",
+      "args": [3000]
+    }
+
+### Title message
+
+    {
+      "kind": "title",
+      "title": "HTTP"
+    }
+
+### Empty message
+
+    {
+      "kind": "empty",
+      "count": 2
+    }
+
+### Clear message
+
+    {
+      "kind": "clear"
+    }
+
+* * *
+
+## Serialized Log Entry
+
+A `log` instruction contains a serialized Logora entry with the following shape:
+
+| Field | Type | Description |
+|---|---|---|
+| `timestamp` | `string` | ISO timestamp of the log entry |
+| `type` | `string` | Log type name (`debug`, `info`, `success`, `warning`, `error`, `highlight`, `raw`) |
+| `message` | `string` | Main log message |
+| `args` | `SerializedValue[]` | Serialized argument list |
+| `scope` | `string \| undefined` | Optional logger scope |
+
+* * *
+
+## Value Serialization
+
+Arguments are serialized before being sent through the broadcaster.
+
+### Supported conversions
+
+- `string`, `number`, `boolean`, `null`
+- `Date` → structured date payload
+- `BigInt` → structured bigint payload
+- `Error` → structured error payload
+- `Symbol` → structured symbol payload
+- `function` → structured function payload
+- arrays and plain objects
+
+### Safety behavior
+
+The default serializer also handles:
+
+- circular references
+- deep objects
+- very large arrays
+- very large objects
+
+Unsupported or truncated values are replaced with safe fallback representations.
+
+* * *
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `broadcaster` | `WebSocketBroadcaster` | — | Broadcaster used to forward serialized messages |
+| `serializer` | `WebSocketInstructionSerializer` | `DefaultWebSocketInstructionSerializer` | Serializer used to convert instructions and values |
+| `level` | `LogLevel \| undefined` | `undefined` | Optional minimum level for this output |
+
+* * *
+
+## Advanced Usage
+
+### Custom serializer
+
+    import {
+      createWebSocketOutput,
+      DefaultWebSocketInstructionSerializer,
+    } from "logora-websocket";
+
+    const output = createWebSocketOutput({
+      broadcaster,
+      serializer: new DefaultWebSocketInstructionSerializer({
+        maxDepth: 8,
+        maxArrayLength: 200,
+        maxObjectKeys: 200,
+      }),
+    });
+
+### Per-output level filtering
+
+    import { LogLevel } from "logora";
+
+    const output = createWebSocketOutput({
+      broadcaster,
+      level: LogLevel.Warning,
+    });
+
+In this case, the WebSocket output will only receive warning and error logs according to the Logora output filtering rules.
+
+* * *
+
+## Notes
+
+- This module is designed for standard WebSocket-based integrations.
+- It does not implement Socket.IO-specific protocol behavior.
+- It does not buffer, replay, or persist messages.
+- It is intended as a live transport module, not a storage backend.
+
+* * *
+
+## License
+
+MIT © Sébastien Bosmans

package/dist/index.d.mts

@@ -0,0 +1,110 @@
+import { ILogoraOutputOptions, LogLevel, ILogoraOutput } from 'logora';
+import { ILogoraWriter } from 'logora/module';
+
+interface SerializedError {
+    __type: "Error";
+    name: string;
+    message: string;
+    stack?: string;
+    cause?: SerializedValue;
+}
+
+interface SerializedDateValue {
+    __type: "Date";
+    value: string;
+}
+interface SerializedBigIntValue {
+    __type: "BigInt";
+    value: string;
+}
+interface SerializedFunctionValue {
+    __type: "Function";
+    name: string;
+}
+interface SerializedSymbolValue {
+    __type: "Symbol";
+    value: string;
+}
+
+type SerializedPrimitive = string | number | boolean | null;
+interface SerializedObject {
+    [key: string]: SerializedValue;
+}
+type SerializedValue = SerializedPrimitive | SerializedValue[] | SerializedObject | SerializedError | SerializedDateValue | SerializedBigIntValue | SerializedFunctionValue | SerializedSymbolValue;
+
+interface SerializedLogEntry {
+    timestamp: string;
+    type: string;
+    message: string;
+    args: SerializedValue[];
+    scope?: string;
+}
+
+interface WebSocketLogInstruction {
+    kind: "log";
+    entry: SerializedLogEntry;
+}
+interface WebSocketPrintInstruction {
+    kind: "print";
+    message: string;
+    args: SerializedValue[];
+}
+interface WebSocketTitleInstruction {
+    kind: "title";
+    title: string;
+}
+interface WebSocketEmptyInstruction {
+    kind: "empty";
+    count: number;
+}
+interface WebSocketClearInstruction {
+    kind: "clear";
+}
+type WebSocketInstruction = WebSocketLogInstruction | WebSocketPrintInstruction | WebSocketTitleInstruction | WebSocketEmptyInstruction | WebSocketClearInstruction;
+
+interface WebSocketInstructionSerializer {
+    serialize(instruction: WebSocketInstruction): string;
+    serializeValue(value: unknown): SerializedValue;
+}
+
+interface WebSocketBroadcaster {
+    broadcast(message: string): void;
+}
+
+declare class WebSocketOutputOptions implements ILogoraOutputOptions {
+    level?: LogLevel;
+    broadcaster: WebSocketBroadcaster;
+    serializer: WebSocketInstructionSerializer;
+    constructor(overrides?: Partial<WebSocketOutputOptions>);
+}
+
+declare class WebSocketOutput implements ILogoraOutput {
+    name: string;
+    options: WebSocketOutputOptions;
+    writer: ILogoraWriter;
+    constructor(config?: Partial<WebSocketOutputOptions>);
+}
+
+type WsLikeClient = {
+    readyState: number;
+    send(data: string): void;
+};
+type WsLikeServer = {
+    clients: Iterable<WsLikeClient>;
+};
+declare function createWsBroadcaster(server: WsLikeServer): WebSocketBroadcaster;
+
+/**
+ * Creates a new WebSocket output transport for Logora.
+ *
+ * This function initializes a WebSocketOutput instance, which can be
+ * attached to a Logora logger to forward writer instructions as
+ * structured messages through a broadcaster abstraction.
+ *
+ * @param config Optional partial configuration to customize broadcaster
+ * and serialization behavior.
+ * @returns A fully initialized WebSocketOutput instance ready to use with Logora.
+ */
+declare function createWebSocketOutput(config?: Partial<WebSocketOutputOptions>): WebSocketOutput;
+
+export { type SerializedBigIntValue, type SerializedDateValue, type SerializedError, type SerializedFunctionValue, type SerializedLogEntry, type SerializedObject, type SerializedPrimitive, type SerializedSymbolValue, type SerializedValue, type WebSocketBroadcaster, type WebSocketClearInstruction, type WebSocketEmptyInstruction, type WebSocketInstruction, type WebSocketLogInstruction, WebSocketOutputOptions, type WebSocketPrintInstruction, type WebSocketTitleInstruction, createWebSocketOutput, createWsBroadcaster };

package/dist/index.d.ts

@@ -0,0 +1,110 @@
+import { ILogoraOutputOptions, LogLevel, ILogoraOutput } from 'logora';
+import { ILogoraWriter } from 'logora/module';
+
+interface SerializedError {
+    __type: "Error";
+    name: string;
+    message: string;
+    stack?: string;
+    cause?: SerializedValue;
+}
+
+interface SerializedDateValue {
+    __type: "Date";
+    value: string;
+}
+interface SerializedBigIntValue {
+    __type: "BigInt";
+    value: string;
+}
+interface SerializedFunctionValue {
+    __type: "Function";
+    name: string;
+}
+interface SerializedSymbolValue {
+    __type: "Symbol";
+    value: string;
+}
+
+type SerializedPrimitive = string | number | boolean | null;
+interface SerializedObject {
+    [key: string]: SerializedValue;
+}
+type SerializedValue = SerializedPrimitive | SerializedValue[] | SerializedObject | SerializedError | SerializedDateValue | SerializedBigIntValue | SerializedFunctionValue | SerializedSymbolValue;
+
+interface SerializedLogEntry {
+    timestamp: string;
+    type: string;
+    message: string;
+    args: SerializedValue[];
+    scope?: string;
+}
+
+interface WebSocketLogInstruction {
+    kind: "log";
+    entry: SerializedLogEntry;
+}
+interface WebSocketPrintInstruction {
+    kind: "print";
+    message: string;
+    args: SerializedValue[];
+}
+interface WebSocketTitleInstruction {
+    kind: "title";
+    title: string;
+}
+interface WebSocketEmptyInstruction {
+    kind: "empty";
+    count: number;
+}
+interface WebSocketClearInstruction {
+    kind: "clear";
+}
+type WebSocketInstruction = WebSocketLogInstruction | WebSocketPrintInstruction | WebSocketTitleInstruction | WebSocketEmptyInstruction | WebSocketClearInstruction;
+
+interface WebSocketInstructionSerializer {
+    serialize(instruction: WebSocketInstruction): string;
+    serializeValue(value: unknown): SerializedValue;
+}
+
+interface WebSocketBroadcaster {
+    broadcast(message: string): void;
+}
+
+declare class WebSocketOutputOptions implements ILogoraOutputOptions {
+    level?: LogLevel;
+    broadcaster: WebSocketBroadcaster;
+    serializer: WebSocketInstructionSerializer;
+    constructor(overrides?: Partial<WebSocketOutputOptions>);
+}
+
+declare class WebSocketOutput implements ILogoraOutput {
+    name: string;
+    options: WebSocketOutputOptions;
+    writer: ILogoraWriter;
+    constructor(config?: Partial<WebSocketOutputOptions>);
+}
+
+type WsLikeClient = {
+    readyState: number;
+    send(data: string): void;
+};
+type WsLikeServer = {
+    clients: Iterable<WsLikeClient>;
+};
+declare function createWsBroadcaster(server: WsLikeServer): WebSocketBroadcaster;
+
+/**
+ * Creates a new WebSocket output transport for Logora.
+ *
+ * This function initializes a WebSocketOutput instance, which can be
+ * attached to a Logora logger to forward writer instructions as
+ * structured messages through a broadcaster abstraction.
+ *
+ * @param config Optional partial configuration to customize broadcaster
+ * and serialization behavior.
+ * @returns A fully initialized WebSocketOutput instance ready to use with Logora.
+ */
+declare function createWebSocketOutput(config?: Partial<WebSocketOutputOptions>): WebSocketOutput;
+
+export { type SerializedBigIntValue, type SerializedDateValue, type SerializedError, type SerializedFunctionValue, type SerializedLogEntry, type SerializedObject, type SerializedPrimitive, type SerializedSymbolValue, type SerializedValue, type WebSocketBroadcaster, type WebSocketClearInstruction, type WebSocketEmptyInstruction, type WebSocketInstruction, type WebSocketLogInstruction, WebSocketOutputOptions, type WebSocketPrintInstruction, type WebSocketTitleInstruction, createWebSocketOutput, createWsBroadcaster };

package/dist/index.js

@@ -0,0 +1,286 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  WebSocketOutputOptions: () => WebSocketOutputOptions,
+  createWebSocketOutput: () => createWebSocketOutput,
+  createWsBroadcaster: () => createWsBroadcaster
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/core/instruction-serializer.ts
+var DefaultWebSocketInstructionSerializer = class {
+  constructor(config) {
+    var _a, _b, _c;
+    this._maxDepth = (_a = config == null ? void 0 : config.maxDepth) != null ? _a : 6;
+    this._maxArrayLength = (_b = config == null ? void 0 : config.maxArrayLength) != null ? _b : 100;
+    this._maxObjectKeys = (_c = config == null ? void 0 : config.maxObjectKeys) != null ? _c : 100;
+  }
+  serialize(instruction) {
+    return JSON.stringify(instruction);
+  }
+  serializeValue(value) {
+    return this._serializeInternal(value, {
+      visitedObjects: /* @__PURE__ */ new WeakSet(),
+      depth: 0
+    });
+  }
+  _serializeInternal(value, context) {
+    if (value === null || value === void 0) {
+      return null;
+    }
+    if (typeof value === "string") {
+      return value;
+    }
+    if (typeof value === "number") {
+      return Number.isFinite(value) ? value : String(value);
+    }
+    if (typeof value === "boolean") {
+      return value;
+    }
+    if (typeof value === "symbol") {
+      return {
+        __type: "Symbol",
+        value: value.toString()
+      };
+    }
+    if (typeof value === "function") {
+      return {
+        __type: "Function",
+        name: value.name || "anonymous"
+      };
+    }
+    if (value instanceof Date) {
+      return {
+        __type: "Date",
+        value: value.toISOString()
+      };
+    }
+    if (value instanceof Error) {
+      return this._serializeError(value, context);
+    }
+    if (context.depth >= this._maxDepth) {
+      return "[MaxDepthExceeded]";
+    }
+    if (Array.isArray(value)) {
+      return this._serializeArray(value, context);
+    }
+    if (typeof value === "object") {
+      return this._serializeObject(value, context);
+    }
+    return "[UnsupportedValue]";
+  }
+  _serializeError(value, context) {
+    const serializedError = {
+      __type: "Error",
+      name: value.name,
+      message: value.message
+    };
+    if (value.stack) {
+      serializedError.stack = value.stack;
+    }
+    const errorWithCause = value;
+    if (errorWithCause.cause !== void 0) {
+      serializedError.cause = this._serializeInternal(errorWithCause.cause, {
+        ...context,
+        depth: context.depth + 1
+      });
+    }
+    return serializedError;
+  }
+  _serializeArray(value, context) {
+    return value.slice(0, this._maxArrayLength).map(
+      (item) => this._serializeInternal(item, {
+        ...context,
+        depth: context.depth + 1
+      })
+    );
+  }
+  _serializeObject(value, context) {
+    if (context.visitedObjects.has(value)) {
+      return "[Circular]";
+    }
+    context.visitedObjects.add(value);
+    const serializedObject = {};
+    const entries = Object.entries(value).slice(
+      0,
+      this._maxObjectKeys
+    );
+    for (const [key, entryValue] of entries) {
+      serializedObject[key] = this._serializeInternal(entryValue, {
+        ...context,
+        depth: context.depth + 1
+      });
+    }
+    return serializedObject;
+  }
+};
+
+// src/config/websocket-output-options.ts
+var WebSocketOutputOptions = class {
+  constructor(overrides) {
+    this.serializer = new DefaultWebSocketInstructionSerializer();
+    Object.assign(this, overrides);
+    if (!this.broadcaster) {
+      throw new Error(
+        "WebSocketOutputOptions requires a broadcaster instance."
+      );
+    }
+  }
+};
+
+// src/core/instruction-factory.ts
+var import_logora = require("logora");
+var WebSocketInstructionFactory = class {
+  constructor(_serializer) {
+    this._serializer = _serializer;
+  }
+  createLog(entry) {
+    return {
+      kind: "log",
+      entry: this._serializeLogEntry(entry)
+    };
+  }
+  createPrint(message, args) {
+    return {
+      kind: "print",
+      message,
+      args: args.map(
+        (argument) => this._serializer.serializeValue(argument)
+      )
+    };
+  }
+  createTitle(title) {
+    return {
+      kind: "title",
+      title
+    };
+  }
+  createEmpty(count) {
+    return {
+      kind: "empty",
+      count
+    };
+  }
+  createClear() {
+    return {
+      kind: "clear"
+    };
+  }
+  _serializeLogEntry(entry) {
+    return {
+      timestamp: entry.timestamp.toISOString(),
+      type: this._serializeLogType(entry.type),
+      message: entry.message,
+      args: entry.args.map(
+        (argument) => this._serializer.serializeValue(argument)
+      ),
+      scope: entry.scope
+    };
+  }
+  _serializeLogType(type) {
+    switch (type) {
+      case import_logora.LogType.Debug:
+        return "debug";
+      case import_logora.LogType.Info:
+        return "info";
+      case import_logora.LogType.Success:
+        return "success";
+      case import_logora.LogType.Warning:
+        return "warning";
+      case import_logora.LogType.Error:
+        return "error";
+      case import_logora.LogType.Highlight:
+        return "highlight";
+      case import_logora.LogType.Raw:
+        return "raw";
+      default:
+        return String(type);
+    }
+  }
+};
+
+// src/core/writer.ts
+var WebSocketWriter = class {
+  constructor(_options) {
+    this._options = _options;
+    this._instructionFactory = new WebSocketInstructionFactory(
+      this._options.serializer
+    );
+  }
+  log(entry) {
+    this._dispatch(this._instructionFactory.createLog(entry));
+  }
+  title(title) {
+    this._dispatch(this._instructionFactory.createTitle(title));
+  }
+  empty(count = 1) {
+    this._dispatch(this._instructionFactory.createEmpty(Math.max(0, count)));
+  }
+  clear() {
+    this._dispatch(this._instructionFactory.createClear());
+  }
+  print(message, ...args) {
+    this._dispatch(this._instructionFactory.createPrint(message, args));
+  }
+  _dispatch(instruction) {
+    const payload = this._options.serializer.serialize(instruction);
+    this._options.broadcaster.broadcast(payload);
+  }
+};
+
+// src/core/output.ts
+var WebSocketOutput = class {
+  constructor(config) {
+    this.name = "websocket";
+    this.options = new WebSocketOutputOptions(config);
+    this.writer = new WebSocketWriter(this.options);
+  }
+};
+
+// src/core/ws-broadcaster.ts
+var OPEN_READY_STATE = 1;
+function createWsBroadcaster(server) {
+  return {
+    broadcast(message) {
+      for (const client of server.clients) {
+        if (client.readyState !== OPEN_READY_STATE) {
+          continue;
+        }
+        try {
+          client.send(message);
+        } catch {
+        }
+      }
+    }
+  };
+}
+
+// src/index.ts
+function createWebSocketOutput(config) {
+  return new WebSocketOutput(config);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  WebSocketOutputOptions,
+  createWebSocketOutput,
+  createWsBroadcaster
+});

package/dist/index.mjs

@@ -0,0 +1,257 @@
+// src/core/instruction-serializer.ts
+var DefaultWebSocketInstructionSerializer = class {
+  constructor(config) {
+    var _a, _b, _c;
+    this._maxDepth = (_a = config == null ? void 0 : config.maxDepth) != null ? _a : 6;
+    this._maxArrayLength = (_b = config == null ? void 0 : config.maxArrayLength) != null ? _b : 100;
+    this._maxObjectKeys = (_c = config == null ? void 0 : config.maxObjectKeys) != null ? _c : 100;
+  }
+  serialize(instruction) {
+    return JSON.stringify(instruction);
+  }
+  serializeValue(value) {
+    return this._serializeInternal(value, {
+      visitedObjects: /* @__PURE__ */ new WeakSet(),
+      depth: 0
+    });
+  }
+  _serializeInternal(value, context) {
+    if (value === null || value === void 0) {
+      return null;
+    }
+    if (typeof value === "string") {
+      return value;
+    }
+    if (typeof value === "number") {
+      return Number.isFinite(value) ? value : String(value);
+    }
+    if (typeof value === "boolean") {
+      return value;
+    }
+    if (typeof value === "symbol") {
+      return {
+        __type: "Symbol",
+        value: value.toString()
+      };
+    }
+    if (typeof value === "function") {
+      return {
+        __type: "Function",
+        name: value.name || "anonymous"
+      };
+    }
+    if (value instanceof Date) {
+      return {
+        __type: "Date",
+        value: value.toISOString()
+      };
+    }
+    if (value instanceof Error) {
+      return this._serializeError(value, context);
+    }
+    if (context.depth >= this._maxDepth) {
+      return "[MaxDepthExceeded]";
+    }
+    if (Array.isArray(value)) {
+      return this._serializeArray(value, context);
+    }
+    if (typeof value === "object") {
+      return this._serializeObject(value, context);
+    }
+    return "[UnsupportedValue]";
+  }
+  _serializeError(value, context) {
+    const serializedError = {
+      __type: "Error",
+      name: value.name,
+      message: value.message
+    };
+    if (value.stack) {
+      serializedError.stack = value.stack;
+    }
+    const errorWithCause = value;
+    if (errorWithCause.cause !== void 0) {
+      serializedError.cause = this._serializeInternal(errorWithCause.cause, {
+        ...context,
+        depth: context.depth + 1
+      });
+    }
+    return serializedError;
+  }
+  _serializeArray(value, context) {
+    return value.slice(0, this._maxArrayLength).map(
+      (item) => this._serializeInternal(item, {
+        ...context,
+        depth: context.depth + 1
+      })
+    );
+  }
+  _serializeObject(value, context) {
+    if (context.visitedObjects.has(value)) {
+      return "[Circular]";
+    }
+    context.visitedObjects.add(value);
+    const serializedObject = {};
+    const entries = Object.entries(value).slice(
+      0,
+      this._maxObjectKeys
+    );
+    for (const [key, entryValue] of entries) {
+      serializedObject[key] = this._serializeInternal(entryValue, {
+        ...context,
+        depth: context.depth + 1
+      });
+    }
+    return serializedObject;
+  }
+};
+
+// src/config/websocket-output-options.ts
+var WebSocketOutputOptions = class {
+  constructor(overrides) {
+    this.serializer = new DefaultWebSocketInstructionSerializer();
+    Object.assign(this, overrides);
+    if (!this.broadcaster) {
+      throw new Error(
+        "WebSocketOutputOptions requires a broadcaster instance."
+      );
+    }
+  }
+};
+
+// src/core/instruction-factory.ts
+import { LogType } from "logora";
+var WebSocketInstructionFactory = class {
+  constructor(_serializer) {
+    this._serializer = _serializer;
+  }
+  createLog(entry) {
+    return {
+      kind: "log",
+      entry: this._serializeLogEntry(entry)
+    };
+  }
+  createPrint(message, args) {
+    return {
+      kind: "print",
+      message,
+      args: args.map(
+        (argument) => this._serializer.serializeValue(argument)
+      )
+    };
+  }
+  createTitle(title) {
+    return {
+      kind: "title",
+      title
+    };
+  }
+  createEmpty(count) {
+    return {
+      kind: "empty",
+      count
+    };
+  }
+  createClear() {
+    return {
+      kind: "clear"
+    };
+  }
+  _serializeLogEntry(entry) {
+    return {
+      timestamp: entry.timestamp.toISOString(),
+      type: this._serializeLogType(entry.type),
+      message: entry.message,
+      args: entry.args.map(
+        (argument) => this._serializer.serializeValue(argument)
+      ),
+      scope: entry.scope
+    };
+  }
+  _serializeLogType(type) {
+    switch (type) {
+      case LogType.Debug:
+        return "debug";
+      case LogType.Info:
+        return "info";
+      case LogType.Success:
+        return "success";
+      case LogType.Warning:
+        return "warning";
+      case LogType.Error:
+        return "error";
+      case LogType.Highlight:
+        return "highlight";
+      case LogType.Raw:
+        return "raw";
+      default:
+        return String(type);
+    }
+  }
+};
+
+// src/core/writer.ts
+var WebSocketWriter = class {
+  constructor(_options) {
+    this._options = _options;
+    this._instructionFactory = new WebSocketInstructionFactory(
+      this._options.serializer
+    );
+  }
+  log(entry) {
+    this._dispatch(this._instructionFactory.createLog(entry));
+  }
+  title(title) {
+    this._dispatch(this._instructionFactory.createTitle(title));
+  }
+  empty(count = 1) {
+    this._dispatch(this._instructionFactory.createEmpty(Math.max(0, count)));
+  }
+  clear() {
+    this._dispatch(this._instructionFactory.createClear());
+  }
+  print(message, ...args) {
+    this._dispatch(this._instructionFactory.createPrint(message, args));
+  }
+  _dispatch(instruction) {
+    const payload = this._options.serializer.serialize(instruction);
+    this._options.broadcaster.broadcast(payload);
+  }
+};
+
+// src/core/output.ts
+var WebSocketOutput = class {
+  constructor(config) {
+    this.name = "websocket";
+    this.options = new WebSocketOutputOptions(config);
+    this.writer = new WebSocketWriter(this.options);
+  }
+};
+
+// src/core/ws-broadcaster.ts
+var OPEN_READY_STATE = 1;
+function createWsBroadcaster(server) {
+  return {
+    broadcast(message) {
+      for (const client of server.clients) {
+        if (client.readyState !== OPEN_READY_STATE) {
+          continue;
+        }
+        try {
+          client.send(message);
+        } catch {
+        }
+      }
+    }
+  };
+}
+
+// src/index.ts
+function createWebSocketOutput(config) {
+  return new WebSocketOutput(config);
+}
+export {
+  WebSocketOutputOptions,
+  createWebSocketOutput,
+  createWsBroadcaster
+};

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "logora-websocket",
+  "version": "1.0.3",
+  "description": "websocket plugin for Logora – enables real-time communication.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "lint": "eslint src tests --ext .ts",
+    "lint:fix": "eslint src tests --ext .ts --fix",
+    "test": "vitest run",
+    "test:dev": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "build": "tsup",
+    "build:dev": "tsup --watch",
+    "build:prod": "npm run clean && npm run lint && npm run build",
+    "clean": "rimraf dist",
+    "check": "npm run lint && npm run test && npm run build",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run build:prod"
+  },
+  "keywords": [
+    "logger",
+    "logora",
+    "typescript",
+    "logging",
+    "websocket"
+  ],
+  "author": "Sébastien Bosmans <https://github.com/boseba>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/boseba/logora-websocket.git"
+  },
+  "bugs": {
+    "url": "https://github.com/boseba/logora-websocket/issues"
+  },
+  "homepage": "https://github.com/boseba/logora-websocket#readme",
+  "engines": {
+    "node": ">=16"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.25.1",
+    "@vitest/coverage-v8": "^3.1.2",
+    "eslint": "^9.25.1",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.31.0",
+    "vitest": "^3.1.2"
+  },
+  "dependencies": {
+    "dayjs": "^1.11.13",
+    "logora": "^2.0.5"
+  }
+}