@raypx-kit/logger 0.0.0-alpha.0 → 0.0.0-alpha.2

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @raypx-kit/logger
 
+## 0.0.0-alpha.2
+
+### Major Changes
+
+- a6af9fe: Raise the minimum supported Node.js version from 22.14.0 to 22.21.0. Update
+  package engine declarations and library build targets to the new floor, and
+  verify installed consumers on Node 22.21.0. Upgrade older Node installations
+  before installing these releases. The repository development pin remains 24.22.0.
+
+## 0.0.0-alpha.1
+
+### Patch Changes
+
+- 5e0caaf: Add `@raypx-kit/logger/safe`, an explicit field policy for drains that removes credentials, personal data, messages, causes and stacks and bounds each event, and `@raypx-kit/logger/stream`, an ordered JSON-lines drain for stderr or another writable.
+
 ## 0.0.0-alpha.0
 
 Initial Raypx Kit prerelease.

package/README.md

@@ -11,7 +11,7 @@ logger through every function.
 bun add @raypx-kit/logger
 ```
 
-ESM; Node 22.14+ or Bun. evlog is an external runtime dependency (`^2.33.1`), not
+ESM; Node 22.21+ or Bun. evlog is an external runtime dependency (`^2.33.1`), not
 bundled or copied. Its framework adapters and their optional peers are not
 required. The Node-only context entry uses `node:async_hooks`; the root and
 pipeline entries do not import it.
@@ -50,6 +50,8 @@ Importing this package does not initialize logging.
 | `@raypx-kit/logger`          | `initLogger`, `log`, `createLogger`, `createRequestLogger`, `createError`, `EvlogError`, `parseError`, `defineEvlog`, `toLoggerConfig`; their configuration, event, logger, error, sampling and drain types |
 | `@raypx-kit/logger/context`  | `runWithLogger`, `getLogger`, `useLogger` for Node and Bun asynchronous context                                                                                                                             |
 | `@raypx-kit/logger/pipeline` | `createDrainPipeline`, `DrainPipelineOptions`, `PipelineDrainFn`                                                                                                                                            |
+| `@raypx-kit/logger/safe`     | `withEventPolicy`, `createEventPolicy`, `safeError`, `DEFAULT_SENSITIVE_KEYS` and their types; no Node APIs, so it also runs on Workers                                                                     |
+| `@raypx-kit/logger/stream`   | `createStreamDrain` for ordered JSON lines on stderr or another Node writable                                                                                                                               |
 
 Core functions retain evlog's native types and behavior. `defineEvlog` describes
 shared configuration; pass `toLoggerConfig(config)` to `initLogger` when using a
@@ -130,6 +132,47 @@ For individual messages, use structured objects, for example
 `log.info({ action: 'worker.started' })`. This keeps events on the same drain and
 redaction path. evlog's pretty string/tag form bypasses that path.
 
+## Allowed fields and redaction
+
+Applications that must never log credentials, personal data or file contents can
+wrap their drain with an explicit field policy. Only the envelope (`timestamp`,
+`level`, `service`, `environment`) and the listed fields leave the process:
+
+```ts
+import { initLogger } from "@raypx-kit/logger";
+import { withEventPolicy } from "@raypx-kit/logger/safe";
+import { createStreamDrain } from "@raypx-kit/logger/stream";
+
+const output = createStreamDrain(); // JSON lines on stderr
+initLogger({
+  env: { service: "cli", environment: "production" },
+  silent: true,
+  drain: withEventPolicy(output, {
+    fields: ["operation", "requestId", "status", "durationMs", "error", "rpc"],
+    shapes: { rpc: ["system", "method"] },
+  }),
+});
+
+// Before exit:
+await output.close();
+```
+
+- Values of sensitive keys (passwords, tokens, cookies, headers, bodies, messages,
+  stacks, paths, commands, URLs, e-mail addresses and similar) are replaced at any
+  depth; strings are shortened and URLs, bearer tokens, JWTs and e-mail addresses
+  inside them are masked. Pass `sensitiveKeys` to replace the default pattern.
+- `error` keeps only a standard error name and a machine `code`; messages, causes
+  and stacks never leave the process.
+- `shapes` keeps selected string properties of framework objects.
+- Each event is limited to `maxEventBytes` (16 KiB by default); fields beyond the
+  limit are dropped in the order they are listed. Getters, `toJSON`, cycles and
+  hostile proxies are never invoked or followed.
+- Request metadata and headers in the drain context are not forwarded.
+
+`createStreamDrain` writes in order, never ends a stream it did not create, drops
+events beyond `maxPending` (1024) and reports write or serialization failures once
+from `flush()` or `close()`, never from the code that emitted the event.
+
 ## Drains, batching and shutdown
 
 ```ts

