logixlysia 6.6.0 → 6.7.0

package/README.md

@@ -1,7 +1,7 @@
 <div align="center">
   <h1><code>🦊</code> Logixlysia</h1>
   <strong>Logixlysia is a logging library for ElysiaJS</strong>
-  <img src="https://github.com/PunGrumpy/logixlysia/blob/main/apps/docs/app/opengraph-image.png?raw=true" alt="Logixlysia" width="100%" height="auto" />
+  <img src="https://github.com/PunGrumpy/logixlysia/blob/main/apps/docs/public/opengraph-image.png?raw=true" alt="Logixlysia" width="100%" height="auto" />
 </div>
 
 ## `📩` Installation

package/dist/ai.d.ts

@@ -1,10 +1,4 @@
 import { Logger as PinoLogger } from "pino";
-type Pino = PinoLogger<never, boolean>;
-type RequestInfo = Request;
-type LogLevel = "DEBUG" | "INFO" | "WARNING" | "ERROR";
-interface StoreData {
-	beforeTime: bigint;
-}
 interface Logger {
 	debug: (request: RequestInfo, message: string, context?: Record<string, unknown>) => void;
 	error: (request: RequestInfo, message: string, context?: Record<string, unknown>) => void;
@@ -16,6 +10,12 @@ interface Logger {
 	pino: Pino;
 	warn: (request: RequestInfo, message: string, context?: Record<string, unknown>) => void;
 }
+type Pino = PinoLogger<never, boolean>;
+type RequestInfo = Request;
+type LogLevel = "DEBUG" | "INFO" | "WARNING" | "ERROR";
+interface StoreData {
+	beforeTime: bigint;
+}
 interface AIMetrics {
 	calls?: number;
 	finishReason?: string;
@@ -34,4 +34,4 @@ interface AIMetrics {
 * on the final access log (evlog-style `ai` object).
 */
 declare const mergeAIMetrics: (logger: Pick<Logger, "mergeContext">, request: Request, metrics: AIMetrics) => void;
-export { mergeAIMetrics, mergeAIMetrics as default, AIMetrics };
+export { mergeAIMetrics, AIMetrics };

package/dist/ai.js

@@ -1,4 +1,4 @@
-var z=(k,w,d)=>{if(Object.keys(d).length===0)return;k.mergeContext(w,{ai:d})};export{z as mergeAIMetrics,z as default};
+var z=(k,w,d)=>{if(Object.keys(d).length===0)return;k.mergeContext(w,{ai:d})};export{z as mergeAIMetrics};
 
-//# debugId=1C3753C5E33BE73A64756E2164756E21
-//# sourceMappingURL=data:application/json;base64,ewogICJ2ZXJzaW9uIjogMywKICAic291cmNlcyI6IFsic3JjL2FpLnRzIl0sCiAgInNvdXJjZXNDb250ZW50IjogWwogICAgImltcG9ydCB0eXBlIHsgTG9nZ2VyIH0gZnJvbSAnLi9pbnRlcmZhY2VzJ1xuXG5leHBvcnQgaW50ZXJmYWNlIEFJTWV0cmljcyB7XG4gIGNhbGxzPzogbnVtYmVyXG4gIGZpbmlzaFJlYXNvbj86IHN0cmluZ1xuICBpbnB1dFRva2Vucz86IG51bWJlclxuICBtb2RlbD86IHN0cmluZ1xuICBtc1RvRmluaXNoPzogbnVtYmVyXG4gIG1zVG9GaXJzdENodW5rPzogbnVtYmVyXG4gIG91dHB1dFRva2Vucz86IG51bWJlclxuICBwcm92aWRlcj86IHN0cmluZ1xuICByZWFzb25pbmdUb2tlbnM/OiBudW1iZXJcbiAgdG9rZW5zUGVyU2Vjb25kPzogbnVtYmVyXG4gIHRvdGFsVG9rZW5zPzogbnVtYmVyXG59XG5cbi8qKlxuICogTWVyZ2VzIEFJIFNESyAvIExMTSB1c2FnZSBtZXRyaWNzIGludG8gdGhlIHJlcXVlc3QgY29udGV4dCBiYWcgc28gdGhleSBhcHBlYXJcbiAqIG9uIHRoZSBmaW5hbCBhY2Nlc3MgbG9nIChldmxvZy1zdHlsZSBgYWlgIG9iamVjdCkuXG4gKi9cbmV4cG9ydCBjb25zdCBtZXJnZUFJTWV0cmljcyA9IChcbiAgbG9nZ2VyOiBQaWNrPExvZ2dlciwgJ21lcmdlQ29udGV4dCc+LFxuICByZXF1ZXN0OiBSZXF1ZXN0LFxuICBtZXRyaWNzOiBBSU1ldHJpY3Ncbik6IHZvaWQgPT4ge1xuICBpZiAoT2JqZWN0LmtleXMobWV0cmljcykubGVuZ3RoID09PSAwKSB7XG4gICAgcmV0dXJuXG4gIH1cbiAgbG9nZ2VyLm1lcmdlQ29udGV4dChyZXF1ZXN0LCB7IGFpOiBtZXRyaWNzIH0pXG59XG5cbmV4cG9ydCB7IG1lcmdlQUlNZXRyaWNzIGFzIGRlZmF1bHQgfVxuIgogIF0sCiAgIm1hcHBpbmdzIjogIkFBb0JPLElBQU0sRUFBaUIsQ0FDNUIsRUFDQSxFQUNBLElBQ1MsQ0FDVCxHQUFJLE9BQU8sS0FBSyxDQUFPLEVBQUUsU0FBVyxFQUNsQyxPQUVGLEVBQU8sYUFBYSxFQUFTLENBQUUsR0FBSSxDQUFRLENBQUMiLAogICJkZWJ1Z0lkIjogIjFDMzc1M0M1RTMzQkU3M0E2NDc1NkUyMTY0NzU2RTIxIiwKICAibmFtZXMiOiBbXQp9
+//# debugId=2447CBBCE831480664756E2164756E21
+//# sourceMappingURL=data:application/json;base64,ewogICJ2ZXJzaW9uIjogMywKICAic291cmNlcyI6IFsic3JjL2FpLnRzIl0sCiAgInNvdXJjZXNDb250ZW50IjogWwogICAgImltcG9ydCB0eXBlIHsgTG9nZ2VyIH0gZnJvbSAnLi9pbnRlcmZhY2VzJ1xuXG5leHBvcnQgaW50ZXJmYWNlIEFJTWV0cmljcyB7XG4gIGNhbGxzPzogbnVtYmVyXG4gIGZpbmlzaFJlYXNvbj86IHN0cmluZ1xuICBpbnB1dFRva2Vucz86IG51bWJlclxuICBtb2RlbD86IHN0cmluZ1xuICBtc1RvRmluaXNoPzogbnVtYmVyXG4gIG1zVG9GaXJzdENodW5rPzogbnVtYmVyXG4gIG91dHB1dFRva2Vucz86IG51bWJlclxuICBwcm92aWRlcj86IHN0cmluZ1xuICByZWFzb25pbmdUb2tlbnM/OiBudW1iZXJcbiAgdG9rZW5zUGVyU2Vjb25kPzogbnVtYmVyXG4gIHRvdGFsVG9rZW5zPzogbnVtYmVyXG59XG5cbi8qKlxuICogTWVyZ2VzIEFJIFNESyAvIExMTSB1c2FnZSBtZXRyaWNzIGludG8gdGhlIHJlcXVlc3QgY29udGV4dCBiYWcgc28gdGhleSBhcHBlYXJcbiAqIG9uIHRoZSBmaW5hbCBhY2Nlc3MgbG9nIChldmxvZy1zdHlsZSBgYWlgIG9iamVjdCkuXG4gKi9cbmV4cG9ydCBjb25zdCBtZXJnZUFJTWV0cmljcyA9IChcbiAgbG9nZ2VyOiBQaWNrPExvZ2dlciwgJ21lcmdlQ29udGV4dCc+LFxuICByZXF1ZXN0OiBSZXF1ZXN0LFxuICBtZXRyaWNzOiBBSU1ldHJpY3Ncbik6IHZvaWQgPT4ge1xuICBpZiAoT2JqZWN0LmtleXMobWV0cmljcykubGVuZ3RoID09PSAwKSB7XG4gICAgcmV0dXJuXG4gIH1cbiAgbG9nZ2VyLm1lcmdlQ29udGV4dChyZXF1ZXN0LCB7IGFpOiBtZXRyaWNzIH0pXG59XG4iCiAgXSwKICAibWFwcGluZ3MiOiAiQUFvQk8sSUFBTSxFQUFpQixDQUM1QixFQUNBLEVBQ0EsSUFDUyxDQUNULEdBQUksT0FBTyxLQUFLLENBQU8sRUFBRSxTQUFXLEVBQ2xDLE9BRUYsRUFBTyxhQUFhLEVBQVMsQ0FBRSxHQUFJLENBQVEsQ0FBQyIsCiAgImRlYnVnSWQiOiAiMjQ0N0NCQkNFODMxNDgwNjY0NzU2RTIxNjQ3NTZFMjEiLAogICJuYW1lcyI6IFtdCn0=

package/dist/index.d.ts

@@ -1,5 +1,24 @@
 import { Elysia } from "elysia";
-import { Logger as PinoLogger, LoggerOptions as PinoLoggerOptions } from "pino";
+import { LoggerOptions as PinoLoggerOptions } from "pino";
+import { Logger as PinoLogger } from "pino";
+interface Logger {
+	debug: (request: RequestInfo, message: string, context?: Record<string, unknown>) => void;
+	error: (request: RequestInfo, message: string, context?: Record<string, unknown>) => void;
+	getContext: (key: RequestInfo | object) => Readonly<Record<string, unknown>>;
+	handleHttpError: (request: RequestInfo, error: unknown, store: StoreData) => void;
+	info: (request: RequestInfo, message: string, context?: Record<string, unknown>) => void;
+	log: (level: LogLevel, request: RequestInfo, data: Record<string, unknown>, store: StoreData) => void;
+	mergeContext: (key: RequestInfo | object, partial: Record<string, unknown>) => void;
+	pino: Pino;
+	warn: (request: RequestInfo, message: string, context?: Record<string, unknown>) => void;
+}
+interface RequestScopedLogger {
+	debug: (message: string, context?: Record<string, unknown>) => void;
+	error: (message: string, context?: Record<string, unknown>) => void;
+	info: (message: string, context?: Record<string, unknown>) => void;
+	mergeContext: (partial: Record<string, unknown>) => void;
+	warn: (message: string, context?: Record<string, unknown>) => void;
+}
 type Pino = PinoLogger<never, boolean>;
 type RequestInfo = Request;
 type LogLevel = "DEBUG" | "INFO" | "WARNING" | "ERROR";
@@ -11,6 +30,10 @@ interface LogixlysiaStore {
 	logger: Logger;
 	pino: Pino;
 }
+interface LogixlysiaContext {
+	request: Request;
+	store: LogixlysiaStore;
+}
 interface Transport {
 	log: (level: LogLevel, message: string, meta?: Record<string, unknown>) => void | Promise<void>;
 }
@@ -18,7 +41,9 @@ interface LogRotationConfig {
 	compress?: boolean;
 	compression?: "gzip";
 	/**
-	* Rotate at a fixed interval, e.g. '1d', '12h'.
+	* Rotate when the live file's age reaches a fixed interval, evaluated on
+	* write (an idle process rotates on its next write, not on a timer).
+	* Format: number + 'h' | 'd' | 'w', e.g. '12h', '1d', '1w'.
 	*/
 	interval?: string;
 	/**
@@ -48,6 +73,11 @@ interface LogFilter {
 */
 type PrettyPrintConfig = boolean | Record<string, unknown>;
 type LogPreset = "dev" | "prod" | "json";
+/** Context passed to {@link Options.config.onError} when a sink fails. */
+interface SinkErrorContext {
+	error: unknown;
+	sink: "file" | "rotation" | "transport";
+}
 interface RequestIdConfig {
 	/**
 	* Enable request ID generation.
@@ -65,93 +95,105 @@ interface RequestIdConfig {
 	*/
 	header?: string;
 }
-interface Options {
-	config?: {
-		showStartupMessage?: boolean;
-		startupMessageFormat?: "simple" | "banner";
-		useColors?: boolean;
-		ip?: boolean;
-		timestamp?: {
-			translateTime?: string;
-		};
-		customLogFormat?: string;
-		/** Service name shown in `{service}` token (e.g. evlog-style `[my-app]`). */
-		service?: string;
-		/** Duration (ms) below this uses green; default 500. */
-		slowThreshold?: number;
-		/** Duration (ms) at or above this uses red + `{speed}` badge; default 1000. */
-		verySlowThreshold?: number;
-		/** Render `data.context` as tree lines under the main log line; default true. */
-		showContextTree?: boolean;
-		/** How many object nesting levels to expand in the context tree; default 1. */
-		contextDepth?: number;
-		/** Include query parameters in the logged URL path; default false. */
-		logQueryParams?: boolean;
-		/** Skip automatic WebSocket lifecycle logs from `wrapWs`; default false. */
-		disableWebSocketLogging?: boolean;
-		/**
-		* Enable automatic request ID generation and propagation.
-		*
-		* - `true`: Enable with defaults (`X-Request-Id` header, `crypto.randomUUID()` generator).
-		* - `false` or `undefined`: Disabled (default).
-		* - `RequestIdConfig` object: Enable with custom header name and/or generator.
-		*
-		* When enabled, the plugin will:
-		* 1. Read `X-Request-Id` (or custom header) from the incoming request — honoring IDs set by upstream proxies.
-		* 2. Generate a new UUID if no header is present.
-		* 3. Merge `{ requestId }` into the request context (appears in logs and context tree).
-		* 4. Set the header on the outgoing response for client-side tracing.
-		*/
-		requestId?: boolean | RequestIdConfig;
-		logFilter?: LogFilter;
-		transports?: Transport[];
-		useTransportsOnly?: boolean;
-		disableInternalLogger?: boolean;
-		disableFileLogging?: boolean;
-		logFilePath?: string;
-		logRotation?: LogRotationConfig;
-		/**
-		* Automatically redact sensitive information (PII) from logs.
-		* Masks emails, IP addresses, Luhn-valid payment card numbers, and JWTs in strings and deeply nested objects.
-		*/
-		autoRedact?: boolean;
-		pino?: (PinoLoggerOptions & {
-			prettyPrint?: PrettyPrintConfig;
-		}) | undefined;
-		/**
-		* Enable request-scoped logger propagation via AsyncLocalStorage.
-		* When enabled, a request-scoped logger `log` is also derived on the Elysia context.
-		* @default false
-		*/
-		useAsyncLocalStorage?: boolean;
+interface FormattingConfig {
+	/** How many object nesting levels to expand in the context tree; default 1. */
+	contextDepth?: number;
+	customLogFormat?: string;
+	ip?: boolean;
+	/** Include query parameters in the logged URL path; default false. */
+	logQueryParams?: boolean;
+	/** Service name shown in `{service}` token (e.g. evlog-style `[my-app]`). */
+	service?: string;
+	/** Render `data.context` as tree lines under the main log line; default true. */
+	showContextTree?: boolean;
+	showStartupMessage?: boolean;
+	/** Duration (ms) below this uses green; default 500. */
+	slowThreshold?: number;
+	startupMessageFormat?: "simple" | "banner";
+	timestamp?: {
+		translateTime?: string;
 	};
+	useColors?: boolean;
+	/** Duration (ms) at or above this uses red + `{speed}` badge; default 1000. */
+	verySlowThreshold?: number;
+}
+interface OutputConfig {
+	disableFileLogging?: boolean;
+	disableInternalLogger?: boolean;
+	/** Directory mode for created log directories. @default 0o700 */
+	logDirMode?: number;
+	/** File mode for created log files. @default 0o600 */
+	logFileMode?: number;
+	logFilePath?: string;
+	logRotation?: LogRotationConfig;
 	/**
-	* Opinionated defaults for common environments.
-	* Explicit `config` fields override preset values.
+	* Called when a sink (transport, file, rotation) fails. Errors thrown by
+	* the hook itself are swallowed. When absent, failures go to stderr
+	* (rate-limited for transports).
 	*/
-	preset?: LogPreset;
+	onError?: (context: SinkErrorContext) => void;
+	transports?: Transport[];
+	useTransportsOnly?: boolean;
 }
-interface Logger {
-	debug: (request: RequestInfo, message: string, context?: Record<string, unknown>) => void;
-	error: (request: RequestInfo, message: string, context?: Record<string, unknown>) => void;
-	getContext: (key: RequestInfo | object) => Readonly<Record<string, unknown>>;
-	handleHttpError: (request: RequestInfo, error: unknown, store: StoreData) => void;
-	info: (request: RequestInfo, message: string, context?: Record<string, unknown>) => void;
-	log: (level: LogLevel, request: RequestInfo, data: Record<string, unknown>, store: StoreData) => void;
-	mergeContext: (key: RequestInfo | object, partial: Record<string, unknown>) => void;
-	pino: Pino;
-	warn: (request: RequestInfo, message: string, context?: Record<string, unknown>) => void;
+interface RedactionConfig {
+	/**
+	* Automatically redact sensitive information (PII) from logs.
+	* Masks emails, IP addresses, Luhn-valid payment card numbers, and JWTs in strings and deeply nested objects.
+	*/
+	autoRedact?: boolean;
+	/**
+	* Log the offending payload (`found`/`errors`) from validation errors.
+	* Off by default: request bodies routinely contain credentials.
+	* @default false
+	*/
+	logErrorPayload?: boolean;
+	/**
+	* Additional key/header names (case-insensitive; `-`/`_`/camelCase variants
+	* are normalized) whose values are redacted when `autoRedact` is enabled.
+	* Extends the built-in list (authorization, cookie, x-api-key, password,
+	* secret, token, session, …).
+	*/
+	redactKeys?: string[];
 }
-interface RequestScopedLogger {
-	debug: (message: string, context?: Record<string, unknown>) => void;
-	error: (message: string, context?: Record<string, unknown>) => void;
-	info: (message: string, context?: Record<string, unknown>) => void;
-	mergeContext: (partial: Record<string, unknown>) => void;
-	warn: (message: string, context?: Record<string, unknown>) => void;
+interface RequestTrackingConfig {
+	/** Skip automatic WebSocket lifecycle logs from `wrapWs`; default false. */
+	disableWebSocketLogging?: boolean;
+	/**
+	* Enable automatic request ID generation and propagation.
+	*
+	* - `true`: Enable with defaults (`X-Request-Id` header, `crypto.randomUUID()` generator).
+	* - `false` or `undefined`: Disabled (default).
+	* - `RequestIdConfig` object: Enable with custom header name and/or generator.
+	*
+	* When enabled, the plugin will:
+	* 1. Read `X-Request-Id` (or custom header) from the incoming request — honoring IDs set by upstream proxies.
+	* 2. Generate a new UUID if no header is present.
+	* 3. Merge `{ requestId }` into the request context (appears in logs and context tree).
+	* 4. Set the header on the outgoing response for client-side tracing.
+	*/
+	requestId?: boolean | RequestIdConfig;
+	/**
+	* Enable request-scoped logger propagation via AsyncLocalStorage.
+	* When enabled, a request-scoped logger `log` is also derived on the Elysia context.
+	* @default false
+	*/
+	useAsyncLocalStorage?: boolean;
 }
-interface LogixlysiaContext {
-	request: Request;
-	store: LogixlysiaStore;
+interface PinoConfig {
+	pino?: (PinoLoggerOptions & {
+		prettyPrint?: PrettyPrintConfig;
+	}) | undefined;
+}
+interface LogixlysiaConfig extends FormattingConfig, OutputConfig, RedactionConfig, RequestTrackingConfig, PinoConfig {
+	logFilter?: LogFilter;
+}
+interface Options {
+	config?: LogixlysiaConfig;
+	/**
+	* Opinionated defaults for common environments.
+	* Explicit `config` fields override preset values.
+	*/
+	preset?: LogPreset;
 }
 /** HTTP `Request` or WebSocket instance for accumulated context. */
 type ContextKey = Request | object;
@@ -159,6 +201,13 @@ interface RequestContextStore {
 	clearContext: (key: ContextKey) => void;
 	getContext: (key: ContextKey) => Readonly<Record<string, unknown>>;
 	mergeContext: (key: ContextKey, partial: Record<string, unknown>) => void;
+	/**
+	* Non-cloning read of the live context bag. Returns the SAME object stored internally (or a
+	* shared frozen empty object) — never hand this to user-facing code, which may retain or
+	* mutate it. Only internal, read-only call sites (that immediately spread the result into a
+	* new object) may use this; everything else must use {@link RequestContextStore.getContext}.
+	*/
+	peekContext: (key: ContextKey) => Readonly<Record<string, unknown>>;
 }
 interface WebSocketLike {
 	readonly data?: {
@@ -204,6 +253,11 @@ declare const resolveRequestIdConfig: (raw?: boolean | RequestIdConfig) => Resol
 /**
 * Reads an existing request ID from the incoming request header, or generates a
 * new one using the configured generator.
+*
+* Inbound values are validated against `VALID_REQUEST_ID` (alphanumeric plus
+* `.`, `_`, `-`, 1-128 chars) before being trusted — request IDs flow into log
+* lines, response headers, and context trees, so malformed or oversized
+* values are replaced with a freshly generated one rather than echoed back.
 */
 declare const getOrCreateRequestId: (request: Request, config: ResolvedRequestIdConfig) => string;
 /**
@@ -230,4 +284,4 @@ type LogixlysiaPlugin = Logixlysia & {
 	wrapWs: ReturnType<typeof createWsHandlerWrapper>;
 };
 declare const logixlysia: (rawOptions?: Options) => LogixlysiaPlugin;
-export { useLogger, resolveRequestIdConfig, resolveOptions, logixlysia, getOrCreateRequestId, logixlysia as default, createWsHandlerWrapper, createPluginLogger, createLogger, WsHandlerHooks, Transport, StoreData, ResolvedRequestIdConfig, RequestScopedLogger, RequestIdConfig, Pino, Options, LogixlysiaStore, LogixlysiaSingleton, LogixlysiaPlugin, LogixlysiaContext, Logixlysia, Logger, LogPreset, LogLevel, EmptyElysiaSlot };
+export { useLogger, resolveRequestIdConfig, resolveOptions, getOrCreateRequestId, logixlysia as default, createWsHandlerWrapper, createPluginLogger, createLogger, WsHandlerHooks, Transport, StoreData, ResolvedRequestIdConfig, RequestScopedLogger, RequestIdConfig, Pino, Options, LogixlysiaStore, LogixlysiaSingleton, LogixlysiaPlugin, LogixlysiaContext, Logixlysia, Logger, LogPreset, LogLevel, EmptyElysiaSlot };