@amkisko/json-logging 0.0.0-stage → 0.1.0

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,10 @@
+import type { Logger } from "./logger.js";
+export declare function bindHttpLogger(logger: Logger): void;
+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,18 @@
+let ambientLogger;
+export function bindHttpLogger(logger) {
+    ambientLogger = logger;
+}
+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,49 @@
+import type { Logger } from "./logger.js";
+import type { LoggerOptions } from "./types.js";
+export type HeaderBag = {
+    get(name: string): string | null;
+};
+export type HttpRequestInput = {
+    method?: string;
+    url?: string;
+    path?: string;
+    headers?: HeaderBag | Record<string, string | string[] | undefined>;
+    requestId?: string;
+};
+export type WithHttpContextOptions = {
+    headerName?: string;
+    logger?: Logger;
+    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;
+};
+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;
+export declare function fallbackRequestId(now?: () => number): string;
+export declare function defaultRandomId(randomUUID?: (() => string) | null): string;
+export declare function isValidRequestId(value: string): boolean;
+export declare function allocateRequestId(existing: string | null | undefined, randomId?: () => string): string;
+export declare function requestPathFromUrl(url: string): string | undefined;
+export declare function pickContextKeys(bag: Record<string, unknown> | undefined, keys: readonly string[] | undefined): Record<string, unknown>;
+export declare function httpFieldsFrom(input: HttpRequestInput, headerName?: string): Record<string, unknown>;
+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;
+export declare function withHttpContext<T>(input: HttpRequestInput, fn: () => T | Promise<T>, options?: WithHttpContextOptions): T | Promise<T>;
+//# sourceMappingURL=http-context.d.ts.map

package/dist/http-context.js

