@amkisko/json-logging 0.0.0-stage → 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+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

@@ -1,3 +1,232 @@
-# Temporary Holding Version
+# @amkisko/json-logging
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Structured JSON logging for Bun, Node, Deno, Next.js, and Remix. The portable API follows the Ruby `activesupport-json_logging` gem style: create a logger, call severity methods, use `tagged` and `withContext`, and emit one JSON object per line.
+
+Zero runtime dependencies. Ambient `withContext` / block `tagged` use AsyncLocalStorage when the runtime exposes it through `process.getBuiltinModule("async_hooks")` (Node, Bun, Deno with Node builtins, Cloudflare Workers with `nodejs_compat`). The package never statically imports `node:async_hooks`, so browsers and Workers without Node builtins can still import and emit basic JSON lines; ambient context is a no-op there. Call `isAsyncLocalStorageAvailable()` to detect ALS. Helpers under `@amkisko/json-logging/next` and `@amkisko/json-logging/remix` use Web APIs and do not add framework packages as runtime dependencies.
+
+## Runtime compatibility
+
+| Runtime | Support | Notes |
+| --- | --- | --- |
+| Node.js | Compatible | Primary target; ALS context works. |
+| Bun | Compatible | Tested in CI; `@amkisko/json-logging/bun` for `Bun.serve`. |
+| Deno | Compatible | ALS via Deno Node builtins (`getBuiltinModule`). |
+| Cloudflare Workers | Compatible | Full ALS with `nodejs_compat`. Without it: import and basic logging still work; `withContext` does not retain fields. |
+| Browsers | Compatible | Basic logging and sinks work. Ambient context requires a host that provides ALS (unusual in browsers). |
+
+On the JSR package settings page, mark Node.js, Bun, Deno, Cloudflare Workers, and Browsers as compatible. Set the package description to the same summary as `package.json`.
+
+## Install
+
+From npm:
+
+```bash
+bun add @amkisko/json-logging
+npm install @amkisko/json-logging
+```
+
+From JSR:
+
+```bash
+deno add jsr:@amkisko/json-logging
+npx jsr add @amkisko/json-logging
+```
+
+## Five-minute usage
+
+```ts
+import { JsonLogging, createLogger, withContext } from "@amkisko/json-logging";
+
+const logger = JsonLogging.new();
+// same as createLogger()
+
+logger.info("server started");
+logger.info({ event: "signup", userId: 42 });
+logger.error(new Error("payment failed"));
+
+logger.tagged("billing", () => {
+  logger.info("invoice created");
+});
+
+const billing = logger.tagged("billing");
+billing.info("sticky tags on child logger");
+
+await withContext({ requestId: "abc" }, async () => {
+  logger.info("handled request");
+});
+```
+
+Each line looks like:
+
+```json
+{"message":"server started","severity":"INFO","timestamp":"2026-10-26T05:30:00.000000Z"}
+```
+
+Object fields merge at the root. Tags appear as `tags`. Request fields appear under `context`. System keys (`tags`, `severity`, `timestamp`, `message`, `context`) are reserved.
+
+Optional hot-path helpers (RFC-0002):
+
+```ts
+const logger = createLogger({
+  level: "info",
+  redact: ["user.password", "headers.authorization"],
+  serializers: {
+    err: (value) => value, // root-field transform
+  },
+});
+
+if (logger.isLevelEnabled("debug")) {
+  logger.debug({ detail: "expensive" });
+}
+```
+
+## Sinks
+
+Console is the default. Pass a custom sink or a `WritableStream`:
+
+```ts
+import { createLogger, consoleSink, streamSink } from "@amkisko/json-logging";
+
+createLogger({ sink: consoleSink() });
+createLogger({ sink: streamSink(myWritableStream) });
+createLogger({
+  sink: {
+    write(line, record) {
+      // forward somewhere else
+    },
+  },
+});
+```
+
+## Capture console and app logs (opt-in)
+
+`JsonLogging.new()` alone does not rewrite `console` or framework logs. For app code plus `console.*`, use the opt-in bridge:
+
+```ts
+import { installStructuredLogging } from "@amkisko/json-logging/console";
+
+const { logger, uninstall } = installStructuredLogging({
+  base: { service: "api" },
+});
+
+logger.info("structured");
+console.log("also structured"); // routed through the same logger
+```
+
+Or attach a bridge to an existing logger:
+
+```ts
+import { createLogger } from "@amkisko/json-logging";
+import { installConsoleBridge } from "@amkisko/json-logging/console";
+
+const logger = createLogger({ base: { service: "api" } });
+const uninstall = installConsoleBridge(logger);
+```
+
+Runnable patterns live under `examples/`:
+
+- `examples/bun-entry.ts`
+- `examples/next-instrumentation.ts`
+- `examples/remix-handle-request.ts`
+
+### What becomes structured
+
+- Calls on the package logger (`info`, `tagged`, `withContext`, ...)
+- `console.log` / `info` / `warn` / `error` / `debug` after `installConsoleBridge` or `installStructuredLogging`
+- Code that already logs through those console methods
+
+### What does not
+
+- Next.js / Remix / Vite / Bun CLI and framework internals
+- Browser DevTools console
+- Libraries that write straight to `process.stdout` / `stderr` or their own transports (Pino destinations, Winston file transports, etc.) without going through `console`
+- Middleware ALS context continuing into a later Node App Router handler (forward `x-request-id` and call `withContext` again)
+
+## HTTP adapters
+
+Shared helpers live under `@amkisko/json-logging/http`. Framework subpaths are duck-typed and add no runtime dependencies (RFC-0003):
+
+- `@amkisko/json-logging/next`
+- `@amkisko/json-logging/remix`
+- `@amkisko/json-logging/hono`
+- `@amkisko/json-logging/express`
+- `@amkisko/json-logging/fastify` (route handler wrap)
+- `@amkisko/json-logging/koa`
+- `@amkisko/json-logging/bun`
+
+CI runs end-to-end adapter checks under `tests/e2e/` against real packages as development dependencies: Hono (`app.request`), Express and Koa (listen + `fetch`), Fastify (`inject`), `Bun.serve`, Next.js (`NextRequest` from `next/server` through `withRequestLogging`), Remix (`createRequestHandler` from `@remix-run/node` with a loader under `withRemixContext`), and NestJS composition (Express `app.use(withExpressLogging)` and Fastify `withHttpContext` interceptor). CI also runs a Node runtime smoke (`make node-smoke`) and an Edge import-graph check (`make edge-import`) so Edge-oriented entrypoints do not statically import forbidden Node builtins. CI does not boot a full Next, Remix, or Nest production app process; it uses the same request and handler APIs those apps call.
+
+```ts
+import { bindHttpLogger, httpLogger } from "@amkisko/json-logging/http";
+import { withHonoLogging } from "@amkisko/json-logging/hono";
+
+bindHttpLogger(httpLogger({ loggerOptions: { base: { service: "api" } } }));
+app.use(withHonoLogging());
+```
+
+There is no dedicated `./nest` or `./sails` export. NestJS on the Express platform uses `app.use(withExpressLogging(...))`. NestJS on Fastify uses a request interceptor (or equivalent) that calls `withHttpContext` from `./http` around the handler. Sails.js sits on Express: mount `withExpressLogging` on the underlying Express app (for example via custom middleware / `sails.hooks.http.app`).
+
+Ambient logger helpers live only on `./http` so framework entrypoints stay slim. Run microbenchmarks with `make bench` (ceilings in `usr/budgets/bench.json`).
+
+## Next.js
+
+Boot once (for example from `instrumentation.ts`), then wrap middleware:
+
+```ts
+import { installStructuredLogging } from "@amkisko/json-logging/console";
+import { bindHttpLogger, httpLogger } from "@amkisko/json-logging/http";
+import { withRequestLogging } from "@amkisko/json-logging/next";
+
+const { logger } = installStructuredLogging({ base: { service: "next-app" } });
+bindHttpLogger(logger);
+
+export default withRequestLogging(async (req) => {
+  httpLogger().info({ event: "middleware", path: req.nextUrl?.pathname });
+  // return NextResponse.next()
+});
+```
+
+See `examples/next-instrumentation.ts`.
+
+## Remix
+
+```ts
+import { installStructuredLogging } from "@amkisko/json-logging/console";
+import { bindHttpLogger, httpLogger } from "@amkisko/json-logging/http";
+import { withRemixContext } from "@amkisko/json-logging/remix";
+
+const { logger } = installStructuredLogging({ base: { service: "remix-app" } });
+bindHttpLogger(logger);
+
+return withRemixContext({ request, context }, () => {
+  httpLogger().info("loading");
+  return handle(request);
+});
+```
+
+See `examples/remix-handle-request.ts`.
+
+## Development
+
+```bash
+bun install
+make check
+```
+
+`make check` runs Biome (`biome.json`), prose checks, typecheck, type-coverage (100% strict), tests with coverage thresholds at 100%, mutation checks, dependency audit, LOC gate, bundle size budget, example smoke, Edge import-graph check, and Node runtime smoke. `make ci` also builds `dist/` and runs `make bench` (ceilings in `usr/budgets/bench.json`).
+
+Release:
+
+```bash
+make release
+make release DRY_RUN=1
+make release VERSION=0.1.0
+```
+
+`make release` reads the first `## X.Y.Z` heading in `CHANGELOG.md`, runs quality gates, publishes to npmjs, pushes a version tag, and leaves JSR publishing to GitHub Actions (OIDC provenance). Optional `VERSION=` overrides the changelog heading. Keep `package.json` and `jsr.json` version fields in sync before release. Create the `@amkisko` scope and `json-logging` package on [jsr.io](https://jsr.io/new), then link this GitHub repository in the JSR package settings so tag publishes can authenticate.
+
+Quality scripts live under `usr/bin/` (same layout as other amkisko libraries). Bundle ceilings are in `usr/budgets/bundle.json`. Product-facing notes live in `CHANGELOG.md`; engineering drafts under `docs/changelogs/`.
+
+## License
+
+MIT (see `LICENSE.md`)

package/dist/bun-serve.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Bun.serve fetch-handler wrap for request-scoped log context (and optional completion).
+ *
+ * @example
+ * ```ts
+ * import { withBunLogging } from "@amkisko/json-logging/bun";
+ * Bun.serve({ fetch: withBunLogging(async (req) => new Response("ok")) });
+ * ```
+ *
+ * @module
+ */
+import type { Logger } from "./logger.js";
+import type { LoggerOptions } from "./types.js";
+/** Minimal fetch Request shape used with Bun.serve. */
+export type BunFetchRequest = {
+    method: string;
+    url: string;
+    headers: Headers;
+};
+/** Options for {@link withBunLogging}. */
+export type WithBunLoggingOptions = {
+    headerName?: string;
+    logger?: Logger;
+    loggerOptions?: LoggerOptions;
+    headersAllowlist?: readonly string[];
+    logCompletion?: boolean;
+};
+/** Wrap a `Bun.serve` fetch handler. Bind loggers via `./http`. */
+export declare function withBunLogging<TArgs extends unknown[], TResult>(handler: (request: BunFetchRequest, ...rest: TArgs) => TResult | Promise<TResult>, options?: WithBunLoggingOptions): (request: BunFetchRequest, ...rest: TArgs) => Promise<TResult>;
+//# sourceMappingURL=bun-serve.d.ts.map

package/dist/bun-serve.js

@@ -0,0 +1,60 @@
+/**
+ * Bun.serve fetch-handler wrap for request-scoped log context (and optional completion).
+ *
+ * @example
+ * ```ts
+ * import { withBunLogging } from "@amkisko/json-logging/bun";
+ * Bun.serve({ fetch: withBunLogging(async (req) => new Response("ok")) });
+ * ```
+ *
+ * @module
+ */
+import { bindLoggerFromOptions, getAmbientHttpLogger } from "./http-ambient.js";
+import { httpFieldsFrom, logRequestCompletion, withHttpContext, } from "./http-context.js";
+function responseStatus(value) {
+    if (typeof value === "object" &&
+        value !== null &&
+        typeof Reflect.get(value, "status") === "number") {
+        return Reflect.get(value, "status");
+    }
+    return 200;
+}
+/** Wrap a `Bun.serve` fetch handler. Bind loggers via `./http`. */
+export function withBunLogging(handler, options = {}) {
+    bindLoggerFromOptions(options);
+    const headerName = options.headerName ?? "x-request-id";
+    return async (request, ...rest) => {
+        const input = {
+            method: request.method,
+            url: request.url,
+            headers: request.headers,
+        };
+        const started = Date.now();
+        const fields = httpFieldsFrom(input, headerName);
+        let error;
+        let result;
+        try {
+            result = (await withHttpContext(input, () => handler(request, ...rest), options));
+            return result;
+        }
+        catch (caught) {
+            error = caught;
+            throw caught;
+        }
+        finally {
+            if (options.logCompletion) {
+                const logger = options.logger ?? getAmbientHttpLogger();
+                if (logger) {
+                    logRequestCompletion(logger, {
+                        method: typeof fields.method === "string" ? fields.method : undefined,
+                        path: typeof fields.path === "string" ? fields.path : undefined,
+                        status: error !== undefined ? 500 : responseStatus(result),
+                        elapsedMs: Date.now() - started,
+                        error,
+                    });
+                }
+            }
+        }
+    };
+}
+//# sourceMappingURL=bun-serve.js.map

package/dist/console-bridge.d.ts

@@ -0,0 +1,26 @@
+import { type ConsoleMethodName, type ConsoleMethods } from "./console-state.js";
+import type { Logger } from "./logger.js";
+import type { LoggerOptions, LogMessage } from "./types.js";
+export type ConsoleBridgeOptions = {
+    methods?: readonly ConsoleMethodName[];
+};
+export type StructuredLoggingInstall = {
+    logger: Logger;
+    uninstall: () => void;
+};
+export declare function isConsoleBridgeInstalled(): boolean;
+export declare function uninstallConsoleBridge(): void;
+/**
+ * Routes console.log/info/warn/error/debug through `logger` as structured JSON.
+ * Opt-in only. Does not capture framework internals or libraries that bypass console.
+ * Safe with the default console sink: writes use the pre-patch console methods.
+ */
+export declare function installConsoleBridge(logger: Logger, options?: ConsoleBridgeOptions): () => void;
+/**
+ * One-call setup: logger that writes via captured console methods, plus console bridge.
+ * Prefer this when the goal is "app + console.* become structured JSON lines".
+ */
+export declare function installStructuredLogging(options?: LoggerOptions & ConsoleBridgeOptions): StructuredLoggingInstall;
+export declare function messageFromConsoleArgs(args: unknown[]): LogMessage;
+export type { ConsoleMethods, ConsoleMethodName };
+//# sourceMappingURL=console-bridge.d.ts.map

package/dist/console-bridge.js

@@ -0,0 +1,155 @@
+import { captureConsoleMethods, enterBridge, getBridgeOriginals, isInBridge, leaveBridge, setBridgeOriginals, } from "./console-state.js";
+import { createLogger } from "./json-logging.js";
+import { isPlainObject } from "./objects.js";
+import { consoleSinkFrom } from "./sinks.js";
+const DEFAULT_METHODS = ["log", "info", "warn", "error", "debug"];
+const LEVEL_BY_METHOD = {
+    log: "info",
+    info: "info",
+    warn: "warn",
+    error: "error",
+    debug: "debug",
+};
+let installedMethods = null;
+export function isConsoleBridgeInstalled() {
+    return getBridgeOriginals() !== null;
+}
+export function uninstallConsoleBridge() {
+    const originals = getBridgeOriginals();
+    if (!originals || !installedMethods) {
+        setBridgeOriginals(null);
+        installedMethods = null;
+        return;
+    }
+    for (const name of installedMethods) {
+        Reflect.set(console, name, originals[name]);
+    }
+    setBridgeOriginals(null);
+    installedMethods = null;
+}
+/**
+ * Routes console.log/info/warn/error/debug through `logger` as structured JSON.
+ * Opt-in only. Does not capture framework internals or libraries that bypass console.
+ * Safe with the default console sink: writes use the pre-patch console methods.
+ */
+export function installConsoleBridge(logger, options = {}) {
+    uninstallConsoleBridge();
+    const originals = captureConsoleMethods(console);
+    setBridgeOriginals(originals);
+    const methods = options.methods ?? DEFAULT_METHODS;
+    installedMethods = [...methods];
+    for (const name of methods) {
+        const level = LEVEL_BY_METHOD[name];
+        Reflect.set(console, name, (...args) => {
+            if (isInBridge()) {
+                originals[name](...args);
+                return;
+            }
+            enterBridge();
+            try {
+                writeThroughLogger(logger, level, args);
+            }
+            finally {
+                leaveBridge();
+            }
+        });
+    }
+    return uninstallConsoleBridge;
+}
+/**
+ * One-call setup: logger that writes via captured console methods, plus console bridge.
+ * Prefer this when the goal is "app + console.* become structured JSON lines".
+ */
+export function installStructuredLogging(options = {}) {
+    const { methods, ...loggerOptions } = options;
+    // Restore real console methods before capture so a re-install does not
+    // bind the sink to an already patched console.
+    uninstallConsoleBridge();
+    const originals = captureConsoleMethods(console);
+    const logger = createLogger({
+        ...loggerOptions,
+        sink: loggerOptions.sink ?? consoleSinkFrom(originals),
+    });
+    const uninstall = installConsoleBridge(logger, methods ? { methods } : {});
+    return { logger, uninstall };
+}
+export function messageFromConsoleArgs(args) {
+    if (args.length === 0) {
+        return "";
+    }
+    if (args.length === 1) {
+        return singleArgMessage(args[0]);
+    }
+    return {
+        message: args.map(stringifyArg).join(" "),
+        console_args: args.map(snapshotArg),
+    };
+}
+function writeThroughLogger(logger, level, args) {
+    const message = messageFromConsoleArgs(args);
+    switch (level) {
+        case "debug":
+            logger.debug(message);
+            break;
+        case "warn":
+            logger.warn(message);
+            break;
+        case "error":
+        case "fatal":
+            logger.error(message);
+            break;
+        default:
+            logger.info(message);
+    }
+}
+function singleArgMessage(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    if (value instanceof Error) {
+        return value;
+    }
+    if (isPlainObject(value)) {
+        return value;
+    }
+    return stringifyArg(value);
+}
+function stringifyArg(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    if (value instanceof Error) {
+        return value.message;
+    }
+    if (typeof value === "number" || typeof value === "boolean") {
+        return String(value);
+    }
+    if (value === null) {
+        return "null";
+    }
+    if (value === undefined) {
+        return "undefined";
+    }
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return "[unstringifiable]";
+    }
+}
+function snapshotArg(value) {
+    if (typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean" ||
+        value === null) {
+        return value;
+    }
+    if (value instanceof Error) {
+        return { name: value.name, message: value.message };
+    }
+    if (isPlainObject(value)) {
+        return value;
+    }
+    return stringifyArg(value);
+}
+//# sourceMappingURL=console-bridge.js.map

