@amkisko/json-logging 0.0.0-stage → 0.1.1

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

package/dist/context.js

@@ -0,0 +1,162 @@
+const GLOBAL_KEY = "__amkisko_json_logging_als__";
+let alsOverride;
+let alsConstructorOverride;
+/** `false` means not resolved yet; `undefined` means unavailable after resolve. */
+let cachedConstructor = false;
+function isAlsConstructor(value) {
+    return typeof value === "function";
+}
+function readProcessBuiltin(id) {
+    const proc = Reflect.get(globalThis, "process");
+    if (typeof proc !== "object" || proc === null) {
+        return undefined;
+    }
+    const getBuiltinModule = Reflect.get(proc, "getBuiltinModule");
+    if (typeof getBuiltinModule !== "function") {
+        return undefined;
+    }
+    return Reflect.apply(getBuiltinModule, proc, [id]);
+}
+/**
+ * Soft-load AsyncLocalStorage without a static `node:async_hooks` import so browsers
+ * and Workers without Node builtins can still import this module for basic logging.
+ */
+function loadAlsConstructor() {
+    if (alsConstructorOverride === null) {
+        return undefined;
+    }
+    if (alsConstructorOverride !== undefined) {
+        return alsConstructorOverride;
+    }
+    if (cachedConstructor !== false) {
+        return cachedConstructor;
+    }
+    for (const id of ["async_hooks", "node:async_hooks"]) {
+        try {
+            const mod = readProcessBuiltin(id);
+            if (typeof mod !== "object" || mod === null) {
+                continue;
+            }
+            const ctor = Reflect.get(mod, "AsyncLocalStorage");
+            if (isAlsConstructor(ctor)) {
+                cachedConstructor = ctor;
+                return cachedConstructor;
+            }
+        }
+        catch {
+            // try next id
+        }
+    }
+    cachedConstructor = undefined;
+    return undefined;
+}
+/** True when this runtime can construct AsyncLocalStorage for ambient context. */
+export function isAsyncLocalStorageAvailable() {
+    return loadAlsConstructor() !== undefined;
+}
+/** Test helper: force ALS constructor resolution (`null` = unavailable). */
+export function setAlsConstructorForTests(value) {
+    alsConstructorOverride = value;
+    cachedConstructor = false;
+}
+/** Test helper: pass null to simulate a runtime without AsyncLocalStorage. */
+export function setAlsOverrideForTests(value) {
+    alsOverride = value;
+}
+function getAls() {
+    if (alsOverride === null) {
+        return undefined;
+    }
+    if (alsOverride !== undefined) {
+        return alsOverride;
+    }
+    const Ctor = loadAlsConstructor();
+    if (!Ctor) {
+        return undefined;
+    }
+    const globalRef = globalThis;
+    if (!globalRef[GLOBAL_KEY]) {
+        globalRef[GLOBAL_KEY] = new Ctor();
+    }
+    return globalRef[GLOBAL_KEY];
+}
+export function readStore(als) {
+    if (!als) {
+        return undefined;
+    }
+    try {
+        return als.getStore();
+    }
+    catch {
+        return undefined;
+    }
+}
+function currentStore() {
+    return readStore(getAls());
+}
+/** Copy of the current ambient context fields, or undefined outside a scope. */
+export function getContext() {
+    const store = currentStore();
+    if (!store) {
+        return undefined;
+    }
+    return { ...store.context };
+}
+/** Copy of nested `tagged` block tags for the current ALS scope. */
+export function getBlockTags() {
+    const store = currentStore();
+    if (!store || store.tags.length === 0) {
+        return [];
+    }
+    return [...store.tags];
+}
+/** One store read for the log hot path. Returns live references; do not mutate. */
+export function peekLogStore() {
+    const store = currentStore();
+    if (!store) {
+        return { context: undefined, tags: [] };
+    }
+    return { context: store.context, tags: store.tags };
+}
+/**
+ * Run `fn` with ambient context fields merged for the duration of the call.
+ * Without AsyncLocalStorage the callback still runs; context is not retained.
+ */
+export function withContext(fields, fn) {
+    const als = getAls();
+    if (!als) {
+        return fn();
+    }
+    const parent = currentStore();
+    const next = {
+        context: { ...(parent?.context ?? {}), ...fields },
+        tags: parent?.tags ? [...parent.tags] : [],
+    };
+    return als.run(next, fn);
+}
+/** Nested tag scope used by {@link Logger.tagged} block form. */
+export function withBlockTags(tags, fn) {
+    const als = getAls();
+    if (!als) {
+        return fn();
+    }
+    const parent = currentStore();
+    const next = {
+        context: parent?.context ? { ...parent.context } : {},
+        tags: [...(parent?.tags ?? []), ...tags],
+    };
+    return als.run(next, fn);
+}
+/** Test helper: clear the global ALS singleton between suites. */
+export function resetContextStorageForTests() {
+    const globalRef = globalThis;
+    const Ctor = loadAlsConstructor();
+    if (Ctor) {
+        globalRef[GLOBAL_KEY] = new Ctor();
+    }
+    else {
+        delete globalRef[GLOBAL_KEY];
+    }
+    alsOverride = undefined;
+}
+//# sourceMappingURL=context.js.map