package/dist/context.d.mts

@@ -1,8 +1,6 @@
 import { AuditableLogger } from "evlog";
-//#region src/context.d.ts
 /** Run work with an existing logger; the caller retains ownership of emit(). */
 export declare function runWithLogger<TResult>(logger: AuditableLogger<object>, callback: () => TResult): TResult;
 export declare function getLogger<T extends object = Record<string, unknown>>(): AuditableLogger<T> | undefined;
 export declare const useLogger: <T extends object = Record<string, unknown>>() => AuditableLogger<T>;
-//#endregion
 //# sourceMappingURL=context.d.mts.map

package/dist/context.mjs

@@ -1,5 +1,5 @@
 import { createLoggerStorage } from "evlog/toolkit/storage";
-//#region src/context.ts
+// src/context.ts
 const context = createLoggerStorage("logger context. Wrap the operation in runWithLogger(logger, callback).", "@raypx-kit/logger/context");
 /** Run work with an existing logger; the caller retains ownership of emit(). */
 function runWithLogger(logger, callback) {
@@ -9,7 +9,6 @@ function getLogger() {
 	return context.storage.getStore() === void 0 ? void 0 : context.useLogger();
 }
 const useLogger = context.useLogger;
-//#endregion
 export { getLogger, runWithLogger, useLogger };
 
 //# sourceMappingURL=context.mjs.map

package/dist/safe.d.mts

@@ -0,0 +1,53 @@
+import { DrainContext } from "evlog";
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+  [key: string]: JsonValue;
+};
+/** A drained event after the policy: the fixed envelope plus allowed, cleaned fields. */
+export type SafeEvent = Readonly<Record<string, JsonValue>> & {
+  readonly timestamp: string;
+  readonly level: string;
+  readonly service: string;
+  readonly environment: string;
+};
+export type SafeDrain = (context: {
+  event: SafeEvent;
+}) => void | Promise<void>;
+export interface EventPolicyOptions {
+  /** Top-level fields that may leave the process. Everything else is dropped. */
+  fields: readonly string[];
+  /**
+   * Allowed fields that keep only the listed string properties, for framework
+   * objects such as `{ rpc: ["system", "method"] }`.
+   */
+  shapes?: Readonly<Record<string, readonly string[]>>;
+  /** Upper bound for one serialized event in UTF-8 bytes (default 16 KiB). */
+  maxEventBytes?: number;
+  /**
+   * Field names whose values are always replaced, at any depth. Names are compared
+   * after removing non-alphanumerics and lowercasing. Defaults to
+   * {@link DEFAULT_SENSITIVE_KEYS}.
+   */
+  sensitiveKeys?: RegExp;
+}
+/** Credentials, personal data, request material, process output and free text. */
+export declare const DEFAULT_SENSITIVE_KEYS: RegExp;
+/**
+ * Reduces any error, including evlog's serialized error field, to a standard name and
+ * an optional machine code. Messages, causes and stacks are never kept.
+ */
+export declare function safeError(error: unknown): {
+  name: string;
+  code?: string | number;
+};
+/**
+ * Returns a function that projects a raw event to its safe form: the envelope, then
+ * allowed fields in order until the byte limit. Hostile values cannot throw out of it.
+ */
+export declare function createEventPolicy({ fields, shapes, maxEventBytes, sensitiveKeys }: EventPolicyOptions): (event: unknown) => SafeEvent;
+/**
+ * Wraps a drain so it only ever receives policy-projected events. Request metadata
+ * and headers from the drain context are never forwarded. A failing projection
+ * drops the event instead of interrupting the caller.
+ */
+export declare function withEventPolicy(drain: SafeDrain, options: EventPolicyOptions): (context: DrainContext) => void | Promise<void>;
+//# sourceMappingURL=safe.d.mts.map

package/dist/safe.mjs

