@loggerjs/node 0.0.2 → 0.3.0

package/README.md

@@ -1,26 +1,48 @@
 # @loggerjs/node
 
-Node transports, process integrations, diagnostics-channel capture, and AsyncLocalStorage context.
+> Node.js transports, AsyncLocalStorage context, and 16 automatic integrations — re-exports all of `@loggerjs/core`.
+
+[![npm](https://img.shields.io/npm/v/@loggerjs/node.svg)](https://www.npmjs.com/package/@loggerjs/node)
+[![license](https://img.shields.io/npm/l/@loggerjs/node)](../../LICENSE)
+[![Node](https://img.shields.io/badge/Node-%E2%89%A522.13-339933?logo=node.js&logoColor=white)](package.json)
+
+The Node platform package for [LoggerJS](../../README.md). It re-exports the entire `@loggerjs/core` API and adds stdout/stderr/file/HTTP/syslog/worker transports, an AsyncLocalStorage context bridge, and integrations that turn process crashes, HTTP frameworks, clients, and queues into structured logs — all opt-in.
+
+## Install
+
+```bash
+npm install @loggerjs/node @loggerjs/processors
+```
+
+`@loggerjs/processors` is optional but recommended for redaction, sampling, and enrichment.
+
+## Usage
 
 ```ts
 import {
   captureProcessIntegration,
   createLogger,
-  expressIntegration,
-  fastifyIntegration,
   installAsyncLocalStorageContext,
+  nodeCompressionPayloadTransform,
   nodeFetchIntegration,
   nodeHttpClientIntegration,
-  nodeSyslogTransport,
-  rotatingFileTransport,
+  nodeHttpTransport,
   stdoutTransport,
 } from "@loggerjs/node";
 
-installAsyncLocalStorageContext();
+installAsyncLocalStorageContext(); // once at startup — context follows async execution
 
 const logger = createLogger({
-  name: "api",
-  transports: [stdoutTransport()],
+  category: ["api"],
+  level: "info",
+  tags: { service: "checkout", env: process.env.NODE_ENV ?? "dev" },
+  transports: [
+    stdoutTransport(), // one NDJSON line per log
+    nodeHttpTransport({
+      url: "https://collector.example/logs",
+      transformPayload: nodeCompressionPayloadTransform({ format: "brotli" }),
+    }),
+  ],
   integrations: [captureProcessIntegration(), nodeHttpClientIntegration(), nodeFetchIntegration()],
 });
 
@@ -28,26 +50,85 @@ logger.info("server started", { port: 3000 });
 await logger.flush();
 ```
 
-```ts
-const infraLogger = createLogger({
-  name: "infra",
-  transports: [nodeSyslogTransport({ host: "127.0.0.1", port: 514, facility: 16 })],
-});
-```
+### HTTP frameworks
 
 ```ts
-const auditLogger = createLogger({
-  name: "audit",
-  transports: [rotatingFileTransport({ path: "audit.log", maxBytes: 10 * 1024 * 1024 })],
-});
+app.use(expressIntegration(logger, { captureAll: true }));     // Express middleware
+fastify.register(fastifyIntegration(logger, { captureAll: true })); // Fastify plugin
 ```
 
+### Other destinations
+
 ```ts
-app.use(expressIntegration(logger, { captureAll: true }));
+import { nodeSyslogTransport, rotatingFileTransport } from "@loggerjs/node";
+
+nodeSyslogTransport({ host: "127.0.0.1", port: 514, facility: 16 });
+rotatingFileTransport({ path: "audit.log", maxBytes: 10 * 1024 * 1024 });
 ```
 
+## Transports
+
+| Transport | Delivers to |
+| --- | --- |
+| `stdoutTransport` / `stderrTransport` | process streams, one NDJSON line per log, drain-aware flush, optional `minLength` buffering, clean `EPIPE` shutdown |
+| `fileTransport` / `rotatingFileTransport` | files, with `mkdir`/`append` controls, optional `sync: true`, crash-path `flushSync`, and size-based rotation |
+| `nodeHttpTransport` | a collector over `fetch`, wrapped in `batchTransport` (batching + retry) |
+| `nodeSyslogTransport` | RFC 5424 syslog over UDP/TCP |
+| `workerTransport` | a worker thread (encodes batches with a codec, optional buffer transfer, ready/ack lifecycle, fallback on worker failure) |
+
+File and process-stream transports share the same internal destination logic for
+write callbacks, drain waiting, `minLength` buffering, close, and sync crash
+flush. Use `await flush()` for normal shutdown. Use `flushSync()` only on fatal
+paths, or configure `fileTransport({ sync: true })` when every write must reach
+the filesystem before the log call returns.
+
+`workerTransport()` is fire-and-forget unless you opt into lifecycle checks.
+Use `readyTimeoutMs` for workers that send `{ type: "loggerjs:ready" }`, and
+`ackTimeoutMs` for workers that acknowledge `{ type: "loggerjs:batch", id }`
+with `{ type: "loggerjs:batch:ack", id }`. Pending batches fall back or are
+counted as drops when readiness, posting, ack, or worker exit fails. Set
+`autoEnd: false` for shared workers you close elsewhere. Explicit
+`transport.ready()` / `logger.ready()` waits for the ready handshake when
+`readyTimeoutMs` is configured.
+
+Call `installLoggerDiagnosticsChannel()` to publish LoggerJS internal
+diagnostics to Node `diagnostics_channel` channels such as `loggerjs.dispatch`,
+`loggerjs.transport`, `loggerjs.flush`, `loggerjs.encode`, and
+`loggerjs.worker`.
+
+## Integrations (16)
+
+| Group | Integrations |
+| --- | --- |
+| **Process & runtime** | `captureProcessIntegration`, `captureCliIntegration`, `diagnosticsChannelIntegration`, `serverlessIntegration` |
+| **HTTP frameworks** | `expressIntegration`, `fastifyIntegration`, `koaIntegration`, `hapiIntegration`, `nestMiddlewareIntegration` |
+| **Clients** | `nodeFetchIntegration`, `nodeHttpClientIntegration`, `redisIntegration`, `prismaIntegration`, `databaseIntegration` |
+| **Queues** | `queueIntegration`, `bullMqIntegration` |
+
+`captureProcessIntegration()` turns uncaught exceptions (fatal), unhandled rejections, warnings, and exit into log events; with `exitOnUncaught` it captures the fatal record, calls `flushSync()`, waits for bounded async `flush()`, then exits. Every integration is tagged `source: "integration:<name>"` and guarded against capture loops.
+
+### Context manager
+
 ```ts
-fastify.register(fastifyIntegration(logger, { captureAll: true }));
+import { installAsyncLocalStorageContext, withContext } from "@loggerjs/node";
+
+installAsyncLocalStorageContext(); // once at startup
+await withContext({ requestId: "req_123" }, async () => {
+  logger.info("request started"); // { requestId } follows across awaits
+});
 ```
 
-Subpaths expose `transport-http`, `transport-file`, `transport-rotating-file`, `transport-stdout`, `transport-syslog`, `transport-worker`, `integration-process`, `integration-cli`, `integration-queue`, `integration-serverless`, `integration-database`, `integration-express`, `integration-fastify`, `integration-fetch`, `integration-http-client`, `integration-diagnostics`, and `context`.
+## Subpath exports
+
+Transports — `transport-stdout` · `transport-file` · `transport-rotating-file` · `transport-http` · `transport-syslog` · `transport-worker` · `payload-transforms` · `logger-diagnostics` · `context`
+
+Integrations — `integration-process` · `integration-cli` · `integration-diagnostics` · `integration-serverless` · `integration-express` · `integration-fastify` · `integration-koa` · `integration-nest` · `integration-hapi` · `integration-fetch` · `integration-http-client` · `integration-redis` · `integration-prisma` · `integration-database` · `integration-queue` · `integration-bullmq`
+
+## Documentation
+
+- [Transports](../../docs/TRANSPORTS.md) · [Integrations](../../docs/INTEGRATIONS.md) · [Operations](../../docs/OPERATIONS.md)
+- [Getting Started](../../docs/GETTING-STARTED.md) · [LoggerJS root README](../../README.md)
+
+## License
+
+[MIT](../../LICENSE) © JS Kits

package/dist/bullmq-integration.d.ts

@@ -0,0 +1,9 @@
+import { type QueueClientLike, type QueueIntegrationOptions } from "./queue-integration.js";
+export interface BullMqIntegrationOptions extends Omit<QueueIntegrationOptions, "client" | "system" | "methods" | "getQueueName"> {
+    client: QueueClientLike & {
+        name?: string;
+    };
+    methods?: readonly string[];
+}
+export declare function bullMqIntegration(options: BullMqIntegrationOptions): import("@loggerjs/core").Integration;
+//# sourceMappingURL=bullmq-integration.d.ts.map

package/dist/bullmq-integration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bullmq-integration.d.ts","sourceRoot":"","sources":["../src/bullmq-integration.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC7B,MAAM,qBAAqB,CAAC;AAE7B,MAAM,WAAW,wBAAyB,SAAQ,IAAI,CACpD,uBAAuB,EACvB,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,cAAc,CACjD;IACC,MAAM,EAAE,eAAe,GAAG;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AASD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,wCASlE"}

package/dist/file-transport.d.ts

@@ -1,14 +1,18 @@
-import { type WriteStream } from "fs";
 import { type Codec, type LoggerLevel, type Transport } from "@loggerjs/core";
+import type { WriteStream } from "fs";
 export interface FileTransportOptions {
     path: string;
     name?: string;
     codec?: Codec<string | Uint8Array>;
     minLevel?: LoggerLevel;
     flags?: string;
+    append?: boolean;
+    mkdir?: boolean;
+    sync?: boolean;
+    minLength?: number;
 }
 export interface FileTransport extends Transport {
-    stream: WriteStream;
+    stream?: WriteStream;
     flushSync: () => void;
 }
 export declare function fileTransport(options: FileTransportOptions): FileTransport;

package/dist/file-transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-transport.d.ts","sourceRoot":"","sources":["../src/file-transport.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqD,KAAK,WAAW,EAAE,MAAM,IAAI,CAAC;AACzF,OAAO,EAGL,KAAK,KAAK,EAEV,KAAK,WAAW,EAChB,KAAK,SAAS,EACf,MAAM,gBAAgB,CAAC;AAExB,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,UAAU,CAAC,CAAC;IACnC,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAc,SAAQ,SAAS;IAC9C,MAAM,EAAE,WAAW,CAAC;IACpB,SAAS,EAAE,MAAM,IAAI,CAAC;CACvB;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CA8D1E"}
+{"version":3,"file":"file-transport.d.ts","sourceRoot":"","sources":["../src/file-transport.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,KAAK,EAEV,KAAK,WAAW,EAChB,KAAK,SAAS,EACf,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,IAAI,CAAC;AAGtC,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,UAAU,CAAC,CAAC;IACnC,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAc,SAAQ,SAAS;IAC9C,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,EAAE,MAAM,IAAI,CAAC;CACvB;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAwB1E"}

package/dist/hapi-integration.d.ts

@@ -0,0 +1,44 @@
+import { type LoggerLevel, type LoggerLike } from "@loggerjs/core";
+export interface HapiRequestLike {
+    method?: string;
+    path?: string;
+    url?: {
+        pathname?: string;
+    };
+    info?: {
+        id?: string;
+        received?: number;
+        remoteAddress?: string;
+    };
+    response?: {
+        statusCode?: number;
+    } | {
+        isBoom?: boolean;
+        output?: {
+            statusCode?: number;
+        };
+    };
+    app?: Record<string, unknown>;
+}
+export interface HapiToolkitLike {
+    continue: unknown;
+}
+export interface HapiServerLike {
+    ext: (event: "onRequest", handler: (request: HapiRequestLike, h: HapiToolkitLike) => unknown) => unknown;
+    events?: {
+        on?: (event: "response", handler: (request: HapiRequestLike) => void) => unknown;
+    };
+}
+export interface HapiIntegrationOptions {
+    minStatus?: number;
+    captureAll?: boolean;
+    bindContext?: boolean;
+    getRequestId?: (request: HapiRequestLike) => string | undefined;
+    context?: (request: HapiRequestLike) => Record<string, unknown> | undefined;
+    level?: (status: number, request: HapiRequestLike) => LoggerLevel;
+}
+export declare function hapiIntegration(logger: LoggerLike, options?: HapiIntegrationOptions): {
+    name: string;
+    register(server: HapiServerLike): void;
+};
+//# sourceMappingURL=hapi-integration.d.ts.map

package/dist/hapi-integration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hapi-integration.d.ts","sourceRoot":"","sources":["../src/hapi-integration.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,WAAW,EAAE,KAAK,UAAU,EAAgB,MAAM,gBAAgB,CAAC;AAE9F,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5B,IAAI,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAClE,QAAQ,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE;YAAE,UAAU,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC;IAC5F,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,CACH,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,CAAC,OAAO,EAAE,eAAe,EAAE,CAAC,EAAE,eAAe,KAAK,OAAO,KAC/D,OAAO,CAAC;IACb,MAAM,CAAC,EAAE;QACP,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,KAAK,OAAO,CAAC;KAClF,CAAC;CACH;AAED,MAAM,WAAW,sBAAsB;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,MAAM,GAAG,SAAS,CAAC;IAChE,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAC5E,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,KAAK,WAAW,CAAC;CACnE;AAkBD,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,GAAE,sBAA2B;;qBAQnE,cAAc;EAsClC"}

package/dist/http-transport.d.ts

@@ -1,4 +1,4 @@
-import { type BatchTransportOptions, type Codec, type LoggerLevel, type Transport } from "@loggerjs/core";
+import { type BatchTransportOptions, type Codec, type LoggerLevel, type PayloadTransform, type Transport } from "@loggerjs/core";
 export interface NodeHttpTransportOptions extends BatchTransportOptions {
     url: string;
     name?: string;
@@ -7,6 +7,7 @@ export interface NodeHttpTransportOptions extends BatchTransportOptions {
     codec?: Codec<string | Uint8Array>;
     minLevel?: LoggerLevel;
     fetchFn?: typeof fetch;
+    transformPayload?: PayloadTransform | readonly PayloadTransform[];
 }
 export declare function nodeHttpTransport(options: NodeHttpTransportOptions): Transport;
 //# sourceMappingURL=http-transport.d.ts.map

package/dist/http-transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http-transport.d.ts","sourceRoot":"","sources":["../src/http-transport.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,qBAAqB,EAC1B,KAAK,KAAK,EAEV,KAAK,WAAW,EAChB,KAAK,SAAS,EACf,MAAM,gBAAgB,CAAC;AAExB,MAAM,WAAW,wBAAyB,SAAQ,qBAAqB;IACrE,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,KAAK,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,UAAU,CAAC,CAAC;IACnC,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACxB;AAOD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,SAAS,CAsC9E"}
+{"version":3,"file":"http-transport.d.ts","sourceRoot":"","sources":["../src/http-transport.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,qBAAqB,EAC1B,KAAK,KAAK,EAGV,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACf,MAAM,gBAAgB,CAAC;AAExB,MAAM,WAAW,wBAAyB,SAAQ,qBAAqB;IACrE,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,KAAK,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,UAAU,CAAC,CAAC;IACnC,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB,gBAAgB,CAAC,EAAE,gBAAgB,GAAG,SAAS,gBAAgB,EAAE,CAAC;CACnE;AAOD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,SAAS,CAiD9E"}