package/dist/console-state.d.ts

@@ -0,0 +1,11 @@
+export type ConsoleMethodName = "log" | "info" | "warn" | "error" | "debug";
+export type ConsoleMethods = {
+    [K in ConsoleMethodName]: (...args: unknown[]) => void;
+};
+export declare function setBridgeOriginals(methods: ConsoleMethods | null): void;
+export declare function getBridgeOriginals(): ConsoleMethods | null;
+export declare function enterBridge(): void;
+export declare function leaveBridge(): void;
+export declare function isInBridge(): boolean;
+export declare function captureConsoleMethods(target?: Partial<ConsoleMethods> & object): ConsoleMethods;
+//# sourceMappingURL=console-state.d.ts.map

package/dist/console-state.js

@@ -0,0 +1,40 @@
+let bridgeOriginals = null;
+let bridgeDepth = 0;
+export function setBridgeOriginals(methods) {
+    bridgeOriginals = methods;
+}
+export function getBridgeOriginals() {
+    return bridgeOriginals;
+}
+export function enterBridge() {
+    bridgeDepth += 1;
+}
+export function leaveBridge() {
+    if (bridgeDepth > 0) {
+        bridgeDepth -= 1;
+    }
+}
+export function isInBridge() {
+    return bridgeDepth > 0;
+}
+export function captureConsoleMethods(target = console) {
+    return {
+        log: bindMethod(target, "log"),
+        info: bindMethod(target, "info"),
+        warn: bindMethod(target, "warn"),
+        error: bindMethod(target, "error"),
+        debug: bindMethod(target, "debug"),
+    };
+}
+function bindMethod(target, name) {
+    const method = Reflect.get(target, name);
+    if (typeof method === "function") {
+        return (...args) => {
+            Reflect.apply(method, target, args);
+        };
+    }
+    return (...args) => {
+        Reflect.apply(console.log, console, args);
+    };
+}
+//# sourceMappingURL=console-state.js.map

