@holz/ansi-terminal-backend 0.4.0 → 0.6.0

package/README.md

@@ -0,0 +1,28 @@
+# `@holz/ansi-terminal-backend`
+
+Pretty-print logs to the terminal.
+
+<img alt="Screenshot of logs printed to the terminal" src="https://user-images.githubusercontent.com/10053423/222926680-0a12da0c-5ff2-40a1-8759-5dca72eb89c3.png" width="600" />
+
+## Usage
+
+```typescript
+import { createAnsiTerminalBackend } from '@holz/ansi-terminal-backend';
+
+const logger = createLogger(createAnsiTerminalBackend());
+```
+
+> **Note**  
+> There is no way to disable colors. The output relies on colors to convey structure. To disable colors, use a different backend such as [`@holz/stream-backend`](https://github.com/PsychoLlama/holz/tree/main/packages/holz-stream-backend).
+
+## Options
+
+```typescript
+createAnsiTerminalBackend({
+  /**
+   * By default it prints to the global console, but you can override it.
+   * See: https://nodejs.org/api/console.html#new-consoleoptions
+   */
+  console: new Console(custom.stdout, custom.stderr),
+});
+```

package/dist/holz-ansi-terminal-backend.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const c=require("@holz/core");function n(l){return`\x1B[${l}`}const t=n("0m"),a=n("2m"),d=n("31m"),g=n("32m"),$=n("33m"),p=n("34m");class u{constructor(e={}){this.console=e.console??console}processLog(e){const r=this.getTimestamp(new Date),s=[{include:!0,command:"%s",content:`${t}${a}${r}${t}`},{include:!0,command:"%s",content:L[e.level]},{include:!0,command:"%s",content:e.message},{include:e.origin.length>0,command:"%s",content:`${a}${e.origin.join(":")}${t}`},{include:Object.keys(e.context).length>0,command:"%O",content:e.context}].filter(o=>o.include),i=s.map(o=>o.command).join(" "),m=s.map(o=>o.content);this.console.error(i,...m)}getTimestamp(e){const r=e.getHours().toString().padStart(2,"0"),s=e.getMinutes().toString().padStart(2,"0"),i=e.getSeconds().toString().padStart(2,"0"),m=e.getMilliseconds().toString().padStart(3,"0");return`[${r}:${s}:${i}.${m}]`}}const L={[c.LogLevel.Debug]:`${p}DEBUG${t}`,[c.LogLevel.Info]:`${g}INFO${t} `,[c.LogLevel.Warn]:`${$}WARN${t} `,[c.LogLevel.Error]:`${d}ERROR${t}`};exports.AnsiTerminalBackend=u;exports.default=u;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const s=require("@holz/core");function o(e){return`\x1B[${e}`}const n=o("0m"),u=o("2m"),g=o("31m"),p=o("32m"),L=o("33m"),S=o("34m");function f(e={}){const r=e.console??console,i=" ".repeat(s.LogLevel.Error.length);return t=>{const a=v(new Date),m=`${n}${u}${a}${n}`,l=[{include:!0,command:"%s",content:m},{include:!0,command:"%s",content:b[t.level]},{include:!0,command:"%s",content:t.message.replace(/(\r?\n)/g,`$1${m} ${i} `)},{include:Object.keys(t.context).length>0,command:"%O",content:t.context},{include:t.origin.length>0,command:"%s",content:`${u}${t.origin.join(":")}${n}`}].filter(c=>c.include),d=l.map(c=>c.command).join(" "),$=l.map(c=>c.content);r.error(d,...$)}}function v(e){const r=e.getHours().toString().padStart(2,"0"),i=e.getMinutes().toString().padStart(2,"0"),t=e.getSeconds().toString().padStart(2,"0"),a=e.getMilliseconds().toString().padStart(3,"0");return`[${r}:${i}:${t}.${a}]`}const b={[s.LogLevel.Debug]:`${S}DEBUG${n}`,[s.LogLevel.Info]:`${p}INFO${n} `,[s.LogLevel.Warn]:`${L}WARN${n} `,[s.LogLevel.Error]:`${g}ERROR${n}`};exports.createAnsiTerminalBackend=f;

package/dist/holz-ansi-terminal-backend.js

@@ -1,55 +1,54 @@
-import { LogLevel as c } from "@holz/core";
-function e(a) {
-  return `\x1B[${a}`;
+import { LogLevel as s } from "@holz/core";
+function o(t) {
+  return `\x1B[${t}`;
 }
-const n = e("0m"), l = e("2m"), d = e("31m"), u = e("32m"), $ = e("33m"), g = e("34m");
-class f {
-  constructor(t = {}) {
-    this.console = t.console ?? console;
-  }
-  processLog(t) {
-    const r = this.getTimestamp(new Date()), s = [
+const e = o("0m"), u = o("2m"), g = o("31m"), p = o("32m"), S = o("33m"), f = o("34m");
+function v(t = {}) {
+  const r = t.console ?? console, i = " ".repeat(s.Error.length);
+  return (n) => {
+    const m = b(new Date()), a = `${e}${u}${m}${e}`, l = [
       {
         include: !0,
         command: "%s",
-        content: `${n}${l}${r}${n}`
+        content: a
       },
       {
         include: !0,
         command: "%s",
-        content: p[t.level]
+        content: h[n.level]
       },
       {
         include: !0,
         command: "%s",
-        content: t.message
+        content: n.message.replace(
+          /(\r?\n)/g,
+          `$1${a} ${i} `
+        )
       },
       {
-        include: t.origin.length > 0,
-        command: "%s",
-        content: `${l}${t.origin.join(":")}${n}`
+        include: Object.keys(n.context).length > 0,
+        command: "%O",
+        content: n.context
       },
       {
-        include: Object.keys(t.context).length > 0,
-        command: "%O",
-        content: t.context
+        include: n.origin.length > 0,
+        command: "%s",
+        content: `${u}${n.origin.join(":")}${e}`
       }
-    ].filter((o) => o.include), i = s.map((o) => o.command).join(" "), m = s.map((o) => o.content);
-    this.console.error(i, ...m);
-  }
-  // ISO-8601 timestamp with milliseconds.
-  getTimestamp(t) {
-    const r = t.getHours().toString().padStart(2, "0"), s = t.getMinutes().toString().padStart(2, "0"), i = t.getSeconds().toString().padStart(2, "0"), m = t.getMilliseconds().toString().padStart(3, "0");
-    return `[${r}:${s}:${i}.${m}]`;
-  }
+    ].filter((c) => c.include), $ = l.map((c) => c.command).join(" "), d = l.map((c) => c.content);
+    r.error($, ...d);
+  };
+}
+function b(t) {
+  const r = t.getHours().toString().padStart(2, "0"), i = t.getMinutes().toString().padStart(2, "0"), n = t.getSeconds().toString().padStart(2, "0"), m = t.getMilliseconds().toString().padStart(3, "0");
+  return `[${r}:${i}:${n}.${m}]`;
 }
-const p = {
-  [c.Debug]: `${g}DEBUG${n}`,
-  [c.Info]: `${u}INFO${n} `,
-  [c.Warn]: `${$}WARN${n} `,
-  [c.Error]: `${d}ERROR${n}`
+const h = {
+  [s.Debug]: `${f}DEBUG${e}`,
+  [s.Info]: `${p}INFO${e} `,
+  [s.Warn]: `${S}WARN${e} `,
+  [s.Error]: `${g}ERROR${e}`
 };
 export {
-  f as AnsiTerminalBackend,
-  f as default
+  v as createAnsiTerminalBackend
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holz/ansi-terminal-backend",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "An ANSI terminal backend for Holz",
   "type": "module",
   "main": "./dist/holz-ansi-terminal-backend.cjs",
@@ -38,13 +38,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__/ansi-terminal-backend.test.ts

@@ -1,24 +1,42 @@
-import { format } from 'util';
+import { Writable } from 'node:stream';
+import { Console } from 'node:console';
 import { createLogger } from '@holz/core';
-import type { MinimalConsole } from '../ansi-terminal-backend';
-import AnsiTerminalBackend from '../ansi-terminal-backend';
+import { createAnsiTerminalBackend } from '../ansi-terminal-backend';
 
 const CURRENT_TIME = new Date('2020-06-15T03:05:07.010Z');
 
-class MockConsole implements MinimalConsole {
-  log(...strings: Array<unknown>) {
-    this.stdout(format(...strings));
-  }
+describe('ANSI terminal backend', () => {
+  function createStream() {
+    let output = '';
+    const stream = new Writable({
+      write(chunk, _encoding, callback) {
+        output += String(chunk);
+        callback();
+      },
+    });
 
-  error(...strings: Array<unknown>) {
-    this.stderr(format(...strings));
+    return {
+      getOutput: () => output,
+      stream,
+    };
   }
 
-  stdout = vi.fn();
-  stderr = vi.fn();
-}
+  // Named "terminal" to avoid conflict with `global.console`.
+  function createTerminal() {
+    const stdout = createStream();
+    const stderr = createStream();
+    const terminal = new Console({
+      stdout: stdout.stream,
+      stderr: stderr.stream,
+    });
+
+    return {
+      stdout,
+      stderr,
+      terminal,
+    };
+  }
 
-describe('ANSI terminal backend', () => {
   beforeEach(() => {
     vi.useFakeTimers({
       now: CURRENT_TIME,
@@ -30,20 +48,18 @@ describe('ANSI terminal backend', () => {
   });
 
   it('prints the message to the terminal', () => {
-    const terminal = new MockConsole();
-    const backend = new AnsiTerminalBackend({ console: terminal });
+    const { terminal, stderr } = createTerminal();
+    const backend = createAnsiTerminalBackend({ console: terminal });
 
     const logger = createLogger(backend);
     logger.info('hello world');
 
-    expect(terminal.stderr).toHaveBeenCalledWith(
-      expect.stringContaining('hello world')
-    );
+    expect(stderr.getOutput()).toContain('hello world');
   });
 
   it('includes the log level', () => {
-    const terminal = new MockConsole();
-    const backend = new AnsiTerminalBackend({ console: terminal });
+    const { terminal, stderr } = createTerminal();
+    const backend = createAnsiTerminalBackend({ console: terminal });
 
     const logger = createLogger(backend);
     logger.debug('shout');
@@ -51,68 +67,56 @@ describe('ANSI terminal backend', () => {
     logger.warn('hmmmm');
     logger.error('oh no');
 
-    expect(terminal.stderr).toHaveBeenCalledWith(
-      expect.stringContaining('DEBUG')
-    );
-
-    expect(terminal.stderr).toHaveBeenCalledWith(
-      expect.stringContaining('INFO')
-    );
-
-    expect(terminal.stderr).toHaveBeenCalledWith(
-      expect.stringContaining('WARN')
-    );
-
-    expect(terminal.stderr).toHaveBeenCalledWith(
-      expect.stringContaining('ERROR')
-    );
+    expect(stderr.getOutput()).toContain('DEBUG');
+    expect(stderr.getOutput()).toContain('INFO');
+    expect(stderr.getOutput()).toContain('WARN');
+    expect(stderr.getOutput()).toContain('ERROR');
   });
 
   it('includes the log namespace', () => {
-    const terminal = new MockConsole();
-    const backend = new AnsiTerminalBackend({ console: terminal });
+    const { terminal, stderr } = createTerminal();
+    const backend = createAnsiTerminalBackend({ console: terminal });
     const logger = createLogger(backend)
       .namespace('my-lib')
       .namespace('MyClass');
 
     logger.debug('initialized');
 
-    expect(terminal.stderr).toHaveBeenCalledWith(
-      expect.stringContaining('my-lib:MyClass')
-    );
+    expect(stderr.getOutput()).toContain('my-lib:MyClass');
   });
 
   it('includes the log context', () => {
-    const terminal = new MockConsole();
-    const backend = new AnsiTerminalBackend({ console: terminal });
+    const { terminal, stderr } = createTerminal();
+    const backend = createAnsiTerminalBackend({ console: terminal });
     const logger = createLogger(backend);
 
     logger.info('creating session', { sessionId: 3109 });
 
     // Hard to test without replicating the implementation.
-    expect(terminal.stderr).toHaveBeenCalledWith(
-      expect.stringContaining('sessionId')
-    );
-
-    expect(terminal.stderr).toHaveBeenCalledWith(
-      expect.stringContaining('3109')
-    );
+    expect(stderr.getOutput()).toContain('sessionId');
+    expect(stderr.getOutput()).toContain('3109');
   });
 
   it('does not include the log context if it is empty', () => {
-    const terminal = new MockConsole();
-    const backend = new AnsiTerminalBackend({ console: terminal });
+    const { terminal, stderr } = createTerminal();
+    const backend = createAnsiTerminalBackend({ console: terminal });
     const logger = createLogger(backend);
 
     logger.warn('activating death ray', {});
 
     // Hard to test without replicating the implementation.
-    expect(terminal.stderr).not.toHaveBeenCalledWith(
-      expect.stringContaining('{')
-    );
+    expect(stderr.getOutput()).not.toContain('{');
+    expect(stderr.getOutput()).not.toContain('}');
+  });
+
+  it('indents multiline strings', () => {
+    const { terminal, stderr } = createTerminal();
+    const backend = createAnsiTerminalBackend({ console: terminal });
+    const logger = createLogger(backend);
+
+    logger.info('This is a multiline string.\nIt has two lines.');
 
-    expect(terminal.stderr).not.toHaveBeenCalledWith(
-      expect.stringContaining('}')
-    );
+    expect(stderr.getOutput()).toContain('This is a multiline string.');
+    expect(stderr.getOutput()).toContain('  It has two lines.');
   });
 });

package/src/ansi-terminal-backend.ts

@@ -11,20 +11,18 @@ import * as ansi from './ansi-codes';
  * ques, the printed text is much less understandable. It is better to check
  * when constructing the logger instead.
  */
-export default class AnsiTerminalBackend implements LogProcessor {
-  private console: MinimalConsole;
+export function createAnsiTerminalBackend(options: Options = {}): LogProcessor {
+  const output = options.console ?? console;
+  const labelSizeInWhitespace = ' '.repeat(LogLevel.Error.length);
 
-  constructor(options: Options = {}) {
-    this.console = options.console ?? console;
-  }
-
-  processLog(log: Log) {
-    const timestamp = this.getTimestamp(new Date());
+  return (log: Log) => {
+    const timestamp = formatAsTimestamp(new Date());
+    const timestampPrefix = `${ansi.reset}${ansi.dim}${timestamp}${ansi.reset}`;
     const segments = [
       {
         include: true,
         command: '%s',
-        content: `${ansi.reset}${ansi.dim}${timestamp}${ansi.reset}`,
+        content: timestampPrefix,
       },
       {
         include: true,
@@ -34,36 +32,39 @@ export default class AnsiTerminalBackend implements LogProcessor {
       {
         include: true,
         command: '%s',
-        content: log.message,
-      },
-      {
-        include: log.origin.length > 0,
-        command: '%s',
-        content: `${ansi.dim}${log.origin.join(':')}${ansi.reset}`,
+        content: log.message.replace(
+          /(\r?\n)/g,
+          `$1${timestampPrefix} ${labelSizeInWhitespace} `
+        ),
       },
       {
         include: Object.keys(log.context).length > 0,
         command: '%O',
         content: log.context,
       },
+      {
+        include: log.origin.length > 0,
+        command: '%s',
+        content: `${ansi.dim}${log.origin.join(':')}${ansi.reset}`,
+      },
     ].filter((segment) => segment.include);
 
     const format = segments.map((segment) => segment.command).join(' ');
     const values = segments.map((segment) => segment.content);
 
     // CLIs typically print interactive messages to stdout and logs to stderr.
-    this.console.error(format, ...values);
-  }
+    output.error(format, ...values);
+  };
+}
 
-  // ISO-8601 timestamp with milliseconds.
-  private getTimestamp(date: Date) {
-    const hours = date.getHours().toString().padStart(2, '0');
-    const minutes = date.getMinutes().toString().padStart(2, '0');
-    const seconds = date.getSeconds().toString().padStart(2, '0');
-    const milliseconds = date.getMilliseconds().toString().padStart(3, '0');
+// ISO-8601 timestamp with milliseconds.
+function formatAsTimestamp(date: Date) {
+  const hours = date.getHours().toString().padStart(2, '0');
+  const minutes = date.getMinutes().toString().padStart(2, '0');
+  const seconds = date.getSeconds().toString().padStart(2, '0');
+  const milliseconds = date.getMilliseconds().toString().padStart(3, '0');
 
-    return `[${hours}:${minutes}:${seconds}.${milliseconds}]`;
-  }
+  return `[${hours}:${minutes}:${seconds}.${milliseconds}]`;
 }
 
 // Trailing whitespace is important for alignment.
@@ -75,11 +76,11 @@ const logLevelLabel: Record<LogLevel, string> = {
 };
 
 interface Options {
-  console?: MinimalConsole;
+  /**
+   * Defaults the global `console`, but in NodeJS you can create a console
+   * over any writable stream. It could be a file or a network socket.
+   *
+   * @see https://nodejs.org/api/console.html#new-consoleoptions
+   */
+  console?: Console;
 }
-
-/**
- * A subset of the Console interface. Must support printf-style interpolation.
- * @see https://console.spec.whatwg.org/#formatting-specifiers
- */
-export type MinimalConsole = Pick<Console, 'log' | 'error'>;

package/src/index.ts

@@ -1,4 +1 @@
-export {
-  default,
-  default as AnsiTerminalBackend,
-} from './ansi-terminal-backend';
+export { createAnsiTerminalBackend } from './ansi-terminal-backend';