@holz/json-backend 0.9.1-rc.8 → 0.9.1

package/dist/holz-json-backend.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});var e={fatal:60,error:50,warn:40,info:30,debug:20,trace:10},t=({stream:e})=>t=>{let i=JSON.stringify({level:r[t.level],time:new Date(t.timestamp).toISOString(),msg:t.message,origin:t.origin,ctx:Object.keys(t.context).length>0?t.context:void 0},n);e.write(`${i}\n`)},n=(e,t)=>t instanceof Error?{...t,name:t.name,message:t.message,cause:t.cause,...t instanceof AggregateError&&{errors:t.errors}}:t,r=Object.fromEntries(Object.entries(e).map(([e,t])=>[t,e]));exports.createJsonBackend=t;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require("@holz/core");var t=({stream:e})=>t=>{let i=JSON.stringify({level:r[t.level],time:new Date(t.timestamp).toISOString(),msg:t.message,origin:t.origin,ctx:Object.keys(t.context).length>0?t.context:void 0},n);e.write(`${i}\n`)},n=(e,t)=>t instanceof Error?{...t,name:t.name,message:t.message,cause:t.cause,...t instanceof AggregateError&&{errors:t.errors}}:t,r=Object.fromEntries(Object.entries(e.level).map(([e,t])=>[t,e]));exports.createJsonBackend=t;

package/dist/holz-json-backend.js

@@ -1,12 +1,6 @@
-//#region ../holz-core/dist/holz-core.js
-var e = {
-	fatal: 60,
-	error: 50,
-	warn: 40,
-	info: 30,
-	debug: 20,
-	trace: 10
-}, t = ({ stream: e }) => (t) => {
+import { level as e } from "@holz/core";
+//#region src/json-backend.ts
+var t = ({ stream: e }) => (t) => {
 	let i = JSON.stringify({
 		level: r[t.level],
 		time: new Date(t.timestamp).toISOString(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holz/json-backend",
-  "version": "0.9.1-rc.8+6bcf3fb",
+  "version": "0.9.1",
   "description": "Print logs as newline-delimited JSON.",
   "type": "module",
   "repository": {
@@ -10,6 +10,7 @@
   },
   "exports": {
     ".": {
+      "source": "./src/index.ts",
       "types": "./dist/holz-json-backend.d.ts",
       "require": "./dist/holz-json-backend.cjs",
       "import": "./dist/holz-json-backend.js"
@@ -22,7 +23,9 @@
   "license": "MIT",
   "sideEffects": false,
   "files": [
-    "dist"
+    "dist",
+    "src",
+    "!src/**/__tests__"
   ],
   "keywords": [
     "holz-backend",
@@ -36,16 +39,19 @@
     "test:coverage": "vitest run --coverage --color --passWithNoTests",
     "test:types": "tsc"
   },
+  "peerDependencies": {
+    "@holz/core": "^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/index.ts

@@ -0,0 +1 @@
+export { createJsonBackend } from './json-backend';

package/src/json-backend.ts

@@ -0,0 +1,73 @@
+import type { Writable } from 'node:stream';
+import { level, type LogLevel, type Log, type LogProcessor } from '@holz/core';
+
+/**
+ * Prints structured logs to a writable stream in NDJSON form. Optimized for
+ * log files.
+ *
+ * @example
+ * createJsonBackend({
+ *   stream: fs.createWriteStream('my-app.log', { flags: 'a' }),
+ * })
+ *
+ * @see https://github.com/ndjson/ndjson-spec
+ */
+export const createJsonBackend = ({ stream }: Config): LogProcessor => {
+  return (log: Log) => {
+    // Follow the order of typical log statements. Be kind to the human
+    // reader.
+    const output = JSON.stringify(
+      {
+        level: labelForLevel[log.level],
+        time: new Date(log.timestamp).toISOString(),
+        msg: log.message,
+        origin: log.origin,
+        ctx: Object.keys(log.context).length > 0 ? log.context : undefined,
+      },
+      errorSerializer,
+    );
+
+    // 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}\n`);
+  };
+};
+
+/**
+ * Errors are not JSON serializable, but errors are naturally a crucial aspect
+ * of any logging system. This unwraps errors into a JSON representation.
+ */
+const errorSerializer = (_key: string, value: unknown) => {
+  if (value instanceof Error) {
+    return {
+      ...value, // Some custom errors have important custom properties.
+      name: value.name,
+      message: value.message,
+      cause: value.cause,
+      // `AggregateError` collects its constituent failures in a
+      // non-enumerable `errors` array that the spread above misses. Pull it
+      // explicitly so those underlying errors survive serialization; the
+      // replacer recurses into each one.
+      ...(value instanceof AggregateError && { errors: value.errors }),
+    };
+  }
+
+  return value;
+};
+
+/**
+ * Slightly heavier than logging the number, but easier to process
+ * programmatically which is somewhat implied by a JSON backend.
+ */
+const labelForLevel = Object.fromEntries(
+  Object.entries(level).map(([key, value]) => [value, key]),
+) as Record<LogLevel, string>;
+
+interface Config {
+  /** Where to print logs. */
+  stream: Writable;
+}