logora-websocket

logora-websocket is the official WebSocket output module for the 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, 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