@holz/stream-backend 0.1.0

package/dist/holz-stream-backend.js

@@ -0,0 +1,35 @@
+var s = /* @__PURE__ */ ((t) => (t.Error = "error", t.Warn = "warn", t.Info = "info", t.Debug = "debug", t))(s || {});
+class m {
+  constructor(e) {
+    this.stream = e.stream;
+  }
+  processLog(e) {
+    const n = new Date().toISOString(), r = g[e.level], i = this.stringifyContext(e.context), a = e.origin.length ? `[${e.origin.join(":")}] ` : "", o = `${n} ${r} ${a}`, c = this.multilineIndent(o.length, e.message), u = `${o}${c}${i ? " " + i : ""}
+`;
+    this.stream.write(u);
+  }
+  // { id: 123, type: 'article' } -> 'id=123 type="article"'
+  stringifyContext(e) {
+    return Object.entries(e).map(([n, r]) => `${n}=${JSON.stringify(r)}`).join(" ");
+  }
+  // Some messages will ruin your output without proper indentation. Stack
+  // traces are a good example of this.
+  //
+  // Supports Unix + DOS line endings.
+  multilineIndent(e, n) {
+    return n.replace(
+      /(\r?\n)/g,
+      (r) => r + " ".repeat(e)
+    );
+  }
+}
+const g = {
+  [s.Debug]: "DEBUG",
+  [s.Info]: "INFO ",
+  [s.Warn]: "WARN ",
+  [s.Error]: "ERROR"
+};
+export {
+  m as StreamBackend,
+  m as default
+};

package/dist/holz-stream-backend.umd.cjs

