@timber-js/app 0.2.0-alpha.204 → 0.2.0-alpha.205

package/dist/_chunks/{logger-DqJ2VoAY.js → primitives-DLAnvsrk.js}

@@ -1,217 +1,29 @@
-import { o as traceAls, r as requestContextAls, s as waitUntilAls } from "./als-registry-C6kcfprT.js";
+import { r as requestContextAls, s as waitUntilAls } from "./als-registry-C6kcfprT.js";
 import { n as _setGetSegmentParamsFn, t as _setGetSearchParamsFn } from "./als-slots-BEEIPKYm.js";
 import { a as assertValidCookieOptions, i as assertValidCookieName, n as parseSetCookie$1, o as assertValidCookieValue, r as stringifySetCookie, t as parseCookie } from "./dist-DtrJyBbw.js";
 import { r as appVisibleSearch } from "./rsc-cache-key-ClUiXQnK.js";
 import { a as mergePreservedSearchParams, o as resolveSegmentParams, r as validateExternalRedirectUrl, t as assertRelativeRedirectPath } from "./href-validation-BIrxavIy.js";
-import { randomUUID } from "node:crypto";
-//#region src/server/tracing.ts
-/**
-* Tracing — per-request trace ID via AsyncLocalStorage, OTEL span helpers.
-*
-* getTraceId() is always available in server code (middleware, access, components, actions).
-* Returns a 32-char lowercase hex string — the OTEL trace ID when an SDK is active,
-* or a crypto.randomUUID()-derived fallback otherwise.
-*
-* See design/17-logging.md §"trace_id is Always Set"
-*/
+//#region src/server/waituntil-bridge.ts
 /**
-* Returns the current request's trace ID — always a 32-char lowercase hex string.
-*
-* With OTEL: the real OTEL trace ID (matches Jaeger/Honeycomb/Datadog).
-* Without OTEL: crypto.randomUUID() with hyphens stripped.
+* Per-request waitUntil bridge — ALS bridge for platform adapters.
 *
-* Throws if called outside a request context (no ALS store).
-*/
-function getTraceId() {
-	const store = traceAls.getStore();
-	if (!store) throw new Error("[timber] getTraceId() called outside of a request context. It can only be used in middleware, access checks, server components, and server actions.");
-	return store.traceId;
-}
-/**
-* Returns the current OTEL span ID if available, undefined otherwise.
-*/
-function getSpanId() {
-	return traceAls.getStore()?.spanId;
-}
-/**
-* Generate a 32-char lowercase hex ID from crypto.randomUUID().
-* Same format as OTEL trace IDs — zero-friction upgrade path.
-*/
-function generateTraceId() {
-	return randomUUID().replace(/-/g, "");
-}
-/**
-* Run a callback within a trace context. Used by the pipeline to establish
-* per-request ALS scope.
-*/
-function runWithTraceId(id, fn) {
-	return traceAls.run({ traceId: id }, fn);
-}
-/**
-* Replace the trace ID in the current ALS store. Used when OTEL creates
-* a root span and we want to switch from the UUID fallback to the real
-* OTEL trace ID.
-*/
-function replaceTraceId(newTraceId, newSpanId) {
-	const store = traceAls.getStore();
-	if (store) {
-		store.traceId = newTraceId;
-		store.spanId = newSpanId;
-	}
-}
-/**
-* Update the span ID in the current ALS store. Used when entering a new
-* OTEL span to keep log–trace correlation accurate.
-*/
-function updateSpanId(newSpanId) {
-	const store = traceAls.getStore();
-	if (store) store.spanId = newSpanId;
-}
-/**
-* Get the current trace store, or undefined if outside a request context.
-* Framework-internal — use getTraceId()/getSpanId() in user code.
-*/
-function getTraceStore() {
-	return traceAls.getStore();
-}
-var PLATFORM_TRACER_KEY = Symbol.for("timber:platform-tracer");
-/** The registered native platform tracer, if any. */
-function getPlatformTracer() {
-	return globalThis[PLATFORM_TRACER_KEY];
-}
-/**
-* Attempt to get the @opentelemetry/api tracer. Returns undefined if the
-* package is not installed or no SDK is registered.
+* The generated entry point (Nitro, Cloudflare) wraps the handler with
+* `runWithWaitUntil`, binding the platform's lifecycle extension function
+* (e.g., h3's `event.waitUntil()` or CF's `ctx.waitUntil()`) for the
+* request duration. The `waitUntil()` primitive reads from this ALS to
+* dispatch background work to the correct platform API.
 *
-* timber.js depends on @opentelemetry/api as the vendor-neutral interface.
-* The API is a no-op by default — spans are only emitted when the developer
-* initializes an SDK in register().
-*/
-var _otelApi;
-async function getOtelApi() {
-	if (_otelApi === void 0) try {
-		_otelApi = await import("@opentelemetry/api");
-	} catch {
-		_otelApi = null;
-	}
-	return _otelApi;
-}
-/** OTEL tracer instance, lazily created. */
-var _tracer;
-/**
-* Get the timber.js OTEL tracer. Returns null if @opentelemetry/api is not available.
-*/
-async function getTracer() {
-	if (_tracer === void 0) {
-		const api = await getOtelApi();
-		if (api) _tracer = api.trace.getTracer("timber.js");
-		else _tracer = null;
-	}
-	return _tracer;
-}
-/**
-* Run a function within a framework span. Composes two emission channels:
-*
-* - **Native platform span** — when an adapter registered a PlatformTracer
-*   (Cloudflare Workers), the fn is wrapped in platformTracer.enterSpan()
-*   so it appears in the platform's native trace view.
-* - **OTEL span** — when an OTEL SDK is active, the fn also runs inside an
-*   OTEL span (dual emission). No SDK and no platform tracer = zero overhead.
-*
-* Automatically:
-* - Creates the span as a child of the current context
-* - Updates the ALS span ID for log–trace correlation
-* - Ends the span when the function completes
-* - Records exceptions on error (OTEL channel)
-*/
-async function withSpan(name, attributes, fn) {
-	const platformTracer = getPlatformTracer();
-	if (!platformTracer) return runOtelSpan(name, attributes, fn);
-	return platformTracer.enterSpan(name, async (span) => {
-		for (const key of Object.keys(attributes)) span.setAttribute(key, attributes[key]);
-		const store = traceAls.getStore();
-		const prevPlatformSpan = store?.platformSpan;
-		if (store) store.platformSpan = span;
-		try {
-			return await runOtelSpan(name, attributes, fn);
-		} finally {
-			if (store) store.platformSpan = prevPlatformSpan;
-		}
-	});
-}
-/** The OTEL half of withSpan() — no-op passthrough when no SDK is active. */
-async function runOtelSpan(name, attributes, fn) {
-	const tracer = await getTracer();
-	if (!tracer) return fn();
-	const api = await getOtelApi();
-	return tracer.startActiveSpan(name, { attributes }, async (span) => {
-		const prevSpanId = getSpanId();
-		updateSpanId(span.spanContext().spanId);
-		try {
-			const result = await fn();
-			span.setStatus({ code: api.SpanStatusCode.OK });
-			return result;
-		} catch (error) {
-			span.setStatus({ code: api.SpanStatusCode.ERROR });
-			if (error instanceof Error) span.recordException(error);
-			throw error;
-		} finally {
-			span.end();
-			updateSpanId(prevSpanId);
-		}
-	});
-}
-/**
-* Set an attribute on the current active span (if any).
-* Used for setting span attributes after span creation (e.g. timber.result on access spans).
-*/
-async function setSpanAttribute(key, value) {
-	const platformSpan = traceAls.getStore()?.platformSpan;
-	if (platformSpan) platformSpan.setAttribute(key, value);
-	const api = await getOtelApi();
-	if (!api) return;
-	const activeSpan = api.trace.getActiveSpan();
-	if (activeSpan) activeSpan.setAttribute(key, value);
-}
-/**
-* Add a span event to the current active span (if any).
-* Used for timber.cache HIT/MISS events — recorded as span events, not child spans.
+* Design doc: design/11-platform.md §"waitUntil()"
 */