@@ -0,0 +1,147 @@
+import { withContext } from "./context.js";
+import { sanitizeError, sanitizeString } from "./sanitize.js";
+/** Accept inbound request ids that are short and correlation-safe. */
+export const REQUEST_ID_PATTERN = /^[\w.\-:]{1,128}$/;
+let fallbackCounter = 0;
+export function fallbackRequestId(now = Date.now) {
+    fallbackCounter += 1;
+    return `req_${now().toString(36)}_${fallbackCounter.toString(36)}`;
+}
+export function defaultRandomId(randomUUID) {
+    const resolved = randomUUID === undefined ? globalThis.crypto?.randomUUID?.bind(globalThis.crypto) : randomUUID;
+    if (typeof resolved === "function") {
+        return resolved();
+    }
+    return fallbackRequestId();
+}
+export function isValidRequestId(value) {
+    return REQUEST_ID_PATTERN.test(value);
+}
+export function allocateRequestId(existing, randomId = defaultRandomId) {
+    if (existing && isValidRequestId(existing)) {
+        return existing;
+    }
+    try {
+        return randomId();
+    }
+    catch {
+        return fallbackRequestId();
+    }
+}
+export function requestPathFromUrl(url) {
+    if (url.length === 0) {
+        return undefined;
+    }
+    try {
+        return new URL(url, "http://localhost").pathname;
+    }
+    catch {
+        const query = url.indexOf("?");
+        const hash = url.indexOf("#");
+        let end = url.length;
+        if (query >= 0) {
+            end = query;
+        }
+        if (hash >= 0 && hash < end) {
+            end = hash;
+        }
+        const path = url.slice(0, end);
+        return path.length > 0 ? path : undefined;
+    }
+}
+function isHeaderBag(value) {
+    return typeof Reflect.get(value, "get") === "function";
+}
+function headerGet(headers, name) {
+    if (!headers) {
+        return null;
+    }
+    if (isHeaderBag(headers)) {
+        return headers.get(name);
+    }
+    const direct = Reflect.get(headers, name) ?? Reflect.get(headers, name.toLowerCase());
+    if (Array.isArray(direct)) {
+        const first = direct[0];
+        return typeof first === "string" ? first : null;
+    }
+    return typeof direct === "string" ? direct : null;
+}
+export function pickContextKeys(bag, keys) {
+    if (!bag || !keys || keys.length === 0) {
+        return {};
+    }
+    const out = {};
+    for (const key of keys) {
+        if (Object.hasOwn(bag, key)) {
+            out[key] = bag[key];
+        }
+    }
+    return out;
+}
+export function httpFieldsFrom(input, headerName = "x-request-id") {
+    const fromHeader = headerGet(input.headers, headerName);
+    const requestId = allocateRequestId(input.requestId ?? fromHeader);
+    const fields = { requestId };
+    if (input.method) {
+        fields.method = input.method;
+    }
+    const path = input.path ?? (input.url ? requestPathFromUrl(input.url) : undefined);
+    if (path) {
+        fields.path = path;
+    }
+    return fields;
+}
+export function pickAllowlistedHeaders(headers, names) {
+    if (!headers || !names || names.length === 0) {
+        return {};
+    }
+    const out = {};
+    for (const name of names) {
+        const value = headerGet(headers, name);
+        if (value !== null && value.length > 0) {
+            out[name] = sanitizeString(value);
+        }
+    }
+    return out;
+}
+/**
+ * One structured access line. Level is error when status >= 500 or error is set.
+ */
+export function logRequestCompletion(logger, fields) {
+    const payload = {
+        event: "http_request",
+        status: fields.status,
+        elapsedMs: fields.elapsedMs,
+    };
+    if (fields.method) {
+        payload.method = fields.method;
+    }
+    if (fields.path) {
+        payload.path = fields.path;
+    }
+    if (fields.error instanceof Error) {
+        Object.assign(payload, sanitizeError(fields.error));
+    }
+    else if (fields.error !== undefined) {
+        payload.error = {
+            message: sanitizeString(String(fields.error)),
+        };
+    }
+    const level = fields.status >= 500 || fields.error !== undefined ? "error" : "info";
+    if (level === "error") {
+        logger.error(payload);
+    }
+    else {
+        logger.info(payload);
+    }
+}
+export function withHttpContext(input, fn, options = {}) {
+    const headerName = options.headerName ?? "x-request-id";
+    const fields = {
+        ...pickAllowlistedHeaders(input.headers, options.headersAllowlist),
+        ...(options.extra ?? {}),
+        ...httpFieldsFrom(input, headerName),
+    };
+    return withContext(fields, fn);
+}
+//# sourceMappingURL=http-context.js.map

package/dist/http.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Shared HTTP helpers: ambient logger binding, request context, and completion lines.
+ * Framework adapters live on separate entrypoints (`./hono`, `./express`, ...).
+ *
+ * @example
+ * ```ts
+ * import { bindHttpLogger, httpLogger, withHttpContext } from "@amkisko/json-logging/http";
+ *
+ * bindHttpLogger(httpLogger({ loggerOptions: { base: { service: "api" } } }));
+ * await withHttpContext({ method: "GET", path: "/" }, () => {
+ *   httpLogger().info("inside request");
+ * });
+ * ```
+ *
+ * @module
+ */
+import type { WithHttpContextOptions } from "./http-context.js";
+import type { Logger } from "./logger.js";
+export { bindHttpLogger, bindLoggerFromOptions, resetHttpLoggerForTests, } from "./http-ambient.js";
+export type { HeaderBag, HttpRequestInput, RequestCompletionFields, WithHttpContextOptions, } from "./http-context.js";
+export { allocateRequestId, defaultRandomId, fallbackRequestId, httpFieldsFrom, isValidRequestId, logRequestCompletion, pickAllowlistedHeaders, pickContextKeys, REQUEST_ID_PATTERN, requestPathFromUrl, withHttpContext, } from "./http-context.js";
+/** Resolve the ambient HTTP logger, or create and bind one from options. */
+export declare function httpLogger(options?: WithHttpContextOptions): Logger;
+//# sourceMappingURL=http.d.ts.map