@@ -0,0 +1,2 @@
+(function(n,t){typeof exports=="object"&&typeof module<"u"?t(exports):typeof define=="function"&&define.amd?define(["exports"],t):(n=typeof globalThis<"u"?globalThis:n||self,t(n["holz-stream-backend"]={}))})(this,function(n){"use strict";var t=(r=>(r.Error="error",r.Warn="warn",r.Info="info",r.Debug="debug",r))(t||{});class s{constructor(e){this.stream=e.stream}processLog(e){const i=new Date().toISOString(),o=u[e.level],a=this.stringifyContext(e.context),d=e.origin.length?`[${e.origin.join(":")}] `:"",c=`${i} ${o} ${d}`,f=this.multilineIndent(c.length,e.message),l=`${c}${f}${a?" "+a:""}
+`;this.stream.write(l)}stringifyContext(e){return Object.entries(e).map(([i,o])=>`${i}=${JSON.stringify(o)}`).join(" ")}multilineIndent(e,i){return i.replace(/(\r?\n)/g,o=>o+" ".repeat(e))}}const u={[t.Debug]:"DEBUG",[t.Info]:"INFO ",[t.Warn]:"WARN ",[t.Error]:"ERROR"};n.StreamBackend=s,n.default=s,Object.defineProperties(n,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}})});

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@holz/stream-backend",
+  "version": "0.1.0",
+  "description": "Print logs to stdout or a file.",
+  "type": "module",
+  "main": "./dist/holz-stream-backend.umd.cjs",
+  "module": "./dist/holz-stream-backend.js",
+  "types": "./src/index.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/PsychoLlama/holz",
+    "directory": "packages/holz-stream-backend"
+  },
+  "exports": {
+    ".": {
+      "require": "./dist/holz-stream-backend.umd.cjs",
+      "import": "./dist/holz-stream-backend.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "Jesse Gibson",
+  "license": "MIT",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src"
+  ],
+  "keywords": [
+    "holz-backend",
+    "stream",
+    "file",
+    "stdout"
+  ],
+  "scripts": {
+    "prepare": "vite build",
+    "test:unit": "vitest --color --passWithNoTests",
+    "test:types": "tsc"
+  },
+  "devDependencies": {
+    "@holz/core": "0.1.0",
+    "@types/node": "^18.14.0",
+    "@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

@@ -0,0 +1,129 @@
+import { Writable } from 'node:stream';
+import { createLogger } from '@holz/core';
+import StreamBackend from '../stream-backend';
+
+const CURRENT_TIME = new Date('2020-06-15T12:00:00.000Z');
+
+describe('Stream backend', () => {
+  function createStream() {
+    let output = '';
+    const stream = new Writable({
+      write(chunk, _encoding, callback) {
+        output += String(chunk);
+        callback();
+      },
+    });
+
+    return {
+      getOutput: () => output,
+      stream,
+    };
+  }
+
+  beforeEach(() => {
+    vi.useFakeTimers({
+      now: CURRENT_TIME,
+    });
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('prints the logs to the writable stream', () => {
+    const { stream, getOutput } = createStream();
+    const backend = new StreamBackend({ stream });
+
+    const logger = createLogger(backend);
+    logger.debug('shout');
+    logger.info('normal');
+    logger.warn('hmmmm');
+    logger.error('oh no');
+
+    expect(getOutput()).toMatchInlineSnapshot(`
+      "2020-06-15T12:00:00.000Z DEBUG shout
+      2020-06-15T12:00:00.000Z INFO  normal
+      2020-06-15T12:00:00.000Z WARN  hmmmm
+      2020-06-15T12:00:00.000Z ERROR oh no
+      "
+    `);
+  });
+
+  it('includes the log namespace', () => {
+    const { stream, getOutput } = createStream();
+    const backend = new StreamBackend({ stream });
+    const logger = createLogger(backend)
+      .namespace('my-lib')
+      .namespace('MyClass');
+
+    logger.debug('initialized');
+
+    expect(getOutput()).toContain('[my-lib:MyClass]');
+  });
+
+  it('does not print the log namespace if it is empty', () => {
+    const { stream, getOutput } = createStream();
+    const backend = new StreamBackend({ stream });
+    const logger = createLogger(backend);
+
+    logger.debug('orphan log');
+
+    expect(getOutput()).not.toContain('[]');
+  });
+
+  it('includes the log context', () => {
+    const { stream, getOutput } = createStream();
+    const backend = new StreamBackend({ stream });
+    const logger = createLogger(backend);
+
+    logger.info('creating session', { sessionId: 3109, enabled: true });
+
+    expect(getOutput()).toContain('sessionId=3109');
+    expect(getOutput()).toContain('enabled=true');
+  });
+
+  it('includes the timestamp for each log', () => {
+    const { stream, getOutput } = createStream();
+    const backend = new StreamBackend({ stream });
+    const logger = createLogger(backend);
+
+    logger.info('traveling through time');
+
+    expect(getOutput()).toContain(CURRENT_TIME.toISOString());
+  });
+
+  it('wraps strings in log context with quotes', () => {
+    const { stream, getOutput } = createStream();
+    const backend = new StreamBackend({ stream });
+    const logger = createLogger(backend);
+
+    logger.info('creating session', { code: 'ENOBACON' });
+
+    expect(getOutput()).toContain('code="ENOBACON"');
+  });
+
+  it('joins arrays in log context', () => {
+    const { stream, getOutput } = createStream();
+    const backend = new StreamBackend({ stream });
+    const logger = createLogger(backend);
+
+    logger.info('adding tags', { tags: ['important', 'urgent'] });
+
+    expect(getOutput()).toContain('tags=["important","urgent"]');
+  });
+
+  it('indents multi-line log statements', () => {
+    const { stream, getOutput } = createStream();
+    const backend = new StreamBackend({ stream });
+    const logger = createLogger(backend);
+
+    logger.info('multi-line log\r\nwith a second line\nand a third line');
+
+    expect(getOutput()).toMatchInlineSnapshot(`
+      "2020-06-15T12:00:00.000Z INFO  multi-line log
+                                     with a second line
+                                     and a third line
+      "
+    `);
+  });
+});

package/src/index.ts

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

package/src/stream-backend.ts

@@ -0,0 +1,68 @@
+import type { Writable } from 'node:stream';
+import { LogLevel } from '@holz/core';
+import type { Log, LogContext, LogProcessor } from '@holz/core';
+
+/**
+ * Prints logs to a writable stream in plaintext. Optimized for log files.
+ *
+ * @example
+ * new StreamBackend({
+ *   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) {
+    const currentTime = new Date().toISOString();
+    const level = LOG_LEVELS[log.level];
+    const context = this.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 : ''}\n`;
+
+    // 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
+    // more logs, and if we buffered it would risk running out of memory and
+    // crashing the process.
+    //
+    // It is unlikely that a file or tty will apply backpressure in practice.
+    this.stream.write(output);
+  }
+
+  // { 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.
+  private multilineIndent(offset: number, message: string) {
+    return message.replace(
+      /(\r?\n)/g,
+      (newline) => newline + ' '.repeat(offset)
+    );
+  }
+}
+
+const LOG_LEVELS: Record<LogLevel, string> = {
+  [LogLevel.Debug]: 'DEBUG',
+  [LogLevel.Info]: 'INFO ',
+  [LogLevel.Warn]: 'WARN ',
+  [LogLevel.Error]: 'ERROR',
+};
+
+interface Config {
+  /** Where to print logs. Normally `process.stderr`. */
+  stream: Writable;
+}