@@ -0,0 +1,180 @@
+// src/safe.ts
+const REDACTED = "[REDACTED]";
+const ENVELOPE = [
+	"timestamp",
+	"level",
+	"service",
+	"environment"
+];
+const LEVELS = /* @__PURE__ */ new Set([
+	"trace",
+	"debug",
+	"info",
+	"warn",
+	"error",
+	"fatal"
+]);
+const FORBIDDEN_KEYS = /* @__PURE__ */ new Set([
+	"__proto__",
+	"constructor",
+	"prototype",
+	"toJSON"
+]);
+const ERROR_NAMES = /* @__PURE__ */ new Set([
+	"Error",
+	"TypeError",
+	"RangeError",
+	"ReferenceError",
+	"SyntaxError",
+	"URIError",
+	"EvalError",
+	"AggregateError",
+	"AbortError",
+	"TimeoutError"
+]);
+/** Credentials, personal data, request material, process output and free text. */
+const DEFAULT_SENSITIVE_KEYS = /^(path|input|text)$|password|passwd|secret|token|authorization|cookie|credential|apikey|privatekey|email|username|headers|payload|body|content|output|stdout|stderr|stack|cause|message|filename|filepath|directory|command|argv|args|cwd|query|url|uri/;
+/** Reads data properties only; the policy never invokes getters or toJSON. */
+function ownData(value, key) {
+	if (value === null || typeof value !== "object") return void 0;
+	try {
+		return Object.getOwnPropertyDescriptor(value, key)?.value;
+	} catch {
+		return;
+	}
+}
+function cleanString(value) {
+	return value.slice(0, 256).replace(/https?:\/\/[^\s]+/gi, REDACTED).replace(/\bBearer\s+[^\s,;]+/gi, REDACTED).replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g, REDACTED).replace(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi, REDACTED).replace(/\b(password|token|secret|api[_-]?key)\s*[:=]\s*[^\s,;]+/gi, REDACTED).replace(/[\u0000-\u001f\u007f]/g, " ").slice(0, 256);
+}
+/**
+* Reduces any error, including evlog's serialized error field, to a standard name and
+* an optional machine code. Messages, causes and stacks are never kept.
+*/
+function safeError(error) {
+	try {
+		let name = ownData(error, "name");
+		if (name === void 0 && error instanceof Error) {
+			if (error instanceof TypeError) name = "TypeError";
+			else if (error instanceof RangeError) name = "RangeError";
+			else if (error instanceof SyntaxError) name = "SyntaxError";
+			else if (error instanceof ReferenceError) name = "ReferenceError";
+		}
+		const result = { name: typeof name === "string" && ERROR_NAMES.has(name) ? name : "Error" };
+		const code = ownData(error, "code");
+		if (typeof code === "string" && /^[A-Z][A-Z0-9_]{0,63}$/.test(code)) result.code = code;
+		else if (typeof code === "number" && Number.isSafeInteger(code)) result.code = code;
+		return result;
+	} catch {
+		return { name: "Error" };
+	}
+}
+/**
+* Returns a function that projects a raw event to its safe form: the envelope, then
+* allowed fields in order until the byte limit. Hostile values cannot throw out of it.
+*/
+function createEventPolicy({ fields, shapes = {}, maxEventBytes = 16384, sensitiveKeys = DEFAULT_SENSITIVE_KEYS }) {
+	const sensitive = (key) => sensitiveKeys.test(key.replace(/[^a-z0-9]/gi, "").toLowerCase());
+	const allowed = [...new Set(fields)].filter((key) => key.length <= 64 && !FORBIDDEN_KEYS.has(key) && !ENVELOPE.includes(key));
+	const encoder = new TextEncoder();
+	function clean(value, depth, seen, budget) {
+		if (budget.remaining-- <= 0) return "[SIZE_LIMIT]";
+		try {
+			if (value === null || typeof value === "boolean") return value;
+			if (typeof value === "string") return cleanString(value);
+			if (typeof value === "number") return Number.isFinite(value) ? value : void 0;
+			if (typeof value !== "object") return void 0;
+			if (value instanceof Error) return safeError(value);
+			if (depth >= 4) return "[DEPTH_LIMIT]";
+			if (seen.has(value)) return "[CIRCULAR]";
+			seen.add(value);
+			try {
+				if (Array.isArray(value)) {
+					const result = [];
+					const length = ownData(value, "length");
+					const count = Math.min(typeof length === "number" ? length : 0, 16);
+					for (let index = 0; index < count && budget.remaining > 0; index++) {
+						const item = clean(ownData(value, String(index)), depth + 1, seen, budget);
+						if (item !== void 0) result.push(item);
+					}
+					return result;
+				}
+				const result = {};
+				for (const key of Object.keys(value).slice(0, 32)) {
+					if (budget.remaining <= 0) break;
+					if (key.length > 64 || FORBIDDEN_KEYS.has(key)) continue;
+					if (sensitive(key)) {
+						result[key] = REDACTED;
+						continue;
+					}
+					const child = clean(ownData(value, key), depth + 1, seen, budget);
+					if (child !== void 0) result[key] = child;
+				}
+				return result;
+			} catch {
+				return "[UNAVAILABLE]";
+			} finally {
+				seen.delete(value);
+			}
+		} catch {
+			return "[UNAVAILABLE]";
+		}
+	}
+	return (event) => {
+		const text = (key, fallback) => {
+			const value = ownData(event, key);
+			return typeof value === "string" ? cleanString(value).slice(0, 80) : fallback;
+		};
+		const level = ownData(event, "level");
+		const result = {
+			timestamp: text("timestamp", (/* @__PURE__ */ new Date()).toISOString()),
+			level: typeof level === "string" && LEVELS.has(level) ? level : "info",
+			service: text("service", "unknown"),
+			environment: text("environment", "unknown")
+		};
+		let bytes = encoder.encode(JSON.stringify(result)).byteLength;
+		const budget = { remaining: 256 };
+		for (const key of allowed) {
+			if (budget.remaining <= 0) break;
+			budget.remaining -= 1;
+			const value = ownData(event, key);
+			if (value === void 0) continue;
+			let projected;
+			if (sensitive(key)) projected = REDACTED;
+			else if (key === "error") projected = safeError(value);
+			else if (Object.hasOwn(shapes, key)) {
+				const shaped = {};
+				for (const field of shapes[key] ?? []) {
+					const entry = ownData(value, field);
+					if (typeof entry === "string" && !sensitive(field)) shaped[field] = cleanString(entry);
+				}
+				projected = shaped;
+			} else projected = clean(value, 0, /* @__PURE__ */ new WeakSet(), budget);
+			if (projected === void 0) continue;
+			const size = encoder.encode(JSON.stringify({ [key]: projected })).byteLength;
+			if (bytes + size > maxEventBytes) continue;
+			result[key] = projected;
+			bytes += size;
+		}
+		return Object.freeze(result);
+	};
+}
+/**
+* Wraps a drain so it only ever receives policy-projected events. Request metadata
+* and headers from the drain context are never forwarded. A failing projection
+* drops the event instead of interrupting the caller.
+*/
+function withEventPolicy(drain, options) {
+	const project = createEventPolicy(options);
+	return (context) => {
+		let event;
+		try {
+			event = project(ownData(context, "event"));
+		} catch {
+			return;
+		}
+		return drain({ event });
+	};
+}
+export { DEFAULT_SENSITIVE_KEYS, createEventPolicy, safeError, withEventPolicy };
+
+//# sourceMappingURL=safe.mjs.map

