@holz/json-backend 0.8.2 → 0.8.3-rc.154

package/README.md

@@ -1,21 +1,66 @@
 # `@holz/json-backend`
 
-Prints structured logs to a writable stream in NDJSON form.
+Serializes structured logs to a writable stream in [NDJSON](https://github.com/ndjson/ndjson-spec) format.
 
 ## Usage
 
+This backend serializes logs into a [`WritableStream<Uint8Array>`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream). Each chunk is UTF-8 encoded. Ideal for append-only log files.
+
+Target environments are servers, host endpoints, and browsers (via [OPFS](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemFileHandle/createWritable)).
+
 ```typescript
 import { createJsonBackend } from '@holz/json-backend';
 import { createLogger } from '@holz/core';
-import * as fs from 'node:fs';
 
 const logger = createLogger(
   createJsonBackend({
-    stream: fs.createWriteStream('my-app.log', { flags: 'a' }),
+    stream: new WritableStream<Uint8Array>(
+      {
+        // ...
+      },
+      new CountQueuingStrategy({
+        highWaterMark: 1024,
+      }),
+    ),
   }),
 );
 ```
 
-Logs are output in [NDJSON](http://ndjson.org/) format. The output is optimized for log files, following the order of typical log statements. The output includes the log level, timestamp, message, and context, if provided.
+### Node Streams
+
+Node's streams shipped long before the web standard and need to be wrapped with [Writable.toWeb](https://nodejs.org/api/stream.html#streamwritabletowebstreamwritable):
+
+```typescript
+import { createWriteStream } from 'node:fs';
+import { Writable } from 'node:stream';
+
+createJsonBackend({
+  stream: Writable.toWeb(createWriteStream('logs.ndjson', { flags: 'a' })),
+}),
+```
+
+The same adapter works for any Node writable, including `process.stderr`.
+
+### Closing the Stream
+
+By default, the stream remains open forever. Pass an [AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) to control the shutdown.
+
+```typescript
+const controller = new AbortController();
+
+createJsonBackend({
+  stream: writableStream,
+  signal: controller.signal,
+});
+
+// Permanently close the writable stream.
+controller.abort();
+```
+
+Tap the stream's [close](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream/WritableStream#closecontroller) handler or node's [finish](https://nodejs.org/api/fs.html#event-finish) event for a clean shutdown.
+
+## Caveats
 
-The `stream` option specifies where the logs will be written to. You can use any writable stream, such as a file or `process.stdout`.
+- Writes are fire-and-forget. Stream backpressure from an overwhelmed sink will cause logs to be dropped. Use [CountQueuingStrategy](https://developer.mozilla.org/en-US/docs/Web/API/CountQueuingStrategy) to adjust the log buffer.
+- Long-running processes and noisy services create giant files. Lean on your environment's tools (`journalctl`) or use a package like [rotating-file-stream](https://github.com/iccicci/rotating-file-stream).
+- OPFS streams in browser environments have poor durability. You may need synchronous access to periodically flush writes, an API only available in workers.

package/dist/holz-json-backend.cjs

@@ -1 +1 @@
-"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;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});var e={fatal:60,error:50,warn:40,info:30,debug:20,trace:10},t=(n,r)=>{let i=(e,t,i={})=>{n({timestamp:Date.now(),message:t,level:e,origin:r,context:i})},a={owner:r,trace:i.bind(null,e.trace),debug:i.bind(null,e.debug),info:i.bind(null,e.info),warn:i.bind(null,e.warn),error:i.bind(null,e.error),fatal:i.bind(null,e.fatal),namespace:e=>t(n,r.concat(e)),withMiddleware:e=>t(e(n),r)},o={configurable:!1,enumerable:!1};return Object.defineProperties(a,{withMiddleware:o,namespace:o,trace:o,debug:o,info:o,warn:o,error:o,fatal:o})},n=new TextEncoder,r=({stream:e,signal:t})=>{let r=e.getWriter();return t?.aborted?r.close().catch(i):t?.addEventListener(`abort`,()=>void r.close().catch(i),{once:!0}),e=>{if(r.desiredSize===null||r.desiredSize<=0)return;let t=JSON.stringify({level:o[e.level],time:new Date(e.timestamp).toISOString(),msg:e.message,origin:e.origin,ctx:Object.keys(e.context).length>0?e.context:void 0},a);r.write(n.encode(`${t}\n`)).catch(i)}},i=()=>{},a=(e,t)=>t instanceof Error?{...t,name:t.name,message:t.message,cause:t.cause,...t instanceof AggregateError&&{errors:t.errors}}:t,o=Object.fromEntries(Object.entries(e).map(([e,t])=>[t,e]));exports.createJsonBackend=r;

package/dist/holz-json-backend.js

@@ -1,37 +1,63 @@
-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
-    },
-    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
-};
+//#region ../holz-core/dist/holz-core.js
+var e = {
+	fatal: 60,
+	error: 50,
+	warn: 40,
+	info: 30,
+	debug: 20,
+	trace: 10
+}, t = (n, r) => {
+	let i = (e, t, i = {}) => {
+		n({
+			timestamp: Date.now(),
+			message: t,
+			level: e,
+			origin: r,
+			context: i
+		});
+	}, a = {
+		owner: r,
+		trace: i.bind(null, e.trace),
+		debug: i.bind(null, e.debug),
+		info: i.bind(null, e.info),
+		warn: i.bind(null, e.warn),
+		error: i.bind(null, e.error),
+		fatal: i.bind(null, e.fatal),
+		namespace: (e) => t(n, r.concat(e)),
+		withMiddleware: (e) => t(e(n), r)
+	}, o = {
+		configurable: !1,
+		enumerable: !1
+	};
+	return Object.defineProperties(a, {
+		withMiddleware: o,
+		namespace: o,
+		trace: o,
+		debug: o,
+		info: o,
+		warn: o,
+		error: o,
+		fatal: o
+	});
+}, n = new TextEncoder(), r = ({ stream: e, signal: t }) => {
+	let r = e.getWriter();
+	return t?.aborted ? r.close().catch(i) : t?.addEventListener("abort", () => void r.close().catch(i), { once: !0 }), (e) => {
+		if (r.desiredSize === null || r.desiredSize <= 0) return;
+		let t = JSON.stringify({
+			level: o[e.level],
+			time: new Date(e.timestamp).toISOString(),
+			msg: e.message,
+			origin: e.origin,
+			ctx: Object.keys(e.context).length > 0 ? e.context : void 0
+		}, a);
+		r.write(n.encode(`${t}\n`)).catch(i);
+	};
+}, i = () => {}, a = (e, t) => t instanceof Error ? {
+	...t,
+	name: t.name,
+	message: t.message,
+	cause: t.cause,
+	...t instanceof AggregateError && { errors: t.errors }
+} : t, o = Object.fromEntries(Object.entries(e).map(([e, t]) => [t, e]));
+//#endregion
+export { r as createJsonBackend };

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

@@ -0,0 +1 @@
+export {};

package/dist/src/index.d.ts

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

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

@@ -0,0 +1,30 @@
+import { LogProcessor } from '@holz/core';
+/**
+ * Prints structured logs to a writable stream in NDJSON form. Optimized for
+ * log files.
+ *
+ * Writes to a Web Streams `WritableStream<Uint8Array>` so the same backend
+ * runs across Node, Deno, Bun, and the browser (e.g. OPFS). See the readme
+ * for a Node file-stream example.
+ *
+ * @example
+ * createJsonBackend({
+ *   stream: new WritableStream({
+ *     write: (chunk) => void process.stdout.write(chunk),
+ *   }),
+ * })
+ *
+ * @see https://github.com/ndjson/ndjson-spec
+ */
+export declare const createJsonBackend: ({ stream, signal }: Config) => LogProcessor;
+interface Config {
+    /** Where to print logs. Each log is written as a line of UTF-8 NDJSON. */
+    stream: WritableStream<Uint8Array>;
+    /**
+     * Closes the stream on abort, flushing queued writes and committing
+     * OPFS-style sinks. Fire-and-forget: to await the flush, observe your own
+     * sink or resource completion. Logs are dropped once shutdown begins.
+     */
+    signal?: AbortSignal;
+}
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holz/json-backend",
-  "version": "0.8.2",
+  "version": "0.8.3-rc.154+3f5148e",
   "description": "Print logs as newline-delimited JSON.",
   "type": "module",
   "repository": {
@@ -32,18 +32,18 @@
   ],
   "scripts": {
     "prepack": "vite build",
-    "test:unit": "vitest --color --passWithNoTests",
+    "test:unit": "vitest run --color --passWithNoTests",
     "test:types": "tsc"
   },
   "devDependencies": {
-    "@holz/core": "^0.8.2",
-    "@types/node": "^22.0.0",
-    "@vitest/coverage-v8": "^3.0.8",
-    "typescript": "^5.8.2",
-    "vite": "^6.0.0",
-    "vite-plugin-dts": "^4.5.3",
-    "vite-tsconfig-paths": "^5.1.4",
-    "vitest": "^3.0.8"
+    "@holz/core": "^0.8.3-rc.154+3f5148e",
+    "@types/node": "^24.0.0",
+    "@vitest/coverage-v8": "^4.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"
   },
-  "gitHead": "f099a09cd01834de9bc1714908183cbb7b828c85"
+  "gitHead": "3f5148eb94bb1d7200d4b4993c95ea30db76b0c4"
 }

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

@@ -1,22 +0,0 @@
-import { LogProcessor } from '@holz/core';
-import { Writable } from 'node:stream';
-
-declare interface Config {
-    /** Where to print logs. */
-    stream: Writable;
-}
-
-/**
- * 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 http://ndjson.org
- */
-export declare const createJsonBackend: ({ stream }: Config) => LogProcessor;
-
-export { }