-async function addSpanEvent(name, attributes) {
-	const api = await getOtelApi();
-	if (!api) return;
-	const activeSpan = api.trace.getActiveSpan();
-	if (activeSpan) activeSpan.addEvent(name, attributes);
-}
 /**
-* Fire-and-forget span event — no await, no microtask overhead.
-*
-* Used on the cache hot path where awaiting addSpanEvent creates an
-* unnecessary microtask per cache operation. If OTEL is not loaded yet,
-* the event is silently dropped (acceptable for diagnostics).
+* Get the current request's waitUntil function, if available.
 *
-* See TIM-370 for perf motivation.
-*/
-function addSpanEventSync(name, attributes) {
-	if (!_otelApi) return;
-	const activeSpan = _otelApi.trace.getActiveSpan();
-	if (activeSpan) activeSpan.addEvent(name, attributes);
-}
-/**
-* Try to extract the OTEL trace ID from the current active span context.
-* Returns undefined if OTEL is not active or no span exists.
+* Returns undefined when no platform adapter has installed a waitUntil
+* handler for the current request (e.g., on platforms that don't support
+* lifecycle extension, or outside a request context).
 */
-async function getOtelTraceId() {
-	const api = await getOtelApi();
-	if (!api) return void 0;
-	const activeSpan = api.trace.getActiveSpan();
-	if (!activeSpan) return void 0;
-	const ctx = activeSpan.spanContext();
-	if (!ctx.traceId || ctx.traceId === "00000000000000000000000000000000") return;
-	return {
-		traceId: ctx.traceId,
-		spanId: ctx.spanId
-	};
+function getWaitUntil() {
+	return waitUntilAls.getStore();
 }
 //#endregion
 //#region src/server/debug.ts
@@ -319,211 +131,6 @@ function _readTimberDebugEnv() {
 	return false;
 }
 //#endregion
-//#region src/server/error-formatter.ts
-/**
-* Error Formatter — rewrites SSR/RSC error messages to surface user code.
-*
-* When React or Vite throw errors during SSR, stack traces reference
-* vendored dependency paths (e.g. `.vite/deps_ssr/@vitejs_plugin-rsc_vendor_...`)
-* and mangled export names (`__vite_ssr_export_default__`). This module
-* rewrites error messages and stack traces to point at user code instead.
-*
-* Dev-only — in production, errors go through the structured logger
-* without formatting.
-*/
-/**
-* Patterns that identify internal Vite/RSC vendor paths in stack traces.
-* These are replaced with human-readable labels.
-*/
-var VENDOR_PATH_PATTERNS = [
-	{
-		pattern: /node_modules\/\.vite\/deps_ssr\/@vitejs_plugin-rsc_vendor_react-server-dom[^\s)]+/g,
-		replacement: "<react-server-dom>"
-	},
-	{
-		pattern: /node_modules\/\.vite\/deps_ssr\/@vitejs_plugin-rsc_vendor[^\s)]+/g,
-		replacement: "<rsc-vendor>"
-	},
-	{
-		pattern: /node_modules\/\.vite\/deps_ssr\/[^\s)]+/g,
-		replacement: "<vite-dep>"
-	},
-	{
-		pattern: /node_modules\/\.vite\/deps\/[^\s)]+/g,
-		replacement: "<vite-dep>"
-	}
-];
-/**
-* Patterns that identify Vite-mangled export names in error messages.
-*/
-var MANGLED_NAME_PATTERNS = [{
-	pattern: /__vite_ssr_export_default__/g,
-	replacement: "<default export>"
-}, {
-	pattern: /__vite_ssr_export_(\w+)__/g,
-	replacement: "<export $1>"
-}];
-/**
-* Rewrite an error's message and stack to replace internal Vite paths
-* and mangled names with human-readable labels.
-*/
-function formatSsrError(error) {
-	if (!(error instanceof Error)) return String(error);
-	let message = error.message;
-	let stack = error.stack ?? "";
-	for (const { pattern, replacement } of MANGLED_NAME_PATTERNS) message = message.replace(pattern, replacement);
-	for (const { pattern, replacement } of VENDOR_PATH_PATTERNS) stack = stack.replace(pattern, replacement);
-	for (const { pattern, replacement } of MANGLED_NAME_PATTERNS) stack = stack.replace(pattern, replacement);
-	const hint = extractErrorHint(error.message);
-	const parts = [];
-	parts.push(message);
-	if (hint) parts.push(`  → ${hint}`);
-	const userFrames = extractUserFrames(stack);
-	if (userFrames.length > 0) {
-		parts.push("");
-		parts.push("  User code in stack:");
-		for (const frame of userFrames) parts.push(`    ${frame}`);
-	}
-	return parts.join("\n");
-}
-/**
-* Extract a human-readable hint from common React/RSC error messages.
-*
-* React error messages contain useful information but the surrounding
-* context (vendor paths, mangled names) obscures it. This extracts the
-* actionable part as a one-line hint.
-*/
-function extractErrorHint(message) {
-	if (message.match(/Functions cannot be passed directly to Client Components/)) {
-		const propMatch = message.match(/<[^>]*?\s(\w+)=\{function/);
-		if (propMatch) return `Prop "${propMatch[1]}" is a function — mark it "use server" or call it before passing`;
-		return "A function prop was passed to a Client Component — mark it \"use server\" or call it before passing";
-	}
-	if (message.includes("Objects are not valid as a React child")) return "An object was rendered as JSX children — convert to string or extract the value";
-	const nullRefMatch = message.match(/Cannot read propert(?:y|ies) of (undefined|null) \(reading '(\w+)'\)/);
-	if (nullRefMatch) return `Accessed .${nullRefMatch[2]} on ${nullRefMatch[1]} — check that the value exists`;
-	const notFnMatch = message.match(/(\w+) is not a function/);
-	if (notFnMatch) return `"${notFnMatch[1]}" is not a function — check imports and exports`;
-	if (message.includes("Element type is invalid")) return "A component resolved to undefined/null — check default exports and import paths";
-	if (message.includes("Invalid hook call")) return "A hook was called outside of a React component render. If this is a 'use client' component, ensure the directive is at the very top of the file (before any imports) and that @vitejs/plugin-rsc is loaded correctly. Barrel re-exports from non-'use client' files do not propagate the directive.";
-	return null;
-}
-/**
-* Extract stack frames that reference user code (not node_modules,
-* not framework internals).
-*
-* Returns at most 5 frames to keep output concise.
-*/
-function extractUserFrames(stack) {
-	const lines = stack.split("\n");
-	const userFrames = [];
-	for (const line of lines) {
-		const trimmed = line.trim();
-		if (!trimmed.startsWith("at ")) continue;
-		if (trimmed.includes("node_modules") || trimmed.includes("<react-server-dom>") || trimmed.includes("<rsc-vendor>") || trimmed.includes("<vite-dep>") || trimmed.includes("node:internal")) continue;
-		userFrames.push(trimmed);
-		if (userFrames.length >= 5) break;
-	}
-	return userFrames;
-}
-//#endregion
-//#region src/server/default-logger.ts
-/**
-* DefaultLogger — human-readable stderr logging when no custom logger is configured.
-*
-* Ships as the fallback so production deployments always have error visibility,
-* even without an `instrumentation.ts` logger export. Output is one line per
-* event, designed for `fly logs`, `kubectl logs`, Cloudflare dashboard tails, etc.
-*
-* Format:
-*   [timber] ERROR  message  key=value key=value  trace_id=4bf92f35
-*   [timber] WARN   message  key=value key=value  trace_id=4bf92f35
-*   [timber] INFO   message  method=GET path=/dashboard status=200 durationMs=43  trace_id=4bf92f35
-*
-* Behavior:
-* - Suppressed entirely in dev mode (dev logging handles all output)
-* - `debug` suppressed unless TIMBER_DEBUG is set
-* - Replaced entirely when a custom logger is set via `setLogger()`
-*
-* See design/17-logging.md §"DefaultLogger"
-*/
-/**
-* Format data fields as `key=value` pairs for human-readable output.
-* - `error` key is serialized via formatSsrError for stack trace cleanup
-* - `trace_id` is truncated to 8 chars for readability (full ID in OTEL)
-* - Other values are stringified inline
-*/
-function formatDataFields(data) {
-	if (!data) return "";
-	const parts = [];
-	let traceId;
-	for (const [key, value] of Object.entries(data)) {
-		if (key === "trace_id") {
-			traceId = typeof value === "string" ? value : String(value);
-			continue;
-		}
-		if (key === "error") {
-			parts.push(`error=${formatSsrError(value)}`);
-			continue;
-		}
-		if (value === void 0 || value === null) continue;
-		parts.push(`${key}=${value}`);
-	}
-	if (traceId) parts.push(`trace_id=${traceId.slice(0, 8)}`);
-	return parts.length > 0 ? "  " + parts.join("  ") : "";
-}
-/** Pad level string to fixed width for alignment. */
-function padLevel(level) {
-	return level.padEnd(5);
-}
-function createDefaultLogger() {
-	return {
-		error(msg, data) {
-			const fields = formatDataFields(data);
-			process.stderr.write(`[timber] ${padLevel("ERROR")}  ${msg}${fields}\n`);
-		},
-		warn(msg, data) {
-			const fields = formatDataFields(data);
-			process.stderr.write(`[timber] ${padLevel("WARN")}  ${msg}${fields}\n`);
-		},
-		info(msg, data) {
-			if (isDevMode()) return;
-			if (!isDebug()) return;
-			const fields = formatDataFields(data);
-			process.stderr.write(`[timber] ${padLevel("INFO")}  ${msg}${fields}\n`);
-		},
-		debug(msg, data) {
-			if (isDevMode()) return;
-			if (!isDebug()) return;
-			const fields = formatDataFields(data);
-			process.stderr.write(`[timber] ${padLevel("DEBUG")}  ${msg}${fields}\n`);
-		}
-	};
-}
-//#endregion
-//#region src/server/waituntil-bridge.ts
-/**
-* Per-request waitUntil bridge — ALS bridge for platform adapters.
-*
-* The generated entry point (Nitro, Cloudflare) wraps the handler with
-* `runWithWaitUntil`, binding the platform's lifecycle extension function
-* (e.g., h3's `event.waitUntil()` or CF's `ctx.waitUntil()`) for the
-* request duration. The `waitUntil()` primitive reads from this ALS to
-* dispatch background work to the correct platform API.
-*
-* Design doc: design/11-platform.md §"waitUntil()"
-*/
-/**
-* Get the current request's waitUntil function, if available.
-*
-* Returns undefined when no platform adapter has installed a waitUntil
-* handler for the current request (e.g., on platforms that don't support
-* lifecycle extension, or outside a request context).
-*/
-function getWaitUntil() {
-	return waitUntilAls.getStore();
-}
-//#endregion
 //#region src/server/cookie-parsing.ts
 /**
 * Cookie parsing and serialization helpers — pure string ↔ structure
@@ -1363,114 +970,6 @@ function waitUntil(promise) {
 	}
 }
 //#endregion
-//#region src/server/logger.ts
-/**
-* Logger — structured logging with environment-aware formatting.
-*
-* timber.js ships a DefaultLogger that writes human-readable lines to stderr
-* in production. Users can export a custom logger from instrumentation.ts to
-* replace it with pino, winston, or any TimberLogger-compatible object.
-*
-* See design/17-logging.md §"Production Logging"
-*/
-var _logger = createDefaultLogger();
-/**
-* Set the user-provided logger. Called by the instrumentation loader
-* when it finds a `logger` export in instrumentation.ts. Replaces
-* the DefaultLogger entirely.
-*/
-function setLogger(logger) {
-	_logger = logger;
-}
-/**
-* Get the current logger. Always non-null — returns DefaultLogger when
-* no custom logger is configured.
-*/
-function getLogger() {
-	return _logger;
-}
-/**
-* Inject trace_id and span_id into log data for log–trace correlation.
-* Always injects trace_id (never undefined). Injects span_id only when OTEL is active.
-*/
-function withTraceContext(data) {
-	const store = getTraceStore();
-	const enriched = { ...data };
-	if (store) {
-		enriched.trace_id = store.traceId;
-		if (store.spanId) enriched.span_id = store.spanId;
-	}
-	return enriched;
-}
-/** Log a completed request. Level: info. */
-function logRequestCompleted(data) {
-	_logger.info("request completed", withTraceContext(data));
-}
-/** Log request received. Level: debug. */
-function logRequestReceived(data) {
-	_logger.debug("request received", withTraceContext(data));
-}
-/** Log a slow request warning. Level: warn. */
-function logSlowRequest(data) {
-	_logger.warn("slow request exceeded threshold", withTraceContext(data));
-}
-/** Log middleware short-circuit. Level: debug. */
-function logMiddlewareShortCircuit(data) {
-	_logger.debug("middleware short-circuited", withTraceContext(data));
-}
-/** Log unhandled error in middleware phase. Level: error. */
-function logMiddlewareError(data) {
-	if (isControlFlowSignal(data.error)) return;
-	_logger.error("unhandled error in middleware phase", withTraceContext(data));
-}
-/** Log unhandled render-phase error. Level: error. */
-function logRenderError(data) {
-	if (isControlFlowSignal(data.error)) return;
-	_logger.error("unhandled render-phase error", withTraceContext(data));
-}
-/** Log proxy.ts uncaught error. Level: error. */
-function logProxyError(data) {
-	_logger.error("proxy.ts threw uncaught error", withTraceContext(data));
-}
-/** Log unhandled error in route handler. Level: error. */
-function logRouteError(data) {
-	if (isControlFlowSignal(data.error)) return;
-	_logger.error("unhandled route handler error", withTraceContext(data));
-}
-/** Log waitUntil() adapter missing (once at startup). Level: warn. */
-function logWaitUntilUnsupported() {
-	_logger.warn("adapter does not support waitUntil()");
-}
-/** Log waitUntil() promise rejection. Level: warn. */
-function logWaitUntilRejected(data) {
-	_logger.warn("waitUntil() promise rejected", withTraceContext(data));
-}
-/** Log staleWhileRevalidate refetch failure. Level: warn. */
-function logSwrRefetchFailed(data) {
-	_logger.warn("staleWhileRevalidate refetch failed", withTraceContext(data));
-}
-/** Log cache miss. Level: debug. */
-function logCacheMiss(data) {
-	_logger.debug("timber.cache MISS", withTraceContext(data));
-}
-/**
-* Log an intentionally swallowed error. Provides observability into catch
-* blocks that are deliberately empty — the error is consumed, never rethrown.
-*
-* Default level: `warn` in dev (so the overlay surfaces patterns), `debug`
-* in production (low noise unless TIMBER_DEBUG is set). Pass `opts.level`
-* to override.
-*
-* **Infallible** — swallow() itself never throws, even if the logger is
-* broken. A thrown swallow would turn a benign catch into a crash.
-*/
-function swallow(err, reason, opts) {
-	try {
-		const level = opts?.level ?? (isDevMode() ? "warn" : "debug");
-		_logger[level](`swallowed: ${reason}`, withTraceContext({ error: err }));
-	} catch {}
-}
-//#endregion
-export { getSegmentParams as A, isDebug as B, redirect as C, getHeader as D, applyRequestHeaderOverlay as E, setSegmentParams as F, getOtelTraceId as G, addSpanEvent as H, getCookie as I, replaceTraceId as J, getSpanId as K, getCookieJar as L, runWithRequestContext as M, setMatchedSegmentPath as N, getHeaders as O, setMutableCookieContext as P, getSetCookieHeaders as R, isSsrStreamError as S, waitUntil as T, addSpanEventSync as U, isDevMode as V, generateTraceId as W, setSpanAttribute as X, runWithTraceId as Y, withSpan as Z, RedirectSignal as _, logProxyError as a, isDenySignal as b, logRequestReceived as c, logSwrRefetchFailed as d, logWaitUntilRejected as f, DenySignal as g, swallow as h, logMiddlewareShortCircuit as i, markResponseFlushed as j, getSearchParams as k, logRouteError as l, setLogger as m, logCacheMiss as n, logRenderError as o, logWaitUntilUnsupported as p, getTraceId as q, logMiddlewareError as r, logRequestCompleted as s, getLogger as t, logSlowRequest as u, RenderError as v, redirectExternal as w, isRedirectSignal as x, deny as y, getWaitUntil as z };
+export { getCookieJar as C, getWaitUntil as D, isDevMode as E, getCookie as S, isDebug as T, markResponseFlushed as _, isControlFlowSignal as a, setMutableCookieContext as b, isSsrStreamError as c, waitUntil as d, applyRequestHeaderOverlay as f, getSegmentParams as g, getSearchParams as h, deny as i, redirect as l, getHeaders as m, RedirectSignal as n, isDenySignal as o, getHeader as p, RenderError as r, isRedirectSignal as s, DenySignal as t, redirectExternal as u, runWithRequestContext as v, getSetCookieHeaders as w, setSegmentParams as x, setMatchedSegmentPath as y };
 
-//# sourceMappingURL=logger-DqJ2VoAY.js.map
+//# sourceMappingURL=primitives-DLAnvsrk.js.map