package/dist/safe.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe.mjs","names":[],"sources":["../src/safe.ts"],"sourcesContent":["import type { DrainContext } from \"evlog\";\n\nexport type JsonValue =\n  | null\n  | boolean\n  | number\n  | string\n  | JsonValue[]\n  | { [key: string]: JsonValue };\n\n/** A drained event after the policy: the fixed envelope plus allowed, cleaned fields. */\nexport type SafeEvent = Readonly<Record<string, JsonValue>> & {\n  readonly timestamp: string;\n  readonly level: string;\n  readonly service: string;\n  readonly environment: string;\n};\n\nexport type SafeDrain = (context: { event: SafeEvent }) => void | Promise<void>;\n\nexport interface EventPolicyOptions {\n  /** Top-level fields that may leave the process. Everything else is dropped. */\n  fields: readonly string[];\n  /**\n   * Allowed fields that keep only the listed string properties, for framework\n   * objects such as `{ rpc: [\"system\", \"method\"] }`.\n   */\n  shapes?: Readonly<Record<string, readonly string[]>>;\n  /** Upper bound for one serialized event in UTF-8 bytes (default 16 KiB). */\n  maxEventBytes?: number;\n  /**\n   * Field names whose values are always replaced, at any depth. Names are compared\n   * after removing non-alphanumerics and lowercasing. Defaults to\n   * {@link DEFAULT_SENSITIVE_KEYS}.\n   */\n  sensitiveKeys?: RegExp;\n}\n\nconst REDACTED = \"[REDACTED]\";\nconst ENVELOPE = [\"timestamp\", \"level\", \"service\", \"environment\"] as const;\nconst LEVELS = new Set([\"trace\", \"debug\", \"info\", \"warn\", \"error\", \"fatal\"]);\nconst FORBIDDEN_KEYS = new Set([\"__proto__\", \"constructor\", \"prototype\", \"toJSON\"]);\nconst ERROR_NAMES = new Set([\n  \"Error\",\n  \"TypeError\",\n  \"RangeError\",\n  \"ReferenceError\",\n  \"SyntaxError\",\n  \"URIError\",\n  \"EvalError\",\n  \"AggregateError\",\n  \"AbortError\",\n  \"TimeoutError\",\n]);\n\n/** Credentials, personal data, request material, process output and free text. */\nexport const DEFAULT_SENSITIVE_KEYS =\n  /^(path|input|text)$|password|passwd|secret|token|authorization|cookie|credential|apikey|privatekey|email|username|headers|payload|body|content|output|stdout|stderr|stack|cause|message|filename|filepath|directory|command|argv|args|cwd|query|url|uri/;\n\n/** Reads data properties only; the policy never invokes getters or toJSON. */\nfunction ownData(value: unknown, key: string): unknown {\n  if (value === null || typeof value !== \"object\") return undefined;\n  try {\n    return Object.getOwnPropertyDescriptor(value, key)?.value;\n  } catch {\n    return undefined;\n  }\n}\n\nfunction cleanString(value: string): string {\n  return (\n    value\n      .slice(0, 256)\n      .replace(/https?:\\/\\/[^\\s]+/gi, REDACTED)\n      .replace(/\\bBearer\\s+[^\\s,;]+/gi, REDACTED)\n      .replace(/\\beyJ[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\b/g, REDACTED)\n      .replace(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\\.[A-Z]{2,}/gi, REDACTED)\n      .replace(/\\b(password|token|secret|api[_-]?key)\\s*[:=]\\s*[^\\s,;]+/gi, REDACTED)\n      // oxlint-disable-next-line no-control-regex -- Control characters never reach log output.\n      .replace(/[\\u0000-\\u001f\\u007f]/g, \" \")\n      .slice(0, 256)\n  );\n}\n\n/**\n * Reduces any error, including evlog's serialized error field, to a standard name and\n * an optional machine code. Messages, causes and stacks are never kept.\n */\nexport function safeError(error: unknown): { name: string; code?: string | number } {\n  try {\n    let name = ownData(error, \"name\");\n    if (name === undefined && error instanceof Error) {\n      if (error instanceof TypeError) name = \"TypeError\";\n      else if (error instanceof RangeError) name = \"RangeError\";\n      else if (error instanceof SyntaxError) name = \"SyntaxError\";\n      else if (error instanceof ReferenceError) name = \"ReferenceError\";\n    }\n    const result: { name: string; code?: string | number } = {\n      name: typeof name === \"string\" && ERROR_NAMES.has(name) ? name : \"Error\",\n    };\n    const code = ownData(error, \"code\");\n    if (typeof code === \"string\" && /^[A-Z][A-Z0-9_]{0,63}$/.test(code)) result.code = code;\n    else if (typeof code === \"number\" && Number.isSafeInteger(code)) result.code = code;\n    return result;\n  } catch {\n    return { name: \"Error\" };\n  }\n}\n\n/**\n * Returns a function that projects a raw event to its safe form: the envelope, then\n * allowed fields in order until the byte limit. Hostile values cannot throw out of it.\n */\nexport function createEventPolicy({\n  fields,\n  shapes = {},\n  maxEventBytes = 16_384,\n  sensitiveKeys = DEFAULT_SENSITIVE_KEYS,\n}: EventPolicyOptions): (event: unknown) => SafeEvent {\n  const sensitive = (key: string) =>\n    sensitiveKeys.test(key.replace(/[^a-z0-9]/gi, \"\").toLowerCase());\n  const allowed = [...new Set(fields)].filter(\n    (key) =>\n      key.length <= 64 &&\n      !FORBIDDEN_KEYS.has(key) &&\n      !(ENVELOPE as readonly string[]).includes(key),\n  );\n  const encoder = new TextEncoder();\n\n  function clean(\n    value: unknown,\n    depth: number,\n    seen: WeakSet<object>,\n    budget: { remaining: number },\n  ): JsonValue | undefined {\n    if (budget.remaining-- <= 0) return \"[SIZE_LIMIT]\";\n    try {\n      if (value === null || typeof value === \"boolean\") return value;\n      if (typeof value === \"string\") return cleanString(value);\n      if (typeof value === \"number\") return Number.isFinite(value) ? value : undefined;\n      if (typeof value !== \"object\") return undefined;\n      if (value instanceof Error) return safeError(value);\n      if (depth >= 4) return \"[DEPTH_LIMIT]\";\n      if (seen.has(value)) return \"[CIRCULAR]\";\n      seen.add(value);\n      try {\n        if (Array.isArray(value)) {\n          const result: JsonValue[] = [];\n          const length = ownData(value, \"length\");\n          const count = Math.min(typeof length === \"number\" ? length : 0, 16);\n          for (let index = 0; index < count && budget.remaining > 0; index++) {\n            const item = clean(ownData(value, String(index)), depth + 1, seen, budget);\n            if (item !== undefined) result.push(item);\n          }\n          return result;\n        }\n        const result: Record<string, JsonValue> = {};\n        for (const key of Object.keys(value).slice(0, 32)) {\n          if (budget.remaining <= 0) break;\n          if (key.length > 64 || FORBIDDEN_KEYS.has(key)) continue;\n          if (sensitive(key)) {\n            result[key] = REDACTED;\n            continue;\n          }\n          const child = clean(ownData(value, key), depth + 1, seen, budget);\n          if (child !== undefined) result[key] = child;\n        }\n        return result;\n      } catch {\n        return \"[UNAVAILABLE]\";\n      } finally {\n        seen.delete(value);\n      }\n    } catch {\n      return \"[UNAVAILABLE]\";\n    }\n  }\n\n  return (event) => {\n    const text = (key: string, fallback: string) => {\n      const value = ownData(event, key);\n      return typeof value === \"string\" ? cleanString(value).slice(0, 80) : fallback;\n    };\n    const level = ownData(event, \"level\");\n    const result: Record<string, JsonValue> = {\n      timestamp: text(\"timestamp\", new Date().toISOString()),\n      level: typeof level === \"string\" && LEVELS.has(level) ? level : \"info\",\n      service: text(\"service\", \"unknown\"),\n      environment: text(\"environment\", \"unknown\"),\n    };\n    let bytes = encoder.encode(JSON.stringify(result)).byteLength;\n    const budget = { remaining: 256 };\n    for (const key of allowed) {\n      if (budget.remaining <= 0) break;\n      budget.remaining -= 1;\n      const value = ownData(event, key);\n      if (value === undefined) continue;\n      let projected: JsonValue | undefined;\n      if (sensitive(key)) projected = REDACTED;\n      else if (key === \"error\") projected = safeError(value);\n      else if (Object.hasOwn(shapes, key)) {\n        const shaped: Record<string, JsonValue> = {};\n        for (const field of shapes[key] ?? []) {\n          const entry = ownData(value, field);\n          if (typeof entry === \"string\" && !sensitive(field)) shaped[field] = cleanString(entry);\n        }\n        projected = shaped;\n      } else projected = clean(value, 0, new WeakSet(), budget);\n      if (projected === undefined) continue;\n      const size = encoder.encode(JSON.stringify({ [key]: projected })).byteLength;\n      if (bytes + size > maxEventBytes) continue;\n      result[key] = projected;\n      bytes += size;\n    }\n    return Object.freeze(result) as SafeEvent;\n  };\n}\n\n/**\n * Wraps a drain so it only ever receives policy-projected events. Request metadata\n * and headers from the drain context are never forwarded. A failing projection\n * drops the event instead of interrupting the caller.\n */\nexport function withEventPolicy(\n  drain: SafeDrain,\n  options: EventPolicyOptions,\n): (context: DrainContext) => void | Promise<void> {\n  const project = createEventPolicy(options);\n  return (context) => {\n    let event: SafeEvent;\n    try {\n      event = project(ownData(context, \"event\"));\n    } catch {\n      return;\n    }\n    return drain({ event });\n  };\n}\n"],"mappings":"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"}

