@adrianhall/cloudflare-toolkit 0.0.1

package/dist/silent-CWpHE65X.js

@@ -0,0 +1,652 @@
+import { r as valueOrDefault } from "./guards-6K1CVAr5.js";
+//#region src/lib/logging/levels.ts
+/**
+* Stable numeric weights for each log level.
+*
+* A record is emitted when: `LOG_LEVELS[record.level] >= LOG_LEVELS[logger.level]`
+*/
+const LOG_LEVELS = {
+	trace: 10,
+	debug: 20,
+	info: 30,
+	warn: 40,
+	error: 50,
+	fatal: 60
+};
+/**
+* Return the numeric weight for `level`.
+*
+* Throws a `TypeError` for any value that is not a recognized `LogLevel`. TypeScript consumers
+* should rely on the `LogLevel` union type and never reach this error path under normal usage.
+* Deliberately not implemented with `throwIfNull`: this throws a `TypeError` for an unrecognized
+* string, not a `null`/`undefined` guard, so using that helper would change the thrown error
+* type.
+*
+* @param level - The level to look up.
+* @returns The numeric weight for `level`.
+* @throws {TypeError} If `level` is not one of the six recognized `LogLevel` values.
+*/
+function levelValue(level) {
+	const value = LOG_LEVELS[level];
+	if (value === void 0) throw new TypeError(`Unknown log level: ${String(level)}. Expected one of: ${Object.keys(LOG_LEVELS).join(", ")}`);
+	return value;
+}
+//#endregion
+//#region src/lib/logging/internal/optional-field.ts
+/**
+* @file An internal helper for the logging subpath — not one of the toolkit's public defensive
+* guards (`src/lib/guards`) and not exported from `src/lib/logging/index.ts`.
+*/
+/**
+* Returns `{ [prop]: o[prop] }` when `prop` is an own property of `o` with a non-`undefined`
+* value, otherwise returns `{}`.
+*
+* Intended for safely spreading optional fields onto plain objects without introducing
+* `undefined`-valued keys:
+*
+* ```ts
+* const result = {
+*   name: err.name,
+*   ...optionalField(err, "stack"),
+* };
+* ```
+*
+* @param o - The object to read `prop` from.
+* @param prop - The property to conditionally include.
+* @returns `{ [prop]: o[prop] }` when defined, otherwise `{}`.
+*/
+function optionalField(o, prop) {
+	return o[prop] !== void 0 ? { [prop]: o[prop] } : {};
+}
+//#endregion
+//#region src/lib/logging/serialize.ts
+/**
+* @file Error serialization for the logging subpath.
+*
+* `serializeError()` converts `Error` instances to plain objects so transports can safely
+* forward structured context without raw `Error` values escaping into JSON serialization or
+* console methods. Only top-level context values are serialized by the logger (`logger.ts`);
+* nested errors are left as-is unless they appear as a direct `cause` of a top-level error.
+*/
+/**
+* Serialize `value` if it is an `Error`; return it unchanged otherwise.
+*
+* - Non-`Error` values are returned as-is.
+* - `Error` instances become plain objects with `name`, `message`, and optionally `stack` and
+*   `cause`.
+* - `cause` is shallowly serialized when it is itself an `Error`.
+*
+* @param value - The value to serialize, if it is an `Error`.
+* @returns A plain-object serialization of `value` when it is an `Error`, otherwise `value`
+*   unchanged.
+*/
+function serializeError(value) {
+	if (!(value instanceof Error)) return value;
+	const serialized = {
+		name: value.name,
+		message: value.message,
+		...optionalField(value, "stack")
+	};
+	if (value.cause !== void 0) serialized.cause = value.cause instanceof Error ? {
+		name: value.cause.name,
+		message: value.cause.message,
+		...optionalField(value.cause, "stack")
+	} : value.cause;
+	return serialized;
+}
+//#endregion
+//#region src/lib/logging/logger.ts
+/**
+* @file The core logger implementation. This is the framework-agnostic core that the
+* `cloudflareLogger` Hono middleware wraps — it must never import `hono`.
+*
+* `createLogger()` constructs a `Logger` that:
+*   - Filters records below the configured level before touching context.
+*   - Merges bindings and per-call context into a new object (never mutates input).
+*   - Serializes top-level `Error` values in context before delivering to transport.
+*   - Wraps transport delivery in try/catch so transport failures never escape.
+*   - Supports child loggers that inherit transport, level, clock, and error handler.
+*/
+/**
+* Internal factory used by both `createLogger` and child loggers.
+*
+* All logger state is captured in the closure; no class is used. Both root loggers and child
+* loggers are created through this function, which keeps the child creation path identical to
+* the root path.
+*
+* @param level - Minimum level to emit.
+* @param transport - Destination for emitted records.
+* @param bindings - Key-value pairs merged into every record's context.
+* @param clock - Produces the timestamp for each record.
+* @param onTransportError - Optional callback for transport failures.
+* @returns A `Logger` bound to the supplied state.
+*/
+function makeLogger(level, transport, bindings, clock, onTransportError) {
+	const currentLevelValue = levelValue(level);
+	/**
+	* Returns `true` when records at `candidate` severity will be emitted. Used both for the
+	* public `isLevelEnabled` method and internally before constructing a record.
+	*
+	* @param candidate - The level to test against the configured minimum level.
+	* @returns `true` when `candidate` is at or above the configured minimum level.
+	*/
+	function isLevelEnabled(candidate) {
+		return levelValue(candidate) >= currentLevelValue;
+	}
+	/**
+	* Core emit path shared by all six level methods.
+	*
+	* Exits immediately when `logLevel` is below the configured minimum so that disabled calls
+	* never access the `context` argument. When enabled, merges bindings with per-call context,
+	* serializes top-level `Error` values, builds the `LogRecord`, and delivers it to the
+	* transport inside a try/catch.
+	*
+	* @param logLevel - Severity of this record.
+	* @param message - Human-readable description of the event.
+	* @param context - Optional per-call structured context.
+	*/
+	function emit(logLevel, message, context) {
+		if (!isLevelEnabled(logLevel)) return;
+		const merged = context !== void 0 ? {
+			...bindings,
+			...context
+		} : { ...bindings };
+		const serializedContext = {};
+		for (const key of Object.keys(merged)) serializedContext[key] = serializeError(merged[key]);
+		const record = {
+			time: clock().toISOString(),
+			level: logLevel,
+			levelValue: levelValue(logLevel),
+			message,
+			context: serializedContext
+		};
+		try {
+			transport.log(record);
+		} catch (error) {
+			try {
+				onTransportError?.(error, record);
+			} catch {}
+		}
+	}
+	return {
+		get level() {
+			return level;
+		},
+		isLevelEnabled,
+		trace(message, context) {
+			emit("trace", message, context);
+		},
+		debug(message, context) {
+			emit("debug", message, context);
+		},
+		info(message, context) {
+			emit("info", message, context);
+		},
+		warn(message, context) {
+			emit("warn", message, context);
+		},
+		error(message, context) {
+			emit("error", message, context);
+		},
+		fatal(message, context) {
+			emit("fatal", message, context);
+		},
+		child(childBindings) {
+			return makeLogger(level, transport, {
+				...bindings,
+				...childBindings
+			}, clock, onTransportError);
+		}
+	};
+}
+/**
+* Create a new `Logger` with the provided options.
+*
+* - `options.transport` is required.
+* - `options.level` defaults to `"info"`.
+* - `options.clock` defaults to `() => new Date()`.
+* - `options.bindings` are merged into every emitted record.
+* - `options.onTransportError` receives transport errors without crashing the app.
+*
+* @param options - Logger construction options.
+* @returns A new `Logger`.
+*/
+function createLogger(options) {
+	const { transport, level = "info", bindings = {}, clock = () => /* @__PURE__ */ new Date(), onTransportError } = options;
+	return makeLogger(level, transport, bindings, clock, onTransportError);
+}
+//#endregion
+//#region src/lib/logging/internal/console.ts
+/**
+* Return the named console method from `c`, falling back to `c.log` if the method is absent or
+* not a function.
+*
+* Rationale: logging must not crash because a host environment is missing a specific console
+* method. `console.log` is the safest baseline and is present in every JS environment that
+* supports `console` at all.
+*
+* @param c - The console-like object to query.
+* @param method - The preferred method name.
+* @returns The requested method if callable, otherwise `c.log`.
+*/
+function getConsoleMethod(c, method) {
+	const candidate = c[method];
+	if (typeof candidate === "function") return candidate.bind(c);
+	return c.log.bind(c);
+}
+//#endregion
+//#region src/lib/logging/transports/browser.ts
+/**
+* @file A transport that formats records for browser DevTools using `%c` styled level badges.
+*
+* `createBrowserTransport()` maps severity levels to appropriate console methods and passes the
+* context object as a separate argument when non-empty, so DevTools can expand it interactively.
+*
+* Level-to-method mapping:
+*   trace, debug → console.debug
+*   info          → console.info
+*   warn          → console.warn
+*   error, fatal  → console.error
+*/
+/** Default CSS badge styles keyed by level. */
+const DEFAULT_STYLES = {
+	trace: "color: #9ca3af; font-weight: bold",
+	debug: "color: #6b7280; font-weight: bold",
+	info: "color: #3b82f6; font-weight: bold",
+	warn: "color: #f59e0b; font-weight: bold",
+	error: "color: #ef4444; font-weight: bold",
+	fatal: "color: #dc2626; font-weight: bold; text-decoration: underline"
+};
+/** Map each log level to the preferred console method name. */
+const LEVEL_METHOD$1 = {
+	trace: "debug",
+	debug: "debug",
+	info: "info",
+	warn: "warn",
+	error: "error",
+	fatal: "error"
+};
+/**
+* Create a browser transport optimized for DevTools output.
+*
+* @param options - Optional level style overrides.
+* @param _console - Injected console-like object (defaults to global `console`). Used in tests.
+* @returns A `Transport` that writes styled records to the browser console.
+*/
+function createBrowserTransport(options, _console = console) {
+	const levelStyles = {
+		...DEFAULT_STYLES,
+		...options?.levelStyles
+	};
+	return { log(record) {
+		const methodName = LEVEL_METHOD$1[record.level];
+		const method = getConsoleMethod(_console, methodName);
+		const style = levelStyles[record.level];
+		const badge = record.level.toUpperCase();
+		if (Object.keys(record.context).length > 0) method(`%c${badge}`, style, record.message, record.context);
+		else method(`%c${badge}`, style, record.message);
+	} };
+}
+//#endregion
+//#region src/lib/logging/transports/capture.ts
+/**
+* Create a capture transport that stores records in memory.
+*
+* @returns A `CaptureTransport` with `.records`, `.clear()`, and `.find()`.
+*/
+function createCaptureTransport() {
+	let internal = [];
+	return {
+		log(record) {
+			internal.push(record);
+		},
+		get records() {
+			return internal.slice();
+		},
+		clear() {
+			internal = [];
+		},
+		find(level) {
+			return internal.filter((r) => r.level === level);
+		}
+	};
+}
+//#endregion
+//#region src/lib/logging/internal/safe-json.ts
+/**
+* @file Internal safe JSON/string formatting for the logging subpath. Not exported from
+* `src/lib/logging/index.ts`; used by `createConsoleTransport` and `createStructuredTransport`.
+*
+* `safeStringify()` serializes arbitrary values to a compact JSON string while handling the
+* common non-JSON types that appear in structured log context:
+*   - Circular references  → `"[Circular]"` (a shared/diamond reference reachable via two
+*     non-nested paths — e.g. `{ a: shared, b: shared }` — is NOT a circular reference and is
+*     serialized in full at both locations; only true ancestor cycles are replaced)
+*   - `bigint`             → `"<n>n"` (e.g. `42n` → `"42n"`)
+*   - `symbol`             → `"Symbol(description)"`
+*   - `function`           → `"[Function name]"` or `"[Function (anonymous)]"`
+*   - `undefined`          → omitted from objects, `"undefined"` at top level
+*/
+/**
+* A stable placeholder emitted when `JSON.stringify` itself throws unexpectedly (e.g. a getter
+* that throws mid-serialization after the circular-reference check has passed).
+*/
+const FALLBACK = "[FormattingError]";
+/**
+* Convert a single value to a JSON-safe replacement.
+*
+* Called from the `JSON.stringify` replacer for every value encountered during serialization.
+* Non-JSON-safe primitives (`bigint`, `symbol`, `function`) are converted to descriptive
+* strings. All other values are returned unchanged so that `JSON.stringify` handles them
+* normally.
+*
+* Exported for direct unit testing so the default return path is reachable without going
+* through the full replacer loop.
+*
+* @param value - The raw value at the current key.
+* @returns A JSON-safe replacement value.
+*/
+function replaceNonJsonValue(value) {
+	if (typeof value === "bigint") return `${value.toString()}n`;
+	if (typeof value === "symbol") return value.toString();
+	if (typeof value === "function") {
+		const name = value.name;
+		return name ? `[Function ${name}]` : "[Function (anonymous)]";
+	}
+	return value;
+}
+/**
+* Serialize `value` to a compact JSON string.
+*
+* Handles:
+* - Circular references (replaced with `"[Circular]"`); shared/diamond references (the same
+*   object reachable via two different, non-nested paths) are NOT treated as circular and are
+*   serialized in full at every location
+* - `bigint` (serialized as `"<n>n"`)
+* - `symbol` (serialized as `"Symbol(description)"`)
+* - `function` (serialized as `"[Function name]"`)
+* - `undefined` at the top level (returns `"undefined"`)
+* - Unexpected formatter errors (returns `"[FormattingError]"`)
+*
+* @param value - The value to serialize.
+* @returns A JSON string representation.
+*/
+function safeStringify(value) {
+	if (value === void 0) return "undefined";
+	const stack = [];
+	try {
+		return JSON.stringify(value, function replacer(_key, val) {
+			if (typeof val === "bigint" || typeof val === "symbol" || typeof val === "function") return replaceNonJsonValue(val);
+			if (val !== null && typeof val === "object") {
+				const holderIndex = stack.indexOf(this);
+				if (holderIndex === -1) stack.push(this);
+				else stack.length = holderIndex + 1;
+				if (stack.includes(val)) return "[Circular]";
+				stack.push(val);
+			}
+			return val;
+		});
+	} catch {
+		return FALLBACK;
+	}
+}
+//#endregion
+//#region src/lib/logging/internal/sanitize.ts
+/**
+* @file An internal helper for the logging subpath — not exported from
+* `src/lib/logging/index.ts`.
+*
+* `sanitizeTerminalText()` neutralizes terminal-injection risk (SEC-007) in strings that are
+* about to be written to a real terminal by `createConsoleTransport()`. `record.message` is
+* caller-supplied and may embed attacker-controlled data (e.g. an email address or path). Left
+* unescaped, it could contain newlines that forge fake log lines, or ANSI escape sequences
+* (`\x1b...`) that manipulate the terminal (colors, cursor movement, title changes) when the
+* output is later viewed through a real terminal such as `wrangler tail`.
+*
+* `record.context` does not need the same treatment: `createConsoleTransport()` always renders
+* it via `safeStringify()` (`JSON.stringify` under the hood), which already escapes every C0
+* control character — including `\x1b` — as `\uXXXX` per the JSON spec.
+*/
+/**
+* Control characters (C0: `\x00`-`\x1f`, plus DEL `\x7f`) that could forge terminal output or
+* trigger ANSI escape sequences. Every terminal escape sequence begins with `\x1b` (ESC), so
+* escaping it alone is sufficient to neutralize ANSI injection; the rest of the range is
+* escaped defensively for the same reason.
+*/
+const CONTROL_CHAR_PATTERN = /[\x00-\x1f\x7f]/g;
+/** Readable escape sequences for the most common control characters. */
+const NAMED_ESCAPES = {
+	"\n": "\\n",
+	"\r": "\\r",
+	"	": "\\t"
+};
+/**
+* Replace every C0 control character and DEL in `value` with a visible, non-executable escape
+* sequence.
+*
+* Common whitespace controls (`\n`, `\r`, `\t`) are rendered as their familiar backslash
+* escapes; every other control character (including ESC, `\x1b`) is rendered as a two-digit hex
+* escape (`\xHH`). This preserves the original information for debugging while preventing the
+* string from forging additional log lines or executing terminal escape sequences.
+*
+* @param value - The raw string to sanitize before writing it to a terminal.
+* @returns `value` with every control character replaced by a visible escape sequence.
+*/
+function sanitizeTerminalText(value) {
+	return value.replace(CONTROL_CHAR_PATTERN, (char) => {
+		const named = NAMED_ESCAPES[char];
+		if (named !== void 0) return named;
+		return `\\x${char.charCodeAt(0).toString(16).padStart(2, "0")}`;
+	});
+}
+//#endregion
+//#region src/lib/logging/transports/console.ts
+/**
+* @file A transport that formats records as human-readable single-line output intended for
+* terminal environments including `wrangler dev`.
+*
+* `createConsoleTransport()` supports optional ANSI color codes and configurable timestamp
+* formats.
+*
+* `record.message` is sanitized via `sanitizeTerminalText()` (SEC-007) before it is written,
+* escaping control/ANSI characters so caller-supplied data cannot forge additional log lines or
+* inject terminal escape sequences when the output is later viewed in a real terminal (e.g.
+* `wrangler tail`).
+*
+* Level-to-method mapping:
+*   trace, debug, info  → console.log
+*   warn, error, fatal  → console.error
+*
+* Output format:
+*   [timestamp] LEVEL  message [{"key":"value"}]
+*/
+const RESET = "\x1B[0m";
+/** Map each level to its ANSI color code. */
+const LEVEL_COLOR = {
+	trace: "\x1B[90m",
+	debug: "\x1B[37m",
+	info: "\x1B[36m",
+	warn: "\x1B[33m",
+	error: "\x1B[31m",
+	fatal: "\x1B[35m"
+};
+/**
+* Extract an `HH:MM:SS` time string from an ISO 8601 timestamp. Falls back to the first 8
+* characters if the expected `T` separator is absent.
+*
+* Exported for direct unit testing of the fallback branch.
+*
+* @param isoString - An ISO 8601 timestamp string.
+* @returns The `HH:MM:SS` portion, or the first 8 characters if no `T` separator is found.
+*/
+function extractTime(isoString) {
+	const tIndex = isoString.indexOf("T");
+	if (tIndex === -1) return isoString.slice(0, 8);
+	return isoString.slice(tIndex + 1, tIndex + 9);
+}
+/** Fixed-width (5 chars) uppercase level labels. */
+const LEVEL_LABEL = {
+	trace: "TRACE",
+	debug: "DEBUG",
+	info: "INFO ",
+	warn: "WARN ",
+	error: "ERROR",
+	fatal: "FATAL"
+};
+/**
+* Create a console transport for terminal/wrangler dev output.
+*
+* @param options - Timestamp and color options.
+* @param _console - Injected console-like object (defaults to global `console`). Used in tests.
+* @returns A `Transport` that writes formatted lines to the terminal.
+*/
+function createConsoleTransport(options, _console = console) {
+	const colors = valueOrDefault(options?.colors, true);
+	const timestamp = valueOrDefault(options?.timestamp, "time");
+	return { log(record) {
+		const method = getConsoleMethod(_console, record.level === "warn" || record.level === "error" || record.level === "fatal" ? "error" : "log");
+		const parts = [];
+		if (timestamp === "time") {
+			const ts = extractTime(record.time);
+			parts.push(colors ? `\x1b[90m${ts}${RESET}` : ts);
+		} else if (timestamp === "iso") parts.push(colors ? `\x1b[90m${record.time}${RESET}` : record.time);
+		const label = LEVEL_LABEL[record.level];
+		if (colors) {
+			const color = LEVEL_COLOR[record.level];
+			parts.push(`${color}${label}${RESET}`);
+		} else parts.push(label);
+		parts.push(sanitizeTerminalText(record.message));
+		if (Object.keys(record.context).length > 0) parts.push(safeStringify(record.context));
+		method(parts.join(" "));
+	} };
+}
+//#endregion
+//#region src/lib/logging/transports/structured.ts
+/**
+* @file A transport that emits records as structured payloads intended for Cloudflare Workers
+* Logs.
+*
+* Workers Logs automatically extracts and indexes fields from JSON object logs, so
+* `createStructuredTransport()` defaults to object logging (`stringify: false`) rather than
+* string logging.
+*
+* Payload shape: `{ time, level, message, ...context }`
+* Reserved keys (`time`, `level`, `message`) from the record take precedence over identically
+* named context keys.
+*
+* Level-to-method mapping:
+*   trace, debug → console.debug
+*   info          → console.log
+*   warn          → console.warn
+*   error, fatal  → console.error
+*/
+/** Map each log level to the preferred console method name. */
+const LEVEL_METHOD = {
+	trace: "debug",
+	debug: "debug",
+	info: "log",
+	warn: "warn",
+	error: "error",
+	fatal: "error"
+};
+/**
+* Create a structured transport for Cloudflare Workers Logs.
+*
+* @param options - Optional stringify flag.
+* @param _console - Injected console-like object (defaults to global `console`). Used in tests.
+* @returns A `Transport` that writes structured payloads to the console.
+*/
+function createStructuredTransport(options, _console = console) {
+	const stringify = valueOrDefault(options?.stringify, false);
+	return { log(record) {
+		const methodName = LEVEL_METHOD[record.level];
+		const method = getConsoleMethod(_console, methodName);
+		const payload = {
+			...record.context,
+			time: record.time,
+			level: record.level,
+			message: record.message
+		};
+		if (stringify) method(safeStringify(payload));
+		else method(payload);
+	} };
+}
+//#endregion
+//#region src/lib/logging/resolve.ts
+/**
+* @file A default-config helper that maps an environment + runtime pair to a ready-to-use
+* `{ level, transport }` pair.
+*
+* `resolveLoggerConfig()` is optional policy — `createLogger` does not require it. Applications
+* that need environment-specific configuration without hand-wiring transports can call this
+* helper and pass the result directly to `createLogger`.
+*
+* Policy table:
+*
+* | Environment   | Runtime   | Level   | Transport  |
+* |---------------|-----------|---------|------------|
+* | test          | browser   | trace   | capture    |
+* | test          | worker    | trace   | capture    |
+* | development   | browser   | info    | browser    |
+* | development   | worker    | debug   | console    |
+* | production    | browser   | warn    | browser    |
+* | production    | worker    | warn    | structured |
+* | unknown       | browser   | warn    | browser    |
+* | unknown       | worker    | warn    | structured |
+*
+* There is no `detectRuntime()` helper in the public API. Applications are expected to know
+* whether they are constructing a browser logger or a Worker logger.
+*/
+/**
+* Resolve a `{ level, transport }` configuration for the given environment and runtime.
+*
+* Each call creates a **fresh** transport instance. If you call this helper more than once with
+* the same arguments you will receive independent transport instances, which is intentional for
+* test isolation.
+*
+* Unknown or `undefined` environments are treated as `"production"`.
+*
+* @param environment - One of `"test"`, `"development"`, `"production"`, or any other string.
+*   `undefined` maps to production behavior.
+* @param runtime - Either `"browser"` or `"worker"`.
+* @returns A fresh `ResolvedLoggerConfig` ready to pass to `createLogger`.
+*/
+function resolveLoggerConfig(environment, runtime) {
+	const env = environment === "test" || environment === "development" ? environment : "production";
+	if (env === "test") return {
+		level: "trace",
+		transport: createCaptureTransport()
+	};
+	if (env === "development") {
+		if (runtime === "browser") return {
+			level: "info",
+			transport: createBrowserTransport()
+		};
+		return {
+			level: "debug",
+			transport: createConsoleTransport()
+		};
+	}
+	if (runtime === "browser") return {
+		level: "warn",
+		transport: createBrowserTransport()
+	};
+	return {
+		level: "warn",
+		transport: createStructuredTransport()
+	};
+}
+//#endregion
+//#region src/lib/logging/transports/silent.ts
+/**
+* Create a silent transport that discards all records.
+*
+* @returns A `Transport` that does nothing.
+*/
+function createSilentTransport() {
+	return { log() {} };
+}
+//#endregion
+export { createCaptureTransport as a, serializeError as c, createConsoleTransport as i, resolveLoggerConfig as n, createBrowserTransport as o, createStructuredTransport as r, createLogger as s, createSilentTransport as t };
+
+//# sourceMappingURL=silent-CWpHE65X.js.map