package/dist/console.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Opt-in console bridge: route `console.log` / `info` / `warn` / `error` / `debug`
+ * through a structured {@link Logger}.
+ *
+ * @example
+ * ```ts
+ * import { installStructuredLogging } from "@amkisko/json-logging/console";
+ *
+ * const { logger, uninstall } = installStructuredLogging({ base: { service: "api" } });
+ * console.log("also structured");
+ * uninstall();
+ * ```
+ *
+ * @module
+ */
+export type { ConsoleBridgeOptions, StructuredLoggingInstall, } from "./console-bridge.js";
+export { installConsoleBridge, installStructuredLogging, isConsoleBridgeInstalled, messageFromConsoleArgs, uninstallConsoleBridge, } from "./console-bridge.js";
+//# sourceMappingURL=console.d.ts.map

package/dist/console.js

@@ -0,0 +1,17 @@
+/**
+ * Opt-in console bridge: route `console.log` / `info` / `warn` / `error` / `debug`
+ * through a structured {@link Logger}.
+ *
+ * @example
+ * ```ts
+ * import { installStructuredLogging } from "@amkisko/json-logging/console";
+ *
+ * const { logger, uninstall } = installStructuredLogging({ base: { service: "api" } });
+ * console.log("also structured");
+ * uninstall();
+ * ```
+ *
+ * @module
+ */
+export { installConsoleBridge, installStructuredLogging, isConsoleBridgeInstalled, messageFromConsoleArgs, uninstallConsoleBridge, } from "./console-bridge.js";
+//# sourceMappingURL=console.js.map