package/dist/stream.d.mts

@@ -0,0 +1,22 @@
+import { Writable } from "node:stream";
+export interface StreamDrainOptions {
+  /** Defaults to `process.stderr`. A caller-owned stream is flushed but never ended. */
+  stream?: Writable;
+  /** Events waiting for the stream before new ones are dropped (default 1024). */
+  maxPending?: number;
+}
+export interface StreamDrain {
+  (context: {
+    event: unknown;
+  }): Promise<void> | undefined;
+  /** Waits for written events; rejects once if any write or serialization failed. */
+  flush(): Promise<void>;
+  /** Stops accepting events, flushes and detaches from the stream. */
+  close(): Promise<void>;
+}
+/**
+ * Writes one JSON line per event, in order. Failures are recorded for flush/close
+ * instead of being thrown into the code that emitted the event.
+ */
+export declare function createStreamDrain({ stream, maxPending }?: StreamDrainOptions): StreamDrain;
+//# sourceMappingURL=stream.d.mts.map

package/dist/stream.mjs

@@ -0,0 +1,62 @@
+// src/stream.ts
+/**
+* Writes one JSON line per event, in order. Failures are recorded for flush/close
+* instead of being thrown into the code that emitted the event.
+*/
+function createStreamDrain({ stream = process.stderr, maxPending = 1024 } = {}) {
+	let tail = Promise.resolve();
+	let pending = 0;
+	let failed = false;
+	let closed = false;
+	const onError = () => {
+		failed = true;
+	};
+	stream.on("error", onError);
+	const drain = ((context) => {
+		if (closed) return void 0;
+		if (pending >= maxPending) {
+			failed = true;
+			return;
+		}
+		let line;
+		try {
+			line = `${JSON.stringify(context.event)}\n`;
+		} catch {
+			failed = true;
+			return;
+		}
+		pending += 1;
+		tail = tail.then(() => new Promise((resolve) => {
+			const done = (error) => {
+				if (error) failed = true;
+				pending -= 1;
+				resolve();
+			};
+			try {
+				stream.write(line, done);
+			} catch {
+				done(/* @__PURE__ */ new Error("write failed"));
+			}
+		}));
+		return tail;
+	});
+	drain.flush = async () => {
+		await tail;
+		if (failed) {
+			failed = false;
+			throw new Error("Log stream drain failed");
+		}
+	};
+	drain.close = async () => {
+		closed = true;
+		try {
+			await drain.flush();
+		} finally {
+			stream.off("error", onError);
+		}
+	};
+	return drain;
+}
+export { createStreamDrain };
+
+//# sourceMappingURL=stream.mjs.map