package/dist/express.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Express middleware that attaches request context (and optional completion on `finish`).
+ *
+ * @example
+ * ```ts
+ * import { withExpressLogging } from "@amkisko/json-logging/express";
+ * app.use(withExpressLogging({ logCompletion: true }));
+ * ```
+ *
+ * @module
+ */
+import type { Logger } from "./logger.js";
+import type { LoggerOptions } from "./types.js";
+/** Minimal Express request shape (no Express runtime dependency). */
+export type ExpressRequestLike = {
+    method?: string;
+    url?: string;
+    originalUrl?: string;
+    headers?: Record<string, string | string[] | undefined>;
+};
+/** Minimal Express response shape. */
+export type ExpressResponseLike = {
+    statusCode?: number;
+    on?: (event: string, listener: () => void) => unknown;
+};
+/** Options for {@link withExpressLogging}. */
+export type WithExpressLoggingOptions = {
+    headerName?: string;
+    logger?: Logger;
+    loggerOptions?: LoggerOptions;
+    headersAllowlist?: readonly string[];
+    logCompletion?: boolean;
+};
+/** Express-style middleware function. */
+export type ExpressMiddleware = (req: ExpressRequestLike, res: ExpressResponseLike, next: (error?: unknown) => void) => void;
+/**
+ * Build Express middleware: `(req, res, next) => ...`.
+ * Bind loggers via `@amkisko/json-logging/http`.
+ */
+export declare function withExpressLogging(options?: WithExpressLoggingOptions): ExpressMiddleware;
+//# sourceMappingURL=express.d.ts.map

package/dist/express.js

@@ -0,0 +1,48 @@
+/**
+ * Express middleware that attaches request context (and optional completion on `finish`).
+ *
+ * @example
+ * ```ts
+ * import { withExpressLogging } from "@amkisko/json-logging/express";
+ * app.use(withExpressLogging({ logCompletion: true }));
+ * ```
+ *
+ * @module
+ */
+import { bindLoggerFromOptions, getAmbientHttpLogger } from "./http-ambient.js";
+import { httpFieldsFrom, logRequestCompletion, withHttpContext, } from "./http-context.js";
+/**
+ * Build Express middleware: `(req, res, next) => ...`.
+ * Bind loggers via `@amkisko/json-logging/http`.
+ */
+export function withExpressLogging(options = {}) {
+    bindLoggerFromOptions(options);
+    const headerName = options.headerName ?? "x-request-id";
+    return (req, res, next) => {
+        const input = {
+            method: req.method,
+            url: req.originalUrl ?? req.url,
+            headers: req.headers,
+        };
+        const started = Date.now();
+        const fields = httpFieldsFrom(input, headerName);
+        void withHttpContext(input, () => {
+            if (options.logCompletion && typeof res.on === "function") {
+                res.on("finish", () => {
+                    const logger = options.logger ?? getAmbientHttpLogger();
+                    if (!logger) {
+                        return;
+                    }
+                    logRequestCompletion(logger, {
+                        method: typeof fields.method === "string" ? fields.method : undefined,
+                        path: typeof fields.path === "string" ? fields.path : undefined,
+                        status: typeof res.statusCode === "number" ? res.statusCode : 0,
+                        elapsedMs: Date.now() - started,
+                    });
+                });
+            }
+            next();
+        }, options);
+    };
+}
+//# sourceMappingURL=express.js.map

