@ayepi/log 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Philip Diffenderfer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,216 @@
+# @ayepi/log
+
+Structured logging with **AsyncLocalStorage trace context**. Stack context with
+`logWith` and it flows through the whole async call tree — and onto thrown errors —
+for great tracing. Plus console interception, console + file transports, configurable
+error serialization, a record filter hook, and an ayepi middleware.
+
+```sh
+pnpm add @ayepi/log
+```
+
+```ts
+import { createLogger } from '@ayepi/log'
+const log = createLogger({ level: 'debug' })
+
+log.logWith({ reqId: 'abc' }, async () => {
+  log.info('handling', { userId: 'u1' }) // record carries reqId + userId
+  await work()                            // a rejection here is tagged with { reqId, userId }
+})
+```
+
+Bare `import` has **no side effects** — console interception is opt-in.
+
+## `log(level, …args)`
+
+Builds a record from mixed arguments:
+
+- always `tms`, `level`, `msg` (the space-joined non-object args);
+- object args are **merged** into the record;
+- `Error` args become `error` / `additionalErrors` (serialized with `name`, `message`,
+  `stack`, recursive `cause`, own props) — and **any trace context attached to the error
+  is merged in** (so a caught error carries the context from where it was thrown);
+- emitted only if `level >= ` the configured threshold (`debug < info < warn < error`).
+
+```ts
+log.error('upload failed', err, { docId })
+// { tms, level:'error', msg:'upload failed', docId, error:{ name, message, stack, cause… }, …throwSiteContext }
+```
+
+## Value resolution — `toLOG` / `toJSON`
+
+Logged values are resolved to a plain **loggable shape** (deeply) before they're merged — so
+the same shape appears in the record transports receive, the `sanitize` pass, and both the text
+and JSON output. A value's **`toLOG()`** hook (logging-specific, **wins over `toJSON`**) or
+`toJSON()` (e.g. `Date`) defines that shape; otherwise it's a structural copy.
+
+```ts
+class Money {
+  constructor(private cents: number) {}
+  toJSON() { return this.cents }                          // API responses: a number
+  toLOG()  { return `$${(this.cents / 100).toFixed(2)}` } // logs: "$19.99"
+}
+log.info('charged', { amount: new Money(1999) }) // → …, amount: "$19.99"
+```
+
+`toLOG()` **may return a promise** — the line is delivered once it resolves, so an expensive or
+async log view is built only when the line actually logs:
+
+```ts
+log.debug('account', { acct: { toLOG: async () => ({ id, balance: await loadBalance() }) } })
+```
+
+A hook that throws/rejects degrades that value to `'(unresolved value)'` (reported to
+`onError`); the rest of the line still logs. `resolveLogValue(value)` runs this standalone.
+
+For types you **don't** own (a `Request`, `URL`, `Buffer`, a third-party class), configure
+`serializers` — predicate functions tried in order at every depth (first non-`undefined` wins,
+taking precedence over `toLOG`/`toJSON`):
+
+```ts
+createLogger({
+  serializers: [
+    (v) => (v instanceof URL ? v.href : undefined),
+    (v) => (v instanceof Request ? { method: v.method, url: v.url } : undefined),
+  ],
+})
+```
+
+## Runtime control & shutdown
+
+```ts
+log.setLevel('debug')        // change the threshold at runtime (admin toggle, signal handler)
+log.isLevelEnabled('debug')  // guard an expensive block when logMaybe doesn't fit
+
+await log.flush()            // drain buffered transports (e.g. the file transport)
+await log.close()            // flush + release timers/handles — wire into an @ayepi/updown teardown
+```
+
+`flush`/`close` run every transport in parallel and route a failing one to `onError`, so one
+bad transport can't abort shutdown.
+
+## Context stacking — `logWith`
+
+`logWith(add, inner)` merges `add` into the ambient context (immutably) and runs
+`inner` within it. Ambient fields keep their bare key; a colliding call-site field
+becomes `key2` (so `reqId`/`userId` stay stable across every log in a request). If
+`inner` returns a promise, its rejection is tagged with the full context under
+`LOG_CONTEXT` (innermost `logWith` wins).
+
+## Output & transports
+
+Text by default (`[tms] level msg key=value, key=value`); `structured: true` for JSON.
+Transports are pluggable and fire-and-forget:
+
+- `consoleTransport(...)` — writes through the captured original console (recursion-safe).
+- `fileTransport(...)` from `@ayepi/log/file` — **non-blocking + batched**: `write()`
+  buffers and returns immediately; lines flush to disk in batches (one append per flush,
+  one flush in flight) so callers never wait on I/O and the FS isn't hammered per line.
+  Size (default) or date rotation; `maxSize`/`maxFiles`/`flushInterval`/`maxBufferBytes`;
+  `close()` flushes (wire it to an `@ayepi/updown` shutdown hook).
+
+```ts
+import { createLogger } from '@ayepi/log'
+import { fileTransport } from '@ayepi/log/file'
+
+const log = createLogger({
+  structured: true,
+  transports: [fileTransport({ path: './logs/app.log', maxSize: 10 * 1024 * 1024, maxFiles: 7 })],
+  filter: (r) => (r.secret ? null : { ...r, ip: redact(r.ip) }), // drop or transform before formatting
+})
+```
+
+## Console interception (opt-in)
+
+```ts
+import { interceptConsole, createLogger } from '@ayepi/log'
+
+createLogger({ interceptConsole: true }) // or: const restore = interceptConsole()
+console.log('routed', { through: 'the logger' }) // log/info/debug/warn/error/trace/dir
+```
+
+## Sanitization — `sanitize`
+
+Declarative redaction + truncation on every record (direct calls **and** intercepted
+`console.*`). Mask by key or value, cap string/array sizes, or drop a record outright:
+
+```ts
+import { createLogger, partialMask } from '@ayepi/log'
+
+createLogger({
+  sanitize: {
+    filter: (r) => r.level !== 'debug',          // drop a record entirely
+    sensitiveKeys: ['password', /token$/i],       // mask matching property names (any depth)
+    sensitiveValues: [/\b\d{16}\b/],              // mask matching string values
+    mask: partialMask(3),                         // 'secret-token' → 'sec***' (default: '[redacted]')
+    maxStringLength: 2000,                        // long string → 'first 2000…... (+N more)'
+    maxArrayLength: 100,                          // big homogeneous array → first 100 + '(+N more)'
+  },
+})
+```
+
+`createSanitizer(opts)` builds the same transformer standalone (it has the `filter` shape, so
+it composes there too). `Date`/class instances and the reserved `tms`/`level` fields are left
+untouched.
+
+## Deferred arguments — `logMaybe`
+
+Compute an expensive log argument **only if the line will actually be logged**. `logMaybe(fn)`
+defers `fn` until the level passes the threshold; the intercepted/structured pipeline then
+calls `fn(level)`, awaits it (async allowed), and treats the result as a normal argument:
+
+```ts
+import { logMaybe } from '@ayepi/log'
+
+log.debug('state', logMaybe(() => buildExpensiveSnapshot())) // snapshot built only at debug level
+```
+
+A line below the threshold never runs `fn`. Outside interception, the value renders via
+`toJSON` (the sync value, or `'(unresolved value)'` for a promise).
+
+## Middleware — `@ayepi/log/middleware` + `@ayepi/log/server`
+
+The ayepi middleware is a **def/impl split**. The **def** is a frontend-safe contract
+(no `node:async_hooks`) declared in your spec; the **impl** binds the trace-context
+behavior on the server. Push per-request trace context for the whole chain + handler:
+
+```ts
+// shared.ts — frontend-safe def (no node:async_hooks)
+import { logMiddleware } from '@ayepi/log/middleware'
+
+const trace = logMiddleware({ requires: [auth] }) // ctx.user is typed in .server below
+const api = spec({ endpoints: { ...trace.group({ … }) } })
+```
+
+```ts
+// server.ts — bind the impl (pulls in node:async_hooks)
+import { logMiddleware } from '@ayepi/log/server'
+import { implement } from '@ayepi/core'
+
+const server = implement(api)
+  .middleware(logMiddleware.server(trace, {
+    context: (ctx, req) => ({ reqId: crypto.randomUUID(), userId: ctx.user.id, path: new URL(req.url).pathname }),
+  }))
+  .handlers({ … })
+```
+
+`logMiddleware(opts?)` is a **def factory** (`opts = { name?, requires? }`) that
+establishes log trace context for the downstream chain. `logMiddleware.server(def, {
+context, logWith? })` — exported from `@ayepi/log/server` — binds it; the `context`
+builder `(ctx, req) => object` lives here, on the server side.
+
+## For AI coding agents
+
+This package ships dense, machine-oriented reference docs written for **AI coding agents**
+(Claude Code, Cursor, and the like) to understand and drive the package — point your agent at them:
+
+- [`ayepi-log-errors-console.md`](./ayepi-log-errors-console.md)
+- [`ayepi-log-middleware.md`](./ayepi-log-middleware.md)
+- [`ayepi-log-transports.md`](./ayepi-log-transports.md)
+- [`ayepi-log.md`](./ayepi-log.md)
+
+They live next to the source in the [repo](https://github.com/ClickerMonkey/ayepi/tree/main/packages/log) and are **not** shipped in the npm tarball.
+
+## License
+
+MIT © Philip Diffenderfer

package/dist/file.cjs

@@ -0,0 +1,175 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_internal = require("./internal.cjs");
+let node_fs_promises = require("node:fs/promises");
+let node_path = require("node:path");
+//#region src/file.ts
+/**
+* # @ayepi/log/file
+*
+* A Node file {@link Transport} with rotation, built for **heavy load**: `write()`
+* is non-blocking (it appends to an in-memory buffer and returns immediately), and
+* buffered lines are flushed to disk in **batches** — one append per flush, at most
+* one flush in flight — so callers never wait on I/O and the file system is not
+* overwhelmed by a syscall per line.
+*
+* Everything touching the file system is **asynchronous** (`node:fs/promises`),
+* including rotation/stat/prune, so a flush never blocks the event loop.
+*
+* **Size** rotation (default) keeps `app.log` bounded to `maxSize`, shifting
+* `app.log → app.log.1 → …` and pruning beyond `maxFiles`. **Date** rotation writes
+* `app-YYYY-MM-DD.log`. Defaults to structured JSON lines. Call `close()` (e.g. from
+* an `@ayepi/updown` shutdown hook) to flush the buffer on exit.
+*
+* `fs` and the clock are injectable for deterministic tests.
+*
+* @module
+*/
+/** Rotate when the active file would exceed this size (10 MiB). */
+const DEFAULT_MAX_SIZE = 10 * 1024 * 1024;
+/** Keep at most this many rotated/dated files. */
+const DEFAULT_MAX_FILES = 5;
+/** Flush the buffer at most this often (ms). */
+const DEFAULT_FLUSH_INTERVAL = 250;
+/** Force an immediate flush once the buffer reaches this many bytes. */
+const DEFAULT_MAX_BUFFER_BYTES = 256 * 1024;
+const NEWLINE = "\n";
+/** `YYYY-MM-DD` length from an ISO string. */
+const DATE_KEY_LEN = 10;
+const exists = async (p) => {
+	try {
+		await (0, node_fs_promises.access)(p);
+		return true;
+	} catch {
+		return false;
+	}
+};
+const nodeFs = {
+	exists,
+	stat: (p) => (0, node_fs_promises.stat)(p).then((s) => ({ size: s.size })),
+	mkdir: (p) => (0, node_fs_promises.mkdir)(p, { recursive: true }).then(() => void 0),
+	appendFile: (p, d) => (0, node_fs_promises.appendFile)(p, d),
+	rename: (a, b) => (0, node_fs_promises.rename)(a, b),
+	unlink: (p) => (0, node_fs_promises.unlink)(p),
+	readdir: (p) => (0, node_fs_promises.readdir)(p)
+};
+const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/** Create a non-blocking, batched Node file {@link Transport}. */
+function fileTransport(opts) {
+	const fs = opts.fs ?? nodeFs;
+	const maxSize = opts.maxSize ?? DEFAULT_MAX_SIZE;
+	const maxFiles = opts.maxFiles ?? DEFAULT_MAX_FILES;
+	const structured = opts.structured ?? true;
+	const strategy = opts.strategy ?? "size";
+	const flushInterval = opts.flushInterval ?? DEFAULT_FLUSH_INTERVAL;
+	const maxBufferBytes = opts.maxBufferBytes ?? DEFAULT_MAX_BUFFER_BYTES;
+	const now = opts.now ?? (() => Date.now());
+	const dir = (0, node_path.dirname)(opts.path);
+	const ext = (0, node_path.extname)(opts.path);
+	const base = (0, node_path.basename)(opts.path, ext);
+	let dirEnsured = false;
+	let lastDateKey = null;
+	let knownSize = -1;
+	let buffer = [];
+	let bufferBytes = 0;
+	let flushing = false;
+	let timer = null;
+	const ensureDir = async () => {
+		if (dirEnsured) return;
+		if (dir && !await fs.exists(dir)) await fs.mkdir(dir, { recursive: true });
+		dirEnsured = true;
+	};
+	const dateKey = () => new Date(now()).toISOString().slice(0, DATE_KEY_LEN);
+	const datedPath = (key) => (0, node_path.join)(dir, `${base}-${key}${ext}`);
+	/** Size rotation: drop the oldest, shift `.n → .n+1`, then `app.log → app.log.1`. */
+	const rotateBySize = async (path) => {
+		const oldest = `${path}.${maxFiles}`;
+		if (await fs.exists(oldest)) try {
+			await fs.unlink(oldest);
+		} catch {}
+		for (let i = maxFiles - 1; i >= 1; i--) if (await fs.exists(`${path}.${i}`)) await fs.rename(`${path}.${i}`, `${path}.${i + 1}`);
+		if (await fs.exists(path)) await fs.rename(path, `${path}.1`);
+	};
+	const pruneDated = async () => {
+		if (!fs.readdir) return;
+		const re = new RegExp(`^${escapeRegExp(base)}-(\\d{4}-\\d{2}-\\d{2})${escapeRegExp(ext)}$`);
+		try {
+			/* v8 ignore next */ const files = (await fs.readdir(dir || ".")).filter((f) => re.test(f)).sort();
+			while (files.length > maxFiles) {
+				const old = files.shift();
+				try {
+					await fs.unlink((0, node_path.join)(dir, old));
+				} catch {}
+			}
+		} catch {}
+	};
+	const currentSize = async (path) => {
+		if (!await fs.exists(path)) return 0;
+		try {
+			return (await fs.stat(path)).size;
+		} catch {
+			return 0;
+		}
+	};
+	async function flush() {
+		if (flushing || buffer.length === 0) return;
+		flushing = true;
+		if (timer) {
+			clearTimeout(timer);
+			timer = null;
+		}
+		try {
+			await ensureDir();
+			const batch = buffer.join("");
+			const batchBytes = bufferBytes;
+			buffer = [];
+			bufferBytes = 0;
+			if (strategy === "date") {
+				const key = dateKey();
+				if (key !== lastDateKey) {
+					lastDateKey = key;
+					await pruneDated();
+				}
+				await fs.appendFile(datedPath(key), batch);
+			} else {
+				if (knownSize < 0) knownSize = await currentSize(opts.path);
+				if (knownSize > 0 && knownSize + batchBytes > maxSize) {
+					await rotateBySize(opts.path);
+					knownSize = 0;
+				}
+				await fs.appendFile(opts.path, batch);
+				knownSize += batchBytes;
+			}
+		} catch (err) {
+			try {
+				opts.onError?.(err);
+			} catch {}
+		} finally {
+			flushing = false;
+			if (buffer.length > 0) scheduleFlush();
+		}
+	}
+	function scheduleFlush() {
+		if (timer || flushing) return;
+		timer = setTimeout(() => {
+			timer = null;
+			flush();
+		}, flushInterval);
+		timer.unref?.();
+	}
+	return {
+		name: "file",
+		write(record, text) {
+			const line = (structured ? require_internal.formatJson(record) : text) + NEWLINE;
+			buffer.push(line);
+			bufferBytes += Buffer.byteLength(line);
+			if (bufferBytes >= maxBufferBytes) flush();
+			else scheduleFlush();
+		},
+		flush,
+		async close() {
+			await flush();
+		}
+	};
+}
+//#endregion
+exports.fileTransport = fileTransport;

package/dist/file.d.cts

@@ -0,0 +1,50 @@
+import { d as Transport } from "./internal.cjs";
+
+//#region src/file.d.ts
+
+/** The minimal **async** fs surface the transport uses (`node:fs/promises` satisfies it; tests inject their own). */
+interface FsLike {
+  exists(path: string): Promise<boolean>;
+  stat(path: string): Promise<{
+    size: number;
+  }>;
+  mkdir(path: string, opts: {
+    recursive: true;
+  }): Promise<void>;
+  /** Asynchronous, batched append — the hot path. */
+  appendFile(path: string, data: string): Promise<void>;
+  rename(from: string, to: string): Promise<void>;
+  unlink(path: string): Promise<void>;
+  readdir?(path: string): Promise<string[]>;
+}
+/** Options for {@link fileTransport}. */
+interface FileTransportOptions {
+  /** Target file path (e.g. `'./logs/app.log'`). The directory is created if missing. */
+  readonly path: string;
+  /** Rotate when the active file would exceed this many bytes (default 10 MiB). */
+  readonly maxSize?: number;
+  /** Keep at most this many rotated/dated files (default 5). */
+  readonly maxFiles?: number;
+  /** Write structured JSON lines regardless of the logger's text/json setting (default `true`). */
+  readonly structured?: boolean;
+  /** Rotation strategy (default `'size'`). */
+  readonly strategy?: 'size' | 'date';
+  /** Flush the buffer at most this often, in ms (default 250). */
+  readonly flushInterval?: number;
+  /** Force an immediate flush once the buffer reaches this many bytes (default 256 KiB). */
+  readonly maxBufferBytes?: number;
+  /** Injected fs (default `node:fs/promises`). */
+  readonly fs?: FsLike;
+  /**
+   * Observe a background **flush** failure (disk full, permission denied, rotation error).
+   * File logging is best-effort — a failed flush is dropped and never rejects; this hook lets
+   * you notice. Off by default. It must not throw; if it does, the throw is ignored.
+   */
+  readonly onError?: (err: unknown) => void;
+  /** Injected clock for date rotation/naming (default `() => Date.now()`). */
+  readonly now?: () => number;
+}
+/** Create a non-blocking, batched Node file {@link Transport}. */
+declare function fileTransport(opts: FileTransportOptions): Transport;
+//#endregion
+export { FileTransportOptions, FsLike, fileTransport };

package/dist/file.d.ts

@@ -0,0 +1,50 @@
+import { d as Transport } from "./internal.js";
+
+//#region src/file.d.ts
+
+/** The minimal **async** fs surface the transport uses (`node:fs/promises` satisfies it; tests inject their own). */
+interface FsLike {
+  exists(path: string): Promise<boolean>;
+  stat(path: string): Promise<{
+    size: number;
+  }>;
+  mkdir(path: string, opts: {
+    recursive: true;
+  }): Promise<void>;
+  /** Asynchronous, batched append — the hot path. */
+  appendFile(path: string, data: string): Promise<void>;
+  rename(from: string, to: string): Promise<void>;
+  unlink(path: string): Promise<void>;
+  readdir?(path: string): Promise<string[]>;
+}
+/** Options for {@link fileTransport}. */
+interface FileTransportOptions {
+  /** Target file path (e.g. `'./logs/app.log'`). The directory is created if missing. */
+  readonly path: string;
+  /** Rotate when the active file would exceed this many bytes (default 10 MiB). */
+  readonly maxSize?: number;
+  /** Keep at most this many rotated/dated files (default 5). */
+  readonly maxFiles?: number;
+  /** Write structured JSON lines regardless of the logger's text/json setting (default `true`). */
+  readonly structured?: boolean;
+  /** Rotation strategy (default `'size'`). */
+  readonly strategy?: 'size' | 'date';
+  /** Flush the buffer at most this often, in ms (default 250). */
+  readonly flushInterval?: number;
+  /** Force an immediate flush once the buffer reaches this many bytes (default 256 KiB). */
+  readonly maxBufferBytes?: number;
+  /** Injected fs (default `node:fs/promises`). */
+  readonly fs?: FsLike;
+  /**
+   * Observe a background **flush** failure (disk full, permission denied, rotation error).
+   * File logging is best-effort — a failed flush is dropped and never rejects; this hook lets
+   * you notice. Off by default. It must not throw; if it does, the throw is ignored.
+   */
+  readonly onError?: (err: unknown) => void;
+  /** Injected clock for date rotation/naming (default `() => Date.now()`). */
+  readonly now?: () => number;
+}
+/** Create a non-blocking, batched Node file {@link Transport}. */
+declare function fileTransport(opts: FileTransportOptions): Transport;
+//#endregion
+export { FileTransportOptions, FsLike, fileTransport };

package/dist/file.js

@@ -0,0 +1,174 @@
+import { d as formatJson } from "./internal.js";
+import { access, appendFile, mkdir, readdir, rename, stat, unlink } from "node:fs/promises";
+import { basename, dirname, extname, join } from "node:path";
+//#region src/file.ts
+/**
+* # @ayepi/log/file
+*
+* A Node file {@link Transport} with rotation, built for **heavy load**: `write()`
+* is non-blocking (it appends to an in-memory buffer and returns immediately), and
+* buffered lines are flushed to disk in **batches** — one append per flush, at most
+* one flush in flight — so callers never wait on I/O and the file system is not
+* overwhelmed by a syscall per line.
+*
+* Everything touching the file system is **asynchronous** (`node:fs/promises`),
+* including rotation/stat/prune, so a flush never blocks the event loop.
+*
+* **Size** rotation (default) keeps `app.log` bounded to `maxSize`, shifting
+* `app.log → app.log.1 → …` and pruning beyond `maxFiles`. **Date** rotation writes
+* `app-YYYY-MM-DD.log`. Defaults to structured JSON lines. Call `close()` (e.g. from
+* an `@ayepi/updown` shutdown hook) to flush the buffer on exit.
+*
+* `fs` and the clock are injectable for deterministic tests.
+*
+* @module
+*/
+/** Rotate when the active file would exceed this size (10 MiB). */
+const DEFAULT_MAX_SIZE = 10 * 1024 * 1024;
+/** Keep at most this many rotated/dated files. */
+const DEFAULT_MAX_FILES = 5;
+/** Flush the buffer at most this often (ms). */
+const DEFAULT_FLUSH_INTERVAL = 250;
+/** Force an immediate flush once the buffer reaches this many bytes. */
+const DEFAULT_MAX_BUFFER_BYTES = 256 * 1024;
+const NEWLINE = "\n";
+/** `YYYY-MM-DD` length from an ISO string. */
+const DATE_KEY_LEN = 10;
+const exists = async (p) => {
+	try {
+		await access(p);
+		return true;
+	} catch {
+		return false;
+	}
+};
+const nodeFs = {
+	exists,
+	stat: (p) => stat(p).then((s) => ({ size: s.size })),
+	mkdir: (p) => mkdir(p, { recursive: true }).then(() => void 0),
+	appendFile: (p, d) => appendFile(p, d),
+	rename: (a, b) => rename(a, b),
+	unlink: (p) => unlink(p),
+	readdir: (p) => readdir(p)
+};
+const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/** Create a non-blocking, batched Node file {@link Transport}. */
+function fileTransport(opts) {
+	const fs = opts.fs ?? nodeFs;
+	const maxSize = opts.maxSize ?? DEFAULT_MAX_SIZE;
+	const maxFiles = opts.maxFiles ?? DEFAULT_MAX_FILES;
+	const structured = opts.structured ?? true;
+	const strategy = opts.strategy ?? "size";
+	const flushInterval = opts.flushInterval ?? DEFAULT_FLUSH_INTERVAL;
+	const maxBufferBytes = opts.maxBufferBytes ?? DEFAULT_MAX_BUFFER_BYTES;
+	const now = opts.now ?? (() => Date.now());
+	const dir = dirname(opts.path);
+	const ext = extname(opts.path);
+	const base = basename(opts.path, ext);
+	let dirEnsured = false;
+	let lastDateKey = null;
+	let knownSize = -1;
+	let buffer = [];
+	let bufferBytes = 0;
+	let flushing = false;
+	let timer = null;
+	const ensureDir = async () => {
+		if (dirEnsured) return;
+		if (dir && !await fs.exists(dir)) await fs.mkdir(dir, { recursive: true });
+		dirEnsured = true;
+	};
+	const dateKey = () => new Date(now()).toISOString().slice(0, DATE_KEY_LEN);
+	const datedPath = (key) => join(dir, `${base}-${key}${ext}`);
+	/** Size rotation: drop the oldest, shift `.n → .n+1`, then `app.log → app.log.1`. */
+	const rotateBySize = async (path) => {
+		const oldest = `${path}.${maxFiles}`;
+		if (await fs.exists(oldest)) try {
+			await fs.unlink(oldest);
+		} catch {}
+		for (let i = maxFiles - 1; i >= 1; i--) if (await fs.exists(`${path}.${i}`)) await fs.rename(`${path}.${i}`, `${path}.${i + 1}`);
+		if (await fs.exists(path)) await fs.rename(path, `${path}.1`);
+	};
+	const pruneDated = async () => {
+		if (!fs.readdir) return;
+		const re = new RegExp(`^${escapeRegExp(base)}-(\\d{4}-\\d{2}-\\d{2})${escapeRegExp(ext)}$`);
+		try {
+			/* v8 ignore next */ const files = (await fs.readdir(dir || ".")).filter((f) => re.test(f)).sort();
+			while (files.length > maxFiles) {
+				const old = files.shift();
+				try {
+					await fs.unlink(join(dir, old));
+				} catch {}
+			}
+		} catch {}
+	};
+	const currentSize = async (path) => {
+		if (!await fs.exists(path)) return 0;
+		try {
+			return (await fs.stat(path)).size;
+		} catch {
+			return 0;
+		}
+	};
+	async function flush() {
+		if (flushing || buffer.length === 0) return;
+		flushing = true;
+		if (timer) {
+			clearTimeout(timer);
+			timer = null;
+		}
+		try {
+			await ensureDir();
+			const batch = buffer.join("");
+			const batchBytes = bufferBytes;
+			buffer = [];
+			bufferBytes = 0;
+			if (strategy === "date") {
+				const key = dateKey();
+				if (key !== lastDateKey) {
+					lastDateKey = key;
+					await pruneDated();
+				}
+				await fs.appendFile(datedPath(key), batch);
+			} else {
+				if (knownSize < 0) knownSize = await currentSize(opts.path);
+				if (knownSize > 0 && knownSize + batchBytes > maxSize) {
+					await rotateBySize(opts.path);
+					knownSize = 0;
+				}
+				await fs.appendFile(opts.path, batch);
+				knownSize += batchBytes;
+			}
+		} catch (err) {
+			try {
+				opts.onError?.(err);
+			} catch {}
+		} finally {
+			flushing = false;
+			if (buffer.length > 0) scheduleFlush();
+		}
+	}
+	function scheduleFlush() {
+		if (timer || flushing) return;
+		timer = setTimeout(() => {
+			timer = null;
+			flush();
+		}, flushInterval);
+		timer.unref?.();
+	}
+	return {
+		name: "file",
+		write(record, text) {
+			const line = (structured ? formatJson(record) : text) + NEWLINE;
+			buffer.push(line);
+			bufferBytes += Buffer.byteLength(line);
+			if (bufferBytes >= maxBufferBytes) flush();
+			else scheduleFlush();
+		},
+		flush,
+		async close() {
+			await flush();
+		}
+	};
+}
+//#endregion
+export { fileTransport };