@holz/ansi-terminal-backend 0.9.1-rc.8 → 0.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holz/ansi-terminal-backend",
-  "version": "0.9.1-rc.8+6bcf3fb",
+  "version": "0.9.1",
   "description": "An ANSI terminal backend for Holz",
   "type": "module",
   "repository": {
@@ -10,6 +10,7 @@
   },
   "exports": {
     ".": {
+      "source": "./src/index.ts",
       "types": "./dist/holz-ansi-terminal-backend.d.ts",
       "require": "./dist/holz-ansi-terminal-backend.cjs",
       "import": "./dist/holz-ansi-terminal-backend.js"
@@ -22,7 +23,9 @@
   "license": "MIT",
   "sideEffects": false,
   "files": [
-    "dist"
+    "dist",
+    "src",
+    "!src/**/__tests__"
   ],
   "keywords": [
     "holz-backend",
@@ -36,18 +39,18 @@
     "test:types": "tsc"
   },
   "peerDependencies": {
-    "@holz/core": "^0.8.0"
+    "@holz/core": "^0.8.0 || ^0.9.0"
   },
   "devDependencies": {
-    "@holz/core": "^0.9.1-rc.8+6bcf3fb",
+    "@holz/core": "^0.9.1",
     "@microsoft/api-extractor": "^7.58.8",
     "@types/node": "^24.0.0",
-    "@vitest/coverage-v8": "^4.0.0",
+    "@vitest/coverage-v8": "^5.0.0",
     "typescript": "^6.0.0",
     "vite": "^8.0.0",
     "vite-plugin-dts": "^5.0.0",
     "vite-tsconfig-paths": "^6.0.0",
-    "vitest": "^4.0.0"
+    "vitest": "^5.0.0"
   },
-  "gitHead": "6bcf3fbc31a0cb3597e62832bfa672535fcaa144"
+  "gitHead": "87f40467fe9aa798fa894c04a208751403c45e8c"
 }

package/src/ansi-codes.ts

@@ -0,0 +1,16 @@
+const ansiCode = (code: string) => `\x1b[${code}`;
+
+/**
+ * Assumes 3-bit color support for an ANSI terminal. This should work on most
+ * modern terminals, including on Windows.
+ */
+
+export const reset = ansiCode('0m');
+export const bold = ansiCode('1m');
+export const dim = ansiCode('2m');
+
+export const red = ansiCode('31m');
+export const green = ansiCode('32m');
+export const yellow = ansiCode('33m');
+export const blue = ansiCode('34m');
+export const brightWhite = ansiCode('97m');

package/src/ansi-terminal-backend.ts

@@ -0,0 +1,90 @@
+import { level, type LogLevel, type Log, type LogProcessor } from '@holz/core';
+import * as ansi from './ansi-codes';
+
+/**
+ * A backend that prints logs to a 3-bit ansi terminal. This should work on
+ * most Unix systems and Windows >= 10.
+ *
+ * NOTE: This is not smart enough to detect if the output is a TTY or if it
+ * supports colors, nor is this the appropriate place to check. Without color
+ * ques, the printed text is much less understandable. It is better to check
+ * when constructing the logger instead.
+ */
+export const createAnsiTerminalBackend = (
+  options: Options = {},
+): LogProcessor => {
+  const output = options.console ?? console;
+  const labelSizeInWhitespace = ' '.repeat(5); // char length of longest level type
+
+  return (log: Log) => {
+    const timestamp = formatAsTimestamp(new Date(log.timestamp));
+    const timestampPrefix = `${ansi.reset}${ansi.dim}${timestamp}${ansi.reset}`;
+    const segments = [
+      {
+        include: true,
+        command: '%s',
+        content: timestampPrefix,
+      },
+      {
+        include: true,
+        command: '%s',
+        content: logLevelLabel[log.level],
+      },
+      {
+        include: true,
+        command: '%s',
+        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.
+    output.error(format, ...values);
+  };
+};
+
+// This is an interactive TTY, so we can assume someone is watching. They
+// probably know what day it is. Focus on the time.
+const 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}]`;
+};
+
+// Trailing whitespace is important for alignment.
+const logLevelLabel: Record<LogLevel, string> = {
+  [level.trace]: `${ansi.brightWhite}TRACE${ansi.reset}`,
+  [level.debug]: `${ansi.blue}DEBUG${ansi.reset}`,
+  [level.info]: `${ansi.green}INFO${ansi.reset} `,
+  [level.warn]: `${ansi.yellow}WARN${ansi.reset} `,
+  [level.error]: `${ansi.red}ERROR${ansi.reset}`,
+  [level.fatal]: `${ansi.bold}${ansi.red}FATAL${ansi.reset}`,
+};
+
+interface Options {
+  /**
+   * 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;
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { createAnsiTerminalBackend } from './ansi-terminal-backend';