package/dist/fastify.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Fastify route-handler wrap for request-scoped log context (and optional completion).
+ *
+ * @example
+ * ```ts
+ * import { withFastifyLogging } from "@amkisko/json-logging/fastify";
+ * app.get("/", withFastifyLogging(async (req, reply) => reply.send("ok")));
+ * ```
+ *
+ * @module
+ */
+import type { Logger } from "./logger.js";
+import type { LoggerOptions } from "./types.js";
+/** Minimal Fastify request shape (no Fastify runtime dependency). */
+export type FastifyRequestLike = {
+    method?: string;
+    url?: string;
+    headers?: Record<string, string | string[] | undefined>;
+};
+/** Minimal Fastify reply shape. */
+export type FastifyReplyLike = {
+    statusCode?: number;
+};
+/** Options for {@link withFastifyLogging}. */
+export type WithFastifyLoggingOptions = {
+    headerName?: string;
+    logger?: Logger;
+    loggerOptions?: LoggerOptions;
+    headersAllowlist?: readonly string[];
+    logCompletion?: boolean;
+};
+/**
+ * Wrap a Fastify route handler so ALS context covers the handler body.
+ * Bind loggers via `./http`.
+ */
+export declare function withFastifyLogging<TRequest extends FastifyRequestLike, TReply extends FastifyReplyLike, TResult>(handler: (this: unknown, request: TRequest, reply: TReply) => TResult | Promise<TResult>, options?: WithFastifyLoggingOptions): (this: unknown, request: TRequest, reply: TReply) => Promise<TResult>;
+//# sourceMappingURL=fastify.d.ts.map

package/dist/fastify.js

@@ -0,0 +1,53 @@
+/**
+ * Fastify route-handler wrap for request-scoped log context (and optional completion).
+ *
+ * @example
+ * ```ts
+ * import { withFastifyLogging } from "@amkisko/json-logging/fastify";
+ * app.get("/", withFastifyLogging(async (req, reply) => reply.send("ok")));
+ * ```
+ *
+ * @module
+ */
+import { bindLoggerFromOptions, getAmbientHttpLogger } from "./http-ambient.js";
+import { httpFieldsFrom, logRequestCompletion, withHttpContext, } from "./http-context.js";
+/**
+ * Wrap a Fastify route handler so ALS context covers the handler body.
+ * Bind loggers via `./http`.
+ */
+export function withFastifyLogging(handler, options = {}) {
+    bindLoggerFromOptions(options);
+    const headerName = options.headerName ?? "x-request-id";
+    return async function (request, reply) {
+        const input = {
+            method: request.method,
+            url: request.url,
+            headers: request.headers,
+        };
+        const started = Date.now();
+        const fields = httpFieldsFrom(input, headerName);
+        let error;
+        try {
+            return (await withHttpContext(input, () => handler.call(this, request, reply), options));
+        }
+        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: typeof reply.statusCode === "number" ? reply.statusCode : 0,
+                        elapsedMs: Date.now() - started,
+                        error,
+                    });
+                }
+            }
+        }
+    };
+}
+//# sourceMappingURL=fastify.js.map