package/dist/context.d.ts

@@ -0,0 +1,40 @@
+/** Key/value fields stored in the ambient request context. */
+export type ContextFields = Record<string, unknown>;
+type Store = {
+    context: ContextFields;
+    tags: string[];
+};
+/** Minimal ALS surface used for request/block context (run + getStore only). */
+export type AlsInstance<T> = {
+    run<R>(store: T, callback: () => R): R;
+    getStore(): T | undefined;
+};
+/** Constructor for {@link AlsInstance}, matching `node:async_hooks`.AsyncLocalStorage. */
+export type AlsConstructor = new <T>() => AlsInstance<T>;
+/** True when this runtime can construct AsyncLocalStorage for ambient context. */
+export declare function isAsyncLocalStorageAvailable(): boolean;
+/** Test helper: force ALS constructor resolution (`null` = unavailable). */
+export declare function setAlsConstructorForTests(value: AlsConstructor | null | undefined): void;
+/** Test helper: pass null to simulate a runtime without AsyncLocalStorage. */
+export declare function setAlsOverrideForTests(value: AlsInstance<Store> | null | undefined): void;
+export declare function readStore(als: AlsInstance<Store> | undefined): Store | undefined;
+/** Copy of the current ambient context fields, or undefined outside a scope. */
+export declare function getContext(): ContextFields | undefined;
+/** Copy of nested `tagged` block tags for the current ALS scope. */
+export declare function getBlockTags(): string[];
+/** One store read for the log hot path. Returns live references; do not mutate. */
+export declare function peekLogStore(): {
+    context: ContextFields | undefined;
+    tags: readonly string[];
+};
+/**
+ * Run `fn` with ambient context fields merged for the duration of the call.
+ * Without AsyncLocalStorage the callback still runs; context is not retained.
+ */
+export declare function withContext<T>(fields: ContextFields, fn: () => T | Promise<T>): T | Promise<T>;
+/** Nested tag scope used by {@link Logger.tagged} block form. */
+export declare function withBlockTags<T>(tags: readonly string[], fn: () => T | Promise<T>): T | Promise<T>;
+/** Test helper: clear the global ALS singleton between suites. */
+export declare function resetContextStorageForTests(): void;
+export {};
+//# sourceMappingURL=context.d.ts.map