@holz/json-backend 0.7.0 → 0.8.0-rc.2

package/README.md

@@ -12,7 +12,7 @@ import * as fs from 'node:fs';
 const logger = createLogger(
   createJsonBackend({
     stream: fs.createWriteStream('my-app.log', { flags: 'a' }),
-  })
+  }),
 );
 ```
 

package/dist/holz-json-backend.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const c=require("node:os");function r({stream:t}){return e=>{const n=JSON.stringify({level:e.level,time:new Date().toISOString(),msg:e.message,ctx:Object.keys(e.context).length>0?e.context:void 0});t.write(`${n}${c.EOL}`)}}exports.createJsonBackend=r;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const n=require("node:os"),s={fatal:60,error:50,warn:40,info:30,debug:20,trace:10},c=({stream:t})=>e=>{const r=JSON.stringify({level:a[e.level],time:new Date(e.timestamp).toISOString(),msg:e.message,ctx:Object.keys(e.context).length>0?e.context:void 0},o);t.write(`${r}${n.EOL}`)},o=(t,e)=>e instanceof Error?{...e,name:e.name,message:e.message,cause:e.cause}:e,a=Object.fromEntries(Object.entries(s).map(([t,e])=>[e,t]));exports.createJsonBackend=c;

package/dist/holz-json-backend.d.ts

@@ -17,6 +17,6 @@ declare interface Config {
  *
  * @see http://ndjson.org
  */
-export declare function createJsonBackend({ stream }: Config): LogProcessor;
+export declare const createJsonBackend: ({ stream }: Config) => LogProcessor;
 
 export { }

package/dist/holz-json-backend.js

@@ -1,15 +1,37 @@
-import { EOL as r } from "node:os";
-function i({ stream: t }) {
-  return (e) => {
-    const n = JSON.stringify({
-      level: e.level,
-      time: (/* @__PURE__ */ new Date()).toISOString(),
+import { EOL as n } from "node:os";
+const s = {
+  /** A critical failure happened and the program must exit. */
+  fatal: 60,
+  /** Something failed, but we can keep going. */
+  error: 50,
+  /** Cause for concern, but we can keep going. */
+  warn: 40,
+  /** High-level progress updates. */
+  info: 30,
+  /** Verbose update about events or control flow (usually hidden). */
+  debug: 20,
+  /** Extremely detailed progress updates (usually hidden). */
+  trace: 10
+}, i = ({ stream: t }) => (e) => {
+  const r = JSON.stringify(
+    {
+      level: o[e.level],
+      time: new Date(e.timestamp).toISOString(),
       msg: e.message,
       ctx: Object.keys(e.context).length > 0 ? e.context : void 0
-    });
-    t.write(`${n}${r}`);
-  };
-}
+    },
+    c
+  );
+  t.write(`${r}${n}`);
+}, c = (t, e) => e instanceof Error ? {
+  ...e,
+  // Some custom errors have important custom properties.
+  name: e.name,
+  message: e.message,
+  cause: e.cause
+} : e, o = Object.fromEntries(
+  Object.entries(s).map(([t, e]) => [e, t])
+);
 export {
   i as createJsonBackend
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holz/json-backend",
-  "version": "0.7.0",
+  "version": "0.8.0-rc.2",
   "description": "Print logs as newline-delimited JSON.",
   "type": "module",
   "repository": {
@@ -37,13 +37,14 @@
     "test:types": "tsc"
   },
   "devDependencies": {
-    "@holz/core": "^0.7.0",
+    "@holz/core": "^0.8.0-rc.2",
     "@types/node": "^22.0.0",
     "@vitest/coverage-v8": "^3.0.8",
-    "typescript": "^5.0.0",
+    "typescript": "^5.8.2",
     "vite": "^6.0.0",
     "vite-plugin-dts": "^4.5.3",
     "vite-tsconfig-paths": "^5.1.4",
     "vitest": "^3.0.8"
-  }
+  },
+  "stableVersion": "0.7.0"
 }

package/src/__tests__/json-backend.test.ts

@@ -5,7 +5,7 @@ import { createJsonBackend } from '../json-backend';
 const CURRENT_TIME = new Date('2020-06-15T12:00:00.000Z');
 
 describe('JSON backend', () => {
-  function createStream() {
+  const createStream = () => {
     let output = '';
     const stream = new Writable({
       write(chunk, _encoding, callback) {
@@ -18,7 +18,7 @@ describe('JSON backend', () => {
       getOutput: () => output,
       stream,
     };
-  }
+  };
 
   beforeEach(() => {
     vi.useFakeTimers({
@@ -64,4 +64,54 @@ describe('JSON backend', () => {
 
     expect(getOutput()).toContain('"reqId":"abc"');
   });
+
+  it('pulls structure from errors', () => {
+    const { stream, getOutput } = createStream();
+    const backend = createJsonBackend({ stream });
+    const logger = createLogger(backend);
+
+    logger.error('content', {
+      error: new RangeError('Testing NDJSON errors'),
+    });
+
+    const output = getOutput();
+    expect(output).toContain(
+      '"error":{"name":"RangeError","message":"Testing NDJSON errors"}',
+    );
+  });
+
+  it('detects and includes error causes', () => {
+    const { stream, getOutput } = createStream();
+    const backend = createJsonBackend({ stream });
+    const logger = createLogger(backend);
+
+    logger.error('content', {
+      error: new Error('Testing NDJSON errors', {
+        cause: new Error('Cause'),
+      }),
+    });
+
+    const output = getOutput();
+    expect(output).toContain(
+      '"error":{"name":"Error","message":"Testing NDJSON errors","cause":{"name":"Error","message":"Cause"}}',
+    );
+  });
+
+  it('includes any enumerable properties on the object', () => {
+    class CustomError extends Error {
+      name = 'CustomError';
+      status = 418;
+    }
+
+    const { stream, getOutput } = createStream();
+    const backend = createJsonBackend({ stream });
+    const logger = createLogger(backend);
+
+    logger.error('content', {
+      error: new CustomError('Testing NDJSON errors'),
+    });
+
+    const output = getOutput();
+    expect(output).toContain('"status":418');
+  });
 });

package/src/json-backend.ts

@@ -1,6 +1,6 @@
 import type { Writable } from 'node:stream';
 import { EOL } from 'node:os';
-import type { Log, LogProcessor } from '@holz/core';
+import { level, type LogLevel, type Log, type LogProcessor } from '@holz/core';
 
 /**
  * Prints structured logs to a writable stream in NDJSON form. Optimized for
@@ -13,16 +13,19 @@ import type { Log, LogProcessor } from '@holz/core';
  *
  * @see http://ndjson.org
  */
-export function createJsonBackend({ stream }: Config): LogProcessor {
+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: log.level,
-      time: new Date().toISOString(),
-      msg: log.message,
-      ctx: Object.keys(log.context).length > 0 ? log.context : undefined,
-    });
+    const output = JSON.stringify(
+      {
+        level: labelForLevel[log.level],
+        time: new Date(log.timestamp).toISOString(),
+        msg: log.message,
+        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
@@ -32,7 +35,32 @@ export function createJsonBackend({ stream }: Config): LogProcessor {
     // It is unlikely that a file or tty will apply backpressure in practice.
     stream.write(`${output}${EOL}`);
   };
-}
+};
+
+/**
+ * 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,
+    };
+  }
+
+  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. */