package/dist/hono.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Hono middleware that attaches request context (and optional completion lines).
+ *
+ * @example
+ * ```ts
+ * import { withHonoLogging } from "@amkisko/json-logging/hono";
+ * app.use(withHonoLogging({ logCompletion: true }));
+ * ```
+ *
+ * @module
+ */
+import type { Logger } from "./logger.js";
+import type { LoggerOptions } from "./types.js";
+/** Minimal Hono context shape (no Hono runtime dependency). */
+export type HonoContextLike = {
+    req: {
+        method: string;
+        url: string;
+        header: (name: string) => string | undefined;
+    };
+    res?: {
+        status: number;
+    };
+};
+/** Options for {@link withHonoLogging}. */
+export type WithHonoLoggingOptions = {
+    headerName?: string;
+    logger?: Logger;
+    loggerOptions?: LoggerOptions;
+    headersAllowlist?: readonly string[];
+    logCompletion?: boolean;
+};
+/** Hono-style middleware function. */
+export type HonoMiddleware = (c: HonoContextLike, next: () => Promise<void>) => Promise<void>;
+/** Build Hono middleware: `(c, next) => ...`. Bind loggers via `./http`. */
+export declare function withHonoLogging(options?: WithHonoLoggingOptions): HonoMiddleware;
+//# sourceMappingURL=hono.d.ts.map

package/dist/hono.js

@@ -0,0 +1,50 @@
+/**
+ * Hono middleware that attaches request context (and optional completion lines).
+ *
+ * @example
+ * ```ts
+ * import { withHonoLogging } from "@amkisko/json-logging/hono";
+ * app.use(withHonoLogging({ logCompletion: true }));
+ * ```
+ *
+ * @module
+ */
+import { bindLoggerFromOptions, getAmbientHttpLogger } from "./http-ambient.js";
+import { httpFieldsFrom, logRequestCompletion, withHttpContext, } from "./http-context.js";
+/** Build Hono middleware: `(c, next) => ...`. Bind loggers via `./http`. */
+export function withHonoLogging(options = {}) {
+    bindLoggerFromOptions(options);
+    const headerName = options.headerName ?? "x-request-id";
+    return async (c, next) => {
+        const existing = c.req.header(headerName) ?? null;
+        const input = {
+            method: c.req.method,
+            url: c.req.url,
+            requestId: existing ?? undefined,
+            headers: {
+                get: (name) => c.req.header(name) ?? null,
+            },
+        };
+        const started = Date.now();
+        const fields = httpFieldsFrom(input, headerName);
+        await withHttpContext(input, async () => {
+            try {
+                await next();
+            }
+            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: c.res?.status ?? 0,
+                            elapsedMs: Date.now() - started,
+                        });
+                    }
+                }
+            }
+        }, options);
+    };
+}
+//# sourceMappingURL=hono.js.map

package/dist/http-ambient.d.ts

@@ -0,0 +1,12 @@
+import type { Logger } from "./logger.js";
+/** Set the process-wide ambient logger used by HTTP adapters. */
+export declare function bindHttpLogger(logger: Logger): void;
+/** Current ambient HTTP logger, if {@link bindHttpLogger} was called. */
+export declare function getAmbientHttpLogger(): Logger | undefined;
+/** Bind options.logger once when building an adapter factory. */
+export declare function bindLoggerFromOptions(options?: {
+    logger?: Logger;
+}): void;
+/** Test helper: clear the shared HTTP ambient logger. */
+export declare function resetHttpLoggerForTests(): void;
+//# sourceMappingURL=http-ambient.d.ts.map

package/dist/http-ambient.js

