@holz/stream-backend 0.9.1-rc.9 → 0.9.2-rc.0.sha-87f4046

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holz/stream-backend",
-  "version": "0.9.1-rc.9+7993ae6",
+  "version": "0.9.2-rc.0.sha-87f4046",
   "description": "Print logs to stdout or a file.",
   "type": "module",
   "repository": {
@@ -10,6 +10,7 @@
   },
   "exports": {
     ".": {
+      "source": "./src/index.ts",
       "types": "./dist/holz-stream-backend.d.ts",
       "require": "./dist/holz-stream-backend.cjs",
       "import": "./dist/holz-stream-backend.js"
@@ -22,7 +23,9 @@
   "license": "MIT",
   "sideEffects": false,
   "files": [
-    "dist"
+    "dist",
+    "src",
+    "!src/**/__tests__"
   ],
   "keywords": [
     "holz-backend",
@@ -37,18 +40,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.9+7993ae6",
+    "@holz/core": "^0.9.2-rc.0.sha-87f4046",
     "@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": "7993ae6757f530d908f8ce2fdd0654767dd3b595"
+  "gitHead": "87f40467fe9aa798fa894c04a208751403c45e8c"
 }

package/src/index.ts

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

package/src/stream-backend.ts

@@ -0,0 +1,70 @@
+import type { Writable } from 'node:stream';
+import { EOL } from 'node:os';
+import { inspect } from 'node:util';
+import {
+  level,
+  type LogLevel,
+  type Log,
+  type LogContext,
+  type LogProcessor,
+} from '@holz/core';
+
+/**
+ * Prints logs to a writable stream in plaintext. Optimized for log files.
+ *
+ * @example
+ * createStreamBackend({
+ *   stream: fs.createWriteStream('my-app.log', { flags: 'a' }),
+ * })
+ */
+export const createStreamBackend = ({ stream }: Config): LogProcessor => {
+  return (log: Log) => {
+    const { error, ...plainContext } = log.context;
+    const time = new Date(log.timestamp).toISOString();
+    const level = LOG_LEVELS[log.level];
+    const context = stringifyContext(plainContext);
+    const namespace = log.origin.length ? `[${log.origin.join(':')}] ` : '';
+
+    const header = `${time} ${level} ${namespace}`;
+    const message = multilineIndent(header.length, log.message);
+    const output = `${header}${message}${context ? ' ' + context : ''}`;
+    const errorMessage = error ? inspect(error, { colors: false }) + EOL : '';
+
+    // 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.
+    stream.write(`${output}${EOL}${errorMessage}`);
+  };
+};
+
+/**
+ * Some messages will ruin your output without proper indentation. Stack
+ * traces are a good example of this.
+ *
+ * Supports Unix + DOS line endings.
+ */
+const multilineIndent = (offset: number, message: string) =>
+  message.replace(/(\r?\n)/g, (newline) => newline + ' '.repeat(offset));
+
+// { id: 123, type: 'article' } -> 'id=123 type="article"'
+const stringifyContext = (context: LogContext) =>
+  Object.entries(context)
+    .map(([key, value]) => `${key}=${JSON.stringify(value)}`)
+    .join(' ');
+
+const LOG_LEVELS: Record<LogLevel, string> = {
+  [level.trace]: 'TRACE',
+  [level.debug]: 'DEBUG',
+  [level.info]: 'INFO ',
+  [level.warn]: 'WARN ',
+  [level.error]: 'ERROR',
+  [level.fatal]: 'FATAL',
+};
+
+interface Config {
+  /** Where to print logs. Normally `process.stderr`. */
+  stream: Writable;
+}