@holz/json-backend 0.8.3-rc.169 → 0.8.3-rc.171

package/README.md

@@ -1,66 +1,27 @@
 # `@holz/json-backend`
 
-Serializes structured logs to a writable stream in [NDJSON](https://github.com/ndjson/ndjson-spec) format.
+Prints structured logs to a writable stream in NDJSON form.
 
 ## 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 { createWriteStream } from 'node:fs';
 
 const logger = createLogger(
   createJsonBackend({
-    stream: new WritableStream<Uint8Array>(
-      {
-        // ...
-      },
-      new CountQueuingStrategy({
-        highWaterMark: 1024,
-      }),
-    ),
+    stream: createWriteStream('my-logs.ndjson', { flags: 'a' }),
   }),
 );
 ```
 
-### 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.
+Logs are output in [NDJSON](https://github.com/ndjson/ndjson-spec) 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.
 
-```typescript
-const controller = new AbortController();
-
-createJsonBackend({
-  stream: writableStream,
-  signal: controller.signal,
-});
-
-// Permanently close the writable stream.
-controller.abort();
-```
+The `stream` option specifies where the logs will be written to. You can use any writable stream, such as a file or `process.stdout`.
 
-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.
+## Log Rotation
 
-## Caveats
+Long-lived processes or noisy services can fill up the disk, given enough time.
 
-- 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.
+Lean on your environment's tools (`journalctl`) or use a package like [rotating-file-stream](https://github.com/iccicci/rotating-file-stream) to prevent files from growing unbounded.

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=(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;
+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=({stream:e})=>t=>{let n=JSON.stringify({level:i[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},r);e.write(`${n}\n`)},r=(e,t)=>t instanceof Error?{...t,name:t.name,message:t.message,cause:t.cause,...t instanceof AggregateError&&{errors:t.errors}}:t,i=Object.fromEntries(Object.entries(e).map(([e,t])=>[t,e]));exports.createJsonBackend=n;

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

@@ -1,33 +1,22 @@
 import { LogProcessor } from '@holz/core';
+import { Writable } from 'node:stream';
 
 declare 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;
+    /** Where to print logs. */
+    stream: Writable;
 }
 
 /**
  * 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),
- *   }),
+ *   stream: fs.createWriteStream('my-app.log', { flags: 'a' }),
  * })
  *
  * @see https://github.com/ndjson/ndjson-spec
  */
-export declare const createJsonBackend: ({ stream, signal }: Config) => LogProcessor;
+export declare const createJsonBackend: ({ stream }: Config) => LogProcessor;
 
 export { }

package/dist/holz-json-backend.js

@@ -39,25 +39,21 @@ var e = {
 		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 ? {
+}, n = ({ stream: e }) => (t) => {
+	let n = JSON.stringify({
+		level: i[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
+	}, r);
+	e.write(`${n}\n`);
+}, r = (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]));
+} : t, i = Object.fromEntries(Object.entries(e).map(([e, t]) => [t, e]));
 //#endregion
-export { r as createJsonBackend };
+export { n as createJsonBackend };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holz/json-backend",
-  "version": "0.8.3-rc.169+b0bea47",
+  "version": "0.8.3-rc.171+909c4b9",
   "description": "Print logs as newline-delimited JSON.",
   "type": "module",
   "repository": {
@@ -37,7 +37,7 @@
     "test:types": "tsc"
   },
   "devDependencies": {
-    "@holz/core": "^0.8.3-rc.169+b0bea47",
+    "@holz/core": "^0.8.3-rc.171+909c4b9",
     "@microsoft/api-extractor": "^7.58.8",
     "@types/node": "^24.0.0",
     "@vitest/coverage-v8": "^4.0.0",
@@ -47,5 +47,5 @@
     "vite-tsconfig-paths": "^6.0.0",
     "vitest": "^4.0.0"
   },
-  "gitHead": "b0bea47da1b33d1e7c1d681a19b2cbe6e0cfea7a"
+  "gitHead": "909c4b99657f1f67fc7124fc8fad767acad32708"
 }