@@ -0,0 +1,20 @@
+let ambientLogger;
+/** Set the process-wide ambient logger used by HTTP adapters. */
+export function bindHttpLogger(logger) {
+    ambientLogger = logger;
+}
+/** Current ambient HTTP logger, if {@link bindHttpLogger} was called. */
+export function getAmbientHttpLogger() {
+    return ambientLogger;
+}
+/** Bind options.logger once when building an adapter factory. */
+export function bindLoggerFromOptions(options) {
+    if (options?.logger) {
+        bindHttpLogger(options.logger);
+    }
+}
+/** Test helper: clear the shared HTTP ambient logger. */
+export function resetHttpLoggerForTests() {
+    ambientLogger = undefined;
+}
+//# sourceMappingURL=http-ambient.js.map

package/dist/http-context.d.ts

@@ -0,0 +1,65 @@
+import type { Logger } from "./logger.js";
+import type { LoggerOptions } from "./types.js";
+/** Headers-like object with a `get` method (Fetch `Headers`, etc.). */
+export type HeaderBag = {
+    get(name: string): string | null;
+};
+/** Request fields used to build ambient HTTP context. */
+export type HttpRequestInput = {
+    method?: string;
+    url?: string;
+    path?: string;
+    headers?: HeaderBag | Record<string, string | string[] | undefined>;
+    requestId?: string;
+};
+/** Options for {@link withHttpContext} and framework adapters. */
+export type WithHttpContextOptions = {
+    /** Header name for inbound request id. Default `x-request-id`. */
+    headerName?: string;
+    /** Explicit logger; otherwise ambient or a new logger from loggerOptions. */
+    logger?: Logger;
+    /** Used when creating a logger if none is bound. */
+    loggerOptions?: LoggerOptions;
+    /** Optional allowlisted fields merged under http fields (http fields win). */
+    extra?: Record<string, unknown>;
+    /**
+     * Copy these request header names into ALS context (sanitized strings).
+     * Listing Authorization or Cookie is an explicit risk; default is none.
+     */
+    headersAllowlist?: readonly string[];
+    /** When true, adapters emit one completion line after the request. */
+    logCompletion?: boolean;
+};
+/** Fields for {@link logRequestCompletion}. */
+export type RequestCompletionFields = {
+    method?: string;
+    path?: string;
+    status: number;
+    elapsedMs: number;
+    error?: unknown;
+};
+/** Accept inbound request ids that are short and correlation-safe. */
+export declare const REQUEST_ID_PATTERN: RegExp;
+/** Monotonic fallback request id when crypto UUID is unavailable. */
+export declare function fallbackRequestId(now?: () => number): string;
+/** Prefer `crypto.randomUUID`, else {@link fallbackRequestId}. */
+export declare function defaultRandomId(randomUUID?: (() => string) | null): string;
+/** True when `value` matches {@link REQUEST_ID_PATTERN}. */
+export declare function isValidRequestId(value: string): boolean;
+/** Keep a valid inbound id, otherwise allocate a new one. */
+export declare function allocateRequestId(existing: string | null | undefined, randomId?: () => string): string;
+/** Pathname from an absolute or relative URL string. */
+export declare function requestPathFromUrl(url: string): string | undefined;
+/** Pick named keys from a bag; missing keys are omitted. */
+export declare function pickContextKeys(bag: Record<string, unknown> | undefined, keys: readonly string[] | undefined): Record<string, unknown>;
+/** Build requestId / method / path fields from {@link HttpRequestInput}. */
+export declare function httpFieldsFrom(input: HttpRequestInput, headerName?: string): Record<string, unknown>;
+/** Copy allowlisted header names into a sanitized string map. */
+export declare function pickAllowlistedHeaders(headers: HeaderBag | Record<string, string | string[] | undefined> | undefined, names: readonly string[] | undefined): Record<string, unknown>;
+/**
+ * One structured access line. Level is error when status >= 500 or error is set.
+ */
+export declare function logRequestCompletion(logger: Logger, fields: RequestCompletionFields): void;
+/** Run `fn` under ALS context built from the HTTP request input. */
+export declare function withHttpContext<T>(input: HttpRequestInput, fn: () => T | Promise<T>, options?: WithHttpContextOptions): T | Promise<T>;
+//# sourceMappingURL=http-context.d.ts.map