@holz/stream-backend 0.4.0 → 0.6.0

package/README.md

@@ -0,0 +1,46 @@
+# `@holz/stream-backend`
+
+A Holz plugin that streams logs in plaintext. It is optimized for log files.
+
+## Usage
+
+To use `@holz/stream-backend`, you first need to import it and create a backend with `createStreamBackend()`:
+
+```typescript
+import { createStreamBackend } from '@holz/stream-backend';
+import { createLogger } from '@holz/core';
+import * as fs from 'fs';
+
+createLogger(
+  createStreamBackend({
+    stream: fs.createWriteStream('server.log', { flags: 'a' }),
+  })
+);
+```
+
+The `stream` option specifies the NodeJS writable stream that the logs should be written to. You can use any writable stream, such as a file or `process.stderr`.
+
+> **Note**  
+> If your system supports JSON, consider [`@holz/json-backend`](https://github.com/PsychoLlama/holz/tree/main/packages/holz-json-backend) as a structured alternative.
+
+## Example Output
+
+When you write logs using `@holz/stream-backend`, they are formatted as plaintext and written to the stream. Each log entry is separated by a line break.
+
+```
+2023-03-04T21:58:11.620Z INFO  [app:devices] Requesting media devices
+2023-03-04T21:58:14.288Z INFO  [app:devices] Received media stream kind=["audio"]
+2023-03-04T21:58:14.288Z WARN  [app:devices] User does not have a camera
+2023-03-04T21:58:14.288Z INFO  [app:rtc] Creating WebRTC session signalingMode="polite"
+2023-03-04T21:58:14.288Z INFO  [app:signaling] Opening signaling channel
+2023-03-04T21:58:14.346Z DEBUG [app:signaling] Signaling channel is open
+2023-03-04T21:58:14.347Z INFO  [app:rtc] Sending session description type="offer"
+2023-03-04T21:58:14.491Z INFO  [app:rtc] Receiving session description type="answer"
+2023-03-04T21:58:14.494Z DEBUG [app:rtc] Sending ICE candidate type="UDP" ip="10.0.0.10" port="33150"
+2023-03-04T21:58:14.494Z INFO  [app:rtc] Attaching local media tracks kind=["audio"]
+2023-03-04T21:58:14.619Z DEBUG [app:rtc] Receiving ICE candidate type="UDP" ip="10.0.0.11" port="36877"
+2023-03-04T21:58:14.630Z INFO  [app:rtc] Testing remote candidates...
+2023-03-04T21:58:14.684Z INFO  [app:rtc] Connection successful.
+```
+
+Note that the logs include a timestamp, log level, namespace, message, and any additional context that was provided.

package/dist/holz-stream-backend.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const u=require("node:os"),r=require("@holz/core");class i{constructor(e){this.stream=e.stream}processLog(e){const t=new Date().toISOString(),n=g[e.level],s=this.stringifyContext(e.context),c=e.origin.length?`[${e.origin.join(":")}] `:"",o=`${t} ${n} ${c}`,a=this.multilineIndent(o.length,e.message),l=`${o}${a}${s?" "+s:""}${u.EOL}`;this.stream.write(l)}stringifyContext(e){return Object.entries(e).map(([t,n])=>`${t}=${JSON.stringify(n)}`).join(" ")}multilineIndent(e,t){return t.replace(/(\r?\n)/g,n=>n+" ".repeat(e))}}const g={[r.LogLevel.Debug]:"DEBUG",[r.LogLevel.Info]:"INFO ",[r.LogLevel.Warn]:"WARN ",[r.LogLevel.Error]:"ERROR"};exports.StreamBackend=i;exports.default=i;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const g=require("node:os"),r=require("@holz/core");function l({stream:t}){return e=>{const n=new Date().toISOString(),i=m[e.level],o=$(e.context),s=e.origin.length?`[${e.origin.join(":")}] `:"",c=`${n} ${i} ${s}`,a=L(c.length,e.message),u=`${c}${a}${o?" "+o:""}`;t.write(`${u}${g.EOL}`)}}function L(t,e){return e.replace(/(\r?\n)/g,n=>n+" ".repeat(t))}function $(t){return Object.entries(t).map(([e,n])=>`${e}=${JSON.stringify(n)}`).join(" ")}const m={[r.LogLevel.Debug]:"DEBUG",[r.LogLevel.Info]:"INFO ",[r.LogLevel.Warn]:"WARN ",[r.LogLevel.Error]:"ERROR"};exports.createStreamBackend=l;

package/dist/holz-stream-backend.js

@@ -1,27 +1,16 @@
-import { EOL as m } from "node:os";
+import { EOL as u } from "node:os";
 import { LogLevel as r } from "@holz/core";
-class p {
-  constructor(t) {
-    this.stream = t.stream;
-  }
-  processLog(t) {
-    const e = new Date().toISOString(), n = g[t.level], s = this.stringifyContext(t.context), o = t.origin.length ? `[${t.origin.join(":")}] ` : "", i = `${e} ${n} ${o}`, c = this.multilineIndent(i.length, t.message), a = `${i}${c}${s ? " " + s : ""}${m}`;
-    this.stream.write(a);
-  }
-  // { id: 123, type: 'article' } -> 'id=123 type="article"'
-  stringifyContext(t) {
-    return Object.entries(t).map(([e, n]) => `${e}=${JSON.stringify(n)}`).join(" ");
-  }
-  // Some messages will ruin your output without proper indentation. Stack
-  // traces are a good example of this.
-  //
-  // Supports Unix + DOS line endings.
-  multilineIndent(t, e) {
-    return e.replace(
-      /(\r?\n)/g,
-      (n) => n + " ".repeat(t)
-    );
-  }
+function l({ stream: t }) {
+  return (e) => {
+    const n = new Date().toISOString(), c = g[e.level], o = f(e.context), s = e.origin.length ? `[${e.origin.join(":")}] ` : "", i = `${n} ${c} ${s}`, a = $(i.length, e.message), m = `${i}${a}${o ? " " + o : ""}`;
+    t.write(`${m}${u}`);
+  };
+}
+function $(t, e) {
+  return e.replace(/(\r?\n)/g, (n) => n + " ".repeat(t));
+}
+function f(t) {
+  return Object.entries(t).map(([e, n]) => `${e}=${JSON.stringify(n)}`).join(" ");
 }
 const g = {
   [r.Debug]: "DEBUG",
@@ -30,6 +19,5 @@ const g = {
   [r.Error]: "ERROR"
 };
 export {
-  p as StreamBackend,
-  p as default
+  l as createStreamBackend
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holz/stream-backend",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Print logs to stdout or a file.",
   "type": "module",
   "main": "./dist/holz-stream-backend.cjs",
@@ -39,13 +39,13 @@
     "test:types": "tsc"
   },
   "peerDependencies": {
-    "@holz/core": "0.2.0"
+    "@holz/core": "^0.6.0"
   },
   "devDependencies": {
-    "@holz/core": "0.2.0",
+    "@holz/core": "^0.6.0",
     "@types/node": "^18.14.0",
-    "@vitest/coverage-c8": "0.28.5",
-    "typescript": "4.9.5",
+    "@vitest/coverage-c8": "^0.28.5",
+    "typescript": "^4.9.5",
     "vite": "^4.0.0",
     "vitest": "^0.28.5"
   }

package/src/__tests__/stream-backend.test.ts

@@ -1,6 +1,6 @@
 import { Writable } from 'node:stream';
 import { createLogger } from '@holz/core';
-import StreamBackend from '../stream-backend';
+import { createStreamBackend } from '../stream-backend';
 
 const CURRENT_TIME = new Date('2020-06-15T12:00:00.000Z');
 
@@ -32,7 +32,7 @@ describe('Stream backend', () => {
 
   it('prints the logs to the writable stream', () => {
     const { stream, getOutput } = createStream();
-    const backend = new StreamBackend({ stream });
+    const backend = createStreamBackend({ stream });
 
     const logger = createLogger(backend);
     logger.debug('shout');
@@ -51,7 +51,7 @@ describe('Stream backend', () => {
 
   it('includes the log namespace', () => {
     const { stream, getOutput } = createStream();
-    const backend = new StreamBackend({ stream });
+    const backend = createStreamBackend({ stream });
     const logger = createLogger(backend)
       .namespace('my-lib')
       .namespace('MyClass');
@@ -63,7 +63,7 @@ describe('Stream backend', () => {
 
   it('does not print the log namespace if it is empty', () => {
     const { stream, getOutput } = createStream();
-    const backend = new StreamBackend({ stream });
+    const backend = createStreamBackend({ stream });
     const logger = createLogger(backend);
 
     logger.debug('orphan log');
@@ -73,7 +73,7 @@ describe('Stream backend', () => {
 
   it('includes the log context', () => {
     const { stream, getOutput } = createStream();
-    const backend = new StreamBackend({ stream });
+    const backend = createStreamBackend({ stream });
     const logger = createLogger(backend);
 
     logger.info('creating session', { sessionId: 3109, enabled: true });
@@ -84,7 +84,7 @@ describe('Stream backend', () => {
 
   it('includes the timestamp for each log', () => {
     const { stream, getOutput } = createStream();
-    const backend = new StreamBackend({ stream });
+    const backend = createStreamBackend({ stream });
     const logger = createLogger(backend);
 
     logger.info('traveling through time');
@@ -94,7 +94,7 @@ describe('Stream backend', () => {
 
   it('wraps strings in log context with quotes', () => {
     const { stream, getOutput } = createStream();
-    const backend = new StreamBackend({ stream });
+    const backend = createStreamBackend({ stream });
     const logger = createLogger(backend);
 
     logger.info('creating session', { code: 'ENOBACON' });
@@ -104,7 +104,7 @@ describe('Stream backend', () => {
 
   it('joins arrays in log context', () => {
     const { stream, getOutput } = createStream();
-    const backend = new StreamBackend({ stream });
+    const backend = createStreamBackend({ stream });
     const logger = createLogger(backend);
 
     logger.info('adding tags', { tags: ['important', 'urgent'] });
@@ -114,7 +114,7 @@ describe('Stream backend', () => {
 
   it('indents multi-line log statements', () => {
     const { stream, getOutput } = createStream();
-    const backend = new StreamBackend({ stream });
+    const backend = createStreamBackend({ stream });
     const logger = createLogger(backend);
 
     logger.info('multi-line log\r\nwith a second line\nand a third line');

package/src/index.ts

@@ -1 +1 @@
-export { default, default as StreamBackend } from './stream-backend';
+export { createStreamBackend } from './stream-backend';

package/src/stream-backend.ts

@@ -7,26 +7,20 @@ import type { Log, LogContext, LogProcessor } from '@holz/core';
  * Prints logs to a writable stream in plaintext. Optimized for log files.
  *
  * @example
- * new StreamBackend({
+ * createStreamBackend({
  *   stream: fs.createWriteStream('my-app.log', { flags: 'a' }),
  * })
  */
-export default class StreamBackend implements LogProcessor {
-  private stream: Writable;
-
-  constructor(options: Config) {
-    this.stream = options.stream;
-  }
-
-  processLog(log: Log) {
+export function createStreamBackend({ stream }: Config): LogProcessor {
+  return (log: Log) => {
     const currentTime = new Date().toISOString();
     const level = LOG_LEVELS[log.level];
-    const context = this.stringifyContext(log.context);
+    const context = stringifyContext(log.context);
     const namespace = log.origin.length ? `[${log.origin.join(':')}] ` : '';
 
     const header = `${currentTime} ${level} ${namespace}`;
-    const message = this.multilineIndent(header.length, log.message);
-    const output = `${header}${message}${context ? ' ' + context : ''}${EOL}`;
+    const message = multilineIndent(header.length, log.message);
+    const output = `${header}${message}${context ? ' ' + context : ''}`;
 
     // NOTE: If the stream applies backpressure, we will lose logs. I believe
     // this is the right tradeoff. We can't prevent the app from generating
@@ -34,26 +28,25 @@ export default class StreamBackend implements LogProcessor {
     // crashing the process.
     //
     // It is unlikely that a file or tty will apply backpressure in practice.
-    this.stream.write(output);
-  }
+    stream.write(`${output}${EOL}`);
+  };
+}
 
-  // { id: 123, type: 'article' } -> 'id=123 type="article"'
-  private stringifyContext(context: LogContext) {
-    return Object.entries(context)
-      .map(([key, value]) => `${key}=${JSON.stringify(value)}`)
-      .join(' ');
-  }
+/**
+ * Some messages will ruin your output without proper indentation. Stack
+ * traces are a good example of this.
+ *
+ * Supports Unix + DOS line endings.
+ */
+function multilineIndent(offset: number, message: string) {
+  return message.replace(/(\r?\n)/g, (newline) => newline + ' '.repeat(offset));
+}
 
-  // Some messages will ruin your output without proper indentation. Stack
-  // traces are a good example of this.
-  //
-  // Supports Unix + DOS line endings.
-  private multilineIndent(offset: number, message: string) {
-    return message.replace(
-      /(\r?\n)/g,
-      (newline) => newline + ' '.repeat(offset)
-    );
-  }
+// { id: 123, type: 'article' } -> 'id=123 type="article"'
+function stringifyContext(context: LogContext) {
+  return Object.entries(context)
+    .map(([key, value]) => `${key}=${JSON.stringify(value)}`)
+    .join(' ');
 }
 
 const LOG_LEVELS: Record<LogLevel, string> = {