package/dist/stream.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.mjs","names":[],"sources":["../src/stream.ts"],"sourcesContent":["import type { Writable } from \"node:stream\";\n\nexport interface StreamDrainOptions {\n  /** Defaults to `process.stderr`. A caller-owned stream is flushed but never ended. */\n  stream?: Writable;\n  /** Events waiting for the stream before new ones are dropped (default 1024). */\n  maxPending?: number;\n}\n\nexport interface StreamDrain {\n  (context: { event: unknown }): Promise<void> | undefined;\n  /** Waits for written events; rejects once if any write or serialization failed. */\n  flush(): Promise<void>;\n  /** Stops accepting events, flushes and detaches from the stream. */\n  close(): Promise<void>;\n}\n\n/**\n * Writes one JSON line per event, in order. Failures are recorded for flush/close\n * instead of being thrown into the code that emitted the event.\n */\nexport function createStreamDrain({\n  stream = process.stderr,\n  maxPending = 1024,\n}: StreamDrainOptions = {}): StreamDrain {\n  let tail: Promise<void> = Promise.resolve();\n  let pending = 0;\n  let failed = false;\n  let closed = false;\n  const onError = () => {\n    failed = true;\n  };\n  stream.on(\"error\", onError);\n\n  const drain = ((context) => {\n    if (closed) return undefined;\n    if (pending >= maxPending) {\n      failed = true;\n      return undefined;\n    }\n    let line: string;\n    try {\n      line = `${JSON.stringify(context.event)}\\n`;\n    } catch {\n      failed = true;\n      return undefined;\n    }\n    pending += 1;\n    tail = tail.then(\n      () =>\n        new Promise<void>((resolve) => {\n          const done = (error?: Error | null) => {\n            if (error) failed = true;\n            pending -= 1;\n            resolve();\n          };\n          try {\n            stream.write(line, done);\n          } catch {\n            done(new Error(\"write failed\"));\n          }\n        }),\n    );\n    return tail;\n  }) as StreamDrain;\n\n  drain.flush = async () => {\n    await tail;\n    if (failed) {\n      failed = false;\n      throw new Error(\"Log stream drain failed\");\n    }\n  };\n  drain.close = async () => {\n    closed = true;\n    try {\n      await drain.flush();\n    } finally {\n      stream.off(\"error\", onError);\n    }\n  };\n  return drain;\n}\n"],"mappings":";;;;;AAqBA,SAAgB,kBAAkB,EAChC,SAAS,QAAQ,QACjB,aAAa,SACS,CAAC,GAAgB;CACvC,IAAI,OAAsB,QAAQ,QAAQ;CAC1C,IAAI,UAAU;CACd,IAAI,SAAS;CACb,IAAI,SAAS;CACb,MAAM,gBAAgB;EACpB,SAAS;CACX;CACA,OAAO,GAAG,SAAS,OAAO;CAE1B,MAAM,UAAU,YAAY;EAC1B,IAAI,QAAQ,OAAO,KAAA;EACnB,IAAI,WAAW,YAAY;GACzB,SAAS;GACT;EACF;EACA,IAAI;EACJ,IAAI;GACF,OAAO,GAAG,KAAK,UAAU,QAAQ,KAAK,EAAE;EAC1C,QAAQ;GACN,SAAS;GACT;EACF;EACA,WAAW;EACX,OAAO,KAAK,WAER,IAAI,SAAe,YAAY;GAC7B,MAAM,QAAQ,UAAyB;IACrC,IAAI,OAAO,SAAS;IACpB,WAAW;IACX,QAAQ;GACV;GACA,IAAI;IACF,OAAO,MAAM,MAAM,IAAI;GACzB,QAAQ;IACN,qBAAK,IAAI,MAAM,cAAc,CAAC;GAChC;EACF,CAAC,CACL;EACA,OAAO;CACT;CAEA,MAAM,QAAQ,YAAY;EACxB,MAAM;EACN,IAAI,QAAQ;GACV,SAAS;GACT,MAAM,IAAI,MAAM,yBAAyB;EAC3C;CACF;CACA,MAAM,QAAQ,YAAY;EACxB,SAAS;EACT,IAAI;GACF,MAAM,MAAM,MAAM;EACpB,UAAU;GACR,OAAO,IAAI,SAAS,OAAO;EAC7B;CACF;CACA,OAAO;AACT"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raypx-kit/logger",
-  "version": "0.0.0-alpha.0",
+  "version": "0.0.0-alpha.2",
   "description": "Evlog structured logging, wide events, drain pipelines and request-scoped context.",
   "homepage": "https://github.com/raypx/raypx-kit/tree/canary/packages/logger",
   "license": "Apache-2.0",
@@ -33,6 +33,14 @@
     "./pipeline": {
       "types": "./dist/pipeline.d.mts",
       "import": "./dist/pipeline.mjs"
+    },
+    "./safe": {
+      "types": "./dist/safe.d.mts",
+      "import": "./dist/safe.mjs"
+    },
+    "./stream": {
+      "types": "./dist/stream.d.mts",
+      "import": "./dist/stream.mjs"
     }
   },
   "publishConfig": {
@@ -47,7 +55,7 @@
     "test:coverage": "bun --bun vp test --run --passWithNoTests --coverage --coverage.reporter=text --coverage.reporter=json --coverage.reporter=lcov",
     "build": "tsdown",
     "dev": "tsdown --watch",
-    "pack:check": "bun pm pack --dry-run --ignore-scripts"
+    "pack:check": "bun pm pack --dry-run"
   },
   "dependencies": {
     "evlog": "^2.33.1"
@@ -56,6 +64,6 @@
     "@vitest/coverage-v8": "^5.0.5"
   },
   "engines": {
-    "node": ">=22.14"
+    "node": ">=22.21"
   }
 }