@safaricom-mxl/log 0.0.3

package/dist/types.d.mts

@@ -0,0 +1,496 @@
+//#region src/types.d.ts
+declare module 'nitropack/types' {
+  interface NitroRuntimeHooks {
+    /**
+     * Tail sampling hook - called before emitting a log.
+     * Set `ctx.shouldKeep = true` to force-keep the log regardless of head sampling.
+     *
+     * @example
+     * ```ts
+     * nitroApp.hooks.hook('@safaricom-mxl/log:emit:keep', (ctx) => {
+     *   if (ctx.context.user?.premium) {
+     *     ctx.shouldKeep = true
+     *   }
+     * })
+     * ```
+     */
+    '@safaricom-mxl/log:emit:keep': (ctx: TailSamplingContext) => void | Promise<void>;
+    /**
+     * Enrichment hook - called after emit, before drain.
+     * Use this to enrich the event with derived context (e.g. geo, user agent).
+     *
+     * @example
+     * ```ts
+     * nitroApp.hooks.hook('@safaricom-mxl/log:enrich', (ctx) => {
+     *   ctx.event.deploymentId = process.env.DEPLOYMENT_ID
+     * })
+     * ```
+     */
+    '@safaricom-mxl/log:enrich': (ctx: EnrichContext) => void | Promise<void>;
+    /**
+     * Drain hook - called after emitting a log (fire-and-forget).
+     * Use this to send logs to external services like Axiom, Loki, or custom endpoints.
+     * Errors are logged but never block the request.
+     *
+     * @example
+     * ```ts
+     * nitroApp.hooks.hook('@safaricom-mxl/log:drain', async (ctx) => {
+     *   await fetch('https://api.axiom.co/v1/datasets/logs/ingest', {
+     *     method: 'POST',
+     *     headers: { Authorization: `Bearer ${process.env.AXIOM_TOKEN}` },
+     *     body: JSON.stringify([ctx.event])
+     *   })
+     * })
+     * ```
+     */
+    '@safaricom-mxl/log:drain': (ctx: DrainContext) => void | Promise<void>;
+  }
+}
+declare module 'nitro/types' {
+  interface NitroRuntimeHooks {
+    '@safaricom-mxl/log:emit:keep': (ctx: TailSamplingContext) => void | Promise<void>;
+    '@safaricom-mxl/log:enrich': (ctx: EnrichContext) => void | Promise<void>;
+    '@safaricom-mxl/log:drain': (ctx: DrainContext) => void | Promise<void>;
+  }
+}
+/**
+ * Transport configuration for sending client logs to the server
+ */
+interface TransportConfig {
+  /**
+   * Enable sending logs to the server API
+   * @default false
+   */
+  enabled?: boolean;
+  /**
+   * API endpoint for log ingestion
+   * @default '/api/_mxllog/ingest'
+   */
+  endpoint?: string;
+}
+/**
+ * Payload sent from client to server for log ingestion
+ */
+interface IngestPayload {
+  timestamp: string;
+  level: 'info' | 'error' | 'warn' | 'debug';
+  [key: string]: unknown;
+}
+/**
+ * Sampling rates per log level (0-100 percentage)
+ */
+interface SamplingRates {
+  /** Percentage of info logs to keep (0-100). Default: 100 */
+  info?: number;
+  /** Percentage of warn logs to keep (0-100). Default: 100 */
+  warn?: number;
+  /** Percentage of debug logs to keep (0-100). Default: 100 */
+  debug?: number;
+  /** Percentage of error logs to keep (0-100). Default: 100 */
+  error?: number;
+}
+/**
+ * Tail sampling condition for forcing log retention based on request outcome.
+ * All conditions use >= comparison (e.g., status: 400 means status >= 400).
+ */
+interface TailSamplingCondition {
+  /** Keep if HTTP status >= this value (e.g., 400 for all errors) */
+  status?: number;
+  /** Keep if request duration >= this value in milliseconds */
+  duration?: number;
+  /** Keep if path matches this glob pattern (e.g., '/api/critical/**') */
+  path?: string;
+}
+/**
+ * Context passed to tail sampling evaluation and hooks.
+ * Contains request outcome information for sampling decisions.
+ */
+interface TailSamplingContext {
+  /** HTTP response status code */
+  status?: number;
+  /** Request duration in milliseconds (raw number) */
+  duration?: number;
+  /** Request path */
+  path?: string;
+  /** HTTP method */
+  method?: string;
+  /** Full accumulated context from the request logger */
+  context: Record<string, unknown>;
+  /**
+   * Set to true in mxllog:emit:keep hook to force keep this log.
+   * Multiple hooks can set this - if any sets it to true, the log is kept.
+   */
+  shouldKeep?: boolean;
+}
+/**
+ * Context passed to the mxllog:enrich hook.
+ * Called after emit, before drain.
+ */
+interface EnrichContext {
+  /** The emitted wide event (mutable). */
+  event: WideEvent;
+  /** Request metadata (if available) */
+  request?: {
+    method?: string;
+    path: string;
+    requestId?: string;
+  };
+  /** Safe HTTP request headers (sensitive headers filtered out) */
+  headers?: Record<string, string>;
+  /** Optional response metadata */
+  response?: {
+    status?: number;
+    headers?: Record<string, string>;
+  };
+}
+/**
+ * Context passed to the mxllog:drain hook.
+ * Contains the complete wide event and request metadata for external transport.
+ */
+interface DrainContext {
+  /** The complete wide event to drain */
+  event: WideEvent;
+  /** Request metadata (if available) */
+  request?: {
+    method?: string;
+    path?: string;
+    requestId?: string;
+  };
+  /** HTTP headers from the original request (useful for correlation with external services) */
+  headers?: Record<string, string>;
+}
+/**
+ * Sampling configuration for filtering logs
+ */
+interface SamplingConfig {
+  /**
+   * Sampling rates per log level (head sampling).
+   * Values are percentages from 0 to 100.
+   * Default: 100 for all levels (log everything).
+   * Error defaults to 100 even if not specified.
+   *
+   * @example
+   * ```ts
+   * sampling: {
+   *   rates: {
+   *     info: 10,    // Keep 10% of info logs
+   *     warn: 50,    // Keep 50% of warning logs
+   *     debug: 5,    // Keep 5% of debug logs
+   *     error: 100,  // Always keep errors (default)
+   *   }
+   * }
+   * ```
+   */
+  rates?: SamplingRates;
+  /**
+   * Tail sampling conditions for forcing log retention (OR logic).
+   * If ANY condition matches, the log is kept regardless of head sampling.
+   * Use the `mxllog:emit:keep` Nitro hook for custom conditions.
+   *
+   * @example
+   * ```ts
+   * sampling: {
+   *   rates: { info: 10 },  // Head sampling: keep 10% of info logs
+   *   keep: [
+   *     { status: 400 },     // Always keep if status >= 400
+   *     { duration: 1000 },  // Always keep if duration >= 1000ms
+   *     { path: '/api/critical/**' },  // Always keep critical paths
+   *   ]
+   * }
+   * ```
+   */
+  keep?: TailSamplingCondition[];
+}
+/**
+ * Route-based service configuration
+ */
+interface RouteConfig {
+  /** Service name to use for routes matching this pattern */
+  service: string;
+}
+/**
+ * Environment context automatically included in every log event
+ */
+interface EnvironmentContext {
+  /** Service name (auto-detected from package.json or configurable) */
+  service: string;
+  /** Environment: 'development', 'production', 'test', etc. */
+  environment: 'development' | 'production' | 'test' | string;
+  /** Application version (auto-detected from package.json) */
+  version?: string;
+  /** Git commit hash (auto-detected from CI/CD env vars) */
+  commitHash?: string;
+  /** Deployment region (auto-detected from cloud provider env vars) */
+  region?: string;
+}
+/**
+ * Logger configuration options
+ */
+interface LoggerConfig {
+  /**
+   * Enable or disable all logging globally.
+   * When false, all emits, tagged logs, and request logger operations become no-ops.
+   * @default true
+   */
+  enabled?: boolean;
+  /** Environment context overrides */
+  env?: Partial<EnvironmentContext>;
+  /** Enable pretty printing (auto-detected: true in dev, false in prod) */
+  pretty?: boolean;
+  /** Sampling configuration for filtering logs */
+  sampling?: SamplingConfig;
+  /**
+   * When pretty is disabled, emit JSON strings (default) or raw objects.
+   * Set to false for environments like Cloudflare Workers that expect objects.
+   * @default true
+   */
+  stringify?: boolean;
+  /**
+   * Drain callback called with every emitted event (fire-and-forget).
+   * Use this to send logs to external services outside of Nitro.
+   * Compatible with drain adapters (`createAxiomDrain()`) and pipeline-wrapped drains.
+   *
+   * @example
+   * ```ts
+   * import { initLogger, log } from '@safaricom-mxl/log'
+   * import { createAxiomDrain } from '@safaricom-mxl/log/axiom'
+   *
+   * initLogger({
+   *   drain: createAxiomDrain({ dataset: 'logs', token: '...' }),
+   * })
+   *
+   * log.info({ action: 'user_login' }) // automatically drained
+   * ```
+   *
+   * @example
+   * ```ts
+   * // With pipeline for batching and retry
+   * import { createDrainPipeline } from '@safaricom-mxl/log/pipeline'
+   *
+   * const pipeline = createDrainPipeline({ batch: { size: 25 } })
+   * const drain = pipeline(createAxiomDrain({ dataset: 'logs', token: '...' }))
+   *
+   * initLogger({ drain })
+   *
+   * // Flush on shutdown
+   * process.on('beforeExit', () => drain.flush())
+   * ```
+   */
+  drain?: (ctx: DrainContext) => void | Promise<void>;
+}
+/**
+ * Base structure for all wide events
+ */
+interface BaseWideEvent {
+  timestamp: string;
+  level: 'info' | 'error' | 'warn' | 'debug';
+  service: string;
+  environment: string;
+  version?: string;
+  commitHash?: string;
+  region?: string;
+}
+/**
+ * Wide event with arbitrary additional fields
+ */
+type WideEvent = BaseWideEvent & Record<string, unknown>;
+/**
+ * Recursively makes all properties optional.
+ * Arrays are kept as-is (not deeply partial).
+ */
+type DeepPartial<T> = T extends Array<unknown> ? T : T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } : T;
+/**
+ * Fields set internally by the mxllog plugin (status, service, etc.).
+ * These are always accepted by `set()` regardless of the user-defined field type.
+ */
+interface InternalFields {
+  status?: number;
+  service?: string;
+  requestLogs?: RequestLogEntry[];
+}
+/**
+ * Request-scoped log entry captured during a request lifecycle.
+ */
+interface RequestLogEntry {
+  level: 'info' | 'warn';
+  message: string;
+  timestamp: string;
+}
+/**
+ * Resolved context type for logger methods.
+ * User fields are deeply partial (matching deep merge behavior) with internal
+ * field keys omitted to avoid intersection conflicts, then internal fields
+ * are added back with their canonical types.
+ */
+type FieldContext<T extends object = Record<string, unknown>> = DeepPartial<Omit<T, keyof InternalFields>> & InternalFields;
+/**
+ * Request-scoped logger for building wide events
+ *
+ * @example
+ * ```ts
+ * const logger = useLogger(event)
+ * logger.set({ user: { id: '123' } })
+ * logger.set({ cart: { items: 3 } })
+ * // emit() is called automatically by the plugin
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With typed fields for compile-time safety
+ * interface MyFields {
+ *   user: { id: string; plan: string }
+ *   action: string
+ * }
+ * const logger = useLogger<MyFields>(event)
+ * logger.set({ user: { id: '123', plan: 'pro' } }) // OK
+ * logger.set({ user: { id: '123' } })               // OK (deep partial)
+ * logger.set({ action: 'checkout' })                 // OK
+ * logger.set({ status: 200 })                        // OK (internal field)
+ * logger.set({ account: '...' })                     // TS error
+ * ```
+ */
+interface RequestLogger<T extends object = Record<string, unknown>> {
+  /**
+   * Add context to the wide event (deep merge via defu)
+   */
+  set: (context: FieldContext<T>) => void;
+  /**
+   * Log an error and capture its details
+   */
+  error: (error: Error | string, context?: FieldContext<T>) => void;
+  /**
+   * Capture an informational message inside the request wide event.
+   */
+  info: (message: string, context?: FieldContext<T>) => void;
+  /**
+   * Capture a warning message inside the request wide event.
+   */
+  warn: (message: string, context?: FieldContext<T>) => void;
+  /**
+   * Emit the final wide event with all accumulated context.
+   * Returns the emitted WideEvent, or null if the log was sampled out.
+   */
+  emit: (overrides?: FieldContext<T> & {
+    _forceKeep?: boolean;
+  }) => WideEvent | null;
+  /**
+   * Get the current accumulated context
+   */
+  getContext: () => FieldContext<T> & Record<string, unknown>;
+}
+/**
+ * Log level type
+ */
+type LogLevel = 'info' | 'error' | 'warn' | 'debug';
+/**
+ * Simple logging API - as easy as console.log
+ *
+ * @example
+ * ```ts
+ * log.info('auth', 'User logged in')
+ * log.error({ action: 'payment', error: 'failed' })
+ * ```
+ */
+interface Log {
+  /**
+   * Log an info message or wide event
+   * @example log.info('auth', 'User logged in')
+   * @example log.info({ action: 'login', userId: '123' })
+   */
+  info(tag: string, message: string): void;
+  info(event: Record<string, unknown>): void;
+  /**
+   * Log an error message or wide event
+   * @example log.error('payment', 'Payment failed')
+   * @example log.error({ action: 'payment', error: 'declined' })
+   */
+  error(tag: string, message: string): void;
+  error(event: Record<string, unknown>): void;
+  /**
+   * Log a warning message or wide event
+   * @example log.warn('api', 'Rate limit approaching')
+   * @example log.warn({ action: 'api', remaining: 10 })
+   */
+  warn(tag: string, message: string): void;
+  warn(event: Record<string, unknown>): void;
+  /**
+   * Log a debug message or wide event
+   * @example log.debug('cache', 'Cache miss')
+   * @example log.debug({ action: 'cache', key: 'user_123' })
+   */
+  debug(tag: string, message: string): void;
+  debug(event: Record<string, unknown>): void;
+}
+/**
+ * Error options for creating structured errors
+ */
+interface ErrorOptions {
+  /** What actually happened */
+  message: string;
+  /** HTTP status code (default: 500) */
+  status?: number;
+  /** Why this error occurred */
+  why?: string;
+  /** How to fix this issue */
+  fix?: string;
+  /** Link to documentation or more information */
+  link?: string;
+  /** The original error that caused this */
+  cause?: Error;
+}
+/**
+ * Options for creating a request logger
+ */
+interface RequestLoggerOptions {
+  method?: string;
+  path?: string;
+  requestId?: string;
+}
+/**
+ * H3 event context with mxllog logger attached
+ */
+interface H3EventContext {
+  log?: RequestLogger;
+  requestId?: string;
+  status?: number;
+  /** Internal: start time for duration calculation in tail sampling */
+  _mxllogStartTime?: number;
+  /** Internal: flag to prevent double emission on errors */
+  _mxllogEmitted?: boolean;
+  [key: string]: unknown;
+}
+/**
+ * Server event type for Nitro/h3 handlers
+ */
+interface ServerEvent {
+  method: string;
+  path: string;
+  context: H3EventContext & {
+    /** Cloudflare Workers context (available when deployed to CF Workers) */cloudflare?: {
+      context: {
+        waitUntil: (promise: Promise<unknown>) => void;
+      };
+    }; /** Vercel Edge context (available when deployed to Vercel Edge) */
+    waitUntil?: (promise: Promise<unknown>) => void;
+  };
+  node?: {
+    res?: {
+      statusCode?: number;
+    };
+  };
+  response?: Response;
+}
+/**
+ * Parsed mxllog error with all fields at the top level
+ */
+interface ParsedError {
+  message: string;
+  status: number;
+  why?: string;
+  fix?: string;
+  link?: string;
+  raw: unknown;
+}
+//#endregion
+export { BaseWideEvent, DeepPartial, DrainContext, EnrichContext, EnvironmentContext, ErrorOptions, FieldContext, H3EventContext, IngestPayload, InternalFields, Log, LogLevel, LoggerConfig, ParsedError, RequestLogEntry, RequestLogger, RequestLoggerOptions, RouteConfig, SamplingConfig, SamplingRates, ServerEvent, TailSamplingCondition, TailSamplingContext, TransportConfig, WideEvent };
+//# sourceMappingURL=types.d.mts.map

package/dist/types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","names":[],"sources":["../src/types.ts"],"mappings":"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"}

package/dist/types.mjs

@@ -0,0 +1 @@
+export {  };

package/dist/utils.d.mts

@@ -0,0 +1,34 @@
+import { EnvironmentContext, LogLevel } from "./types.mjs";
+
+//#region src/utils.d.ts
+declare function formatDuration(ms: number): string;
+declare function isServer(): boolean;
+declare function isClient(): boolean;
+declare function isDev(): boolean;
+declare function detectEnvironment(): Partial<EnvironmentContext>;
+declare function getConsoleMethod(level: LogLevel): LogLevel;
+declare const colors: {
+  readonly reset: "\u001B[0m";
+  readonly bold: "\u001B[1m";
+  readonly dim: "\u001B[2m";
+  readonly red: "\u001B[31m";
+  readonly green: "\u001B[32m";
+  readonly yellow: "\u001B[33m";
+  readonly blue: "\u001B[34m";
+  readonly magenta: "\u001B[35m";
+  readonly cyan: "\u001B[36m";
+  readonly white: "\u001B[37m";
+  readonly gray: "\u001B[90m";
+};
+declare function getLevelColor(level: string): string;
+/** Headers that should never be passed to hooks for security */
+declare const SENSITIVE_HEADERS: string[];
+declare function filterSafeHeaders(headers: Record<string, string>): Record<string, string>;
+/**
+ * Match a path against a glob pattern.
+ * Supports * (any chars except /) and ** (any chars including /).
+ */
+declare function matchesPattern(path: string, pattern: string): boolean;
+//#endregion
+export { SENSITIVE_HEADERS, colors, detectEnvironment, filterSafeHeaders, formatDuration, getConsoleMethod, getLevelColor, isClient, isDev, isServer, matchesPattern };
+//# sourceMappingURL=utils.d.mts.map

package/dist/utils.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.mts","names":[],"sources":["../src/utils.ts"],"mappings":";;;iBAEgB,cAAA,CAAe,EAAA;AAAA,iBAOf,QAAA,CAAA;AAAA,iBAIA,QAAA,CAAA;AAAA,iBAIA,KAAA,CAAA;AAAA,iBAUA,iBAAA,CAAA,GAAqB,OAAA,CAAQ,kBAAA;AAAA,iBAmB7B,gBAAA,CAAiB,KAAA,EAAO,QAAA,GAAW,QAAA;AAAA,cAItC,MAAA;EAAA;;;;;;;;;;;;iBAcG,aAAA,CAAc,KAAA;;cAgBjB,iBAAA;AAAA,iBASG,iBAAA,CAAkB,OAAA,EAAS,MAAA,mBAAyB,MAAA;;;;;iBAgBpD,cAAA,CAAe,IAAA,UAAc,OAAA"}

package/dist/utils.mjs

@@ -0,0 +1,78 @@
+//#region src/utils.ts
+function formatDuration(ms) {
+	if (ms < 1e3) return `${Math.round(ms)}ms`;
+	return `${(ms / 1e3).toFixed(2)}s`;
+}
+function isServer() {
+	return typeof window === "undefined";
+}
+function isClient() {
+	return typeof window !== "undefined";
+}
+function isDev() {
+	if (typeof process !== "undefined") return process.env.NODE_ENV !== "production";
+	if (typeof window !== "undefined") return true;
+	return false;
+}
+function detectEnvironment() {
+	const env = typeof process !== "undefined" ? process.env : {};
+	const defaultEnvironment = isDev() ? "development" : "production";
+	return {
+		environment: env.NODE_ENV || defaultEnvironment,
+		service: env.SERVICE_NAME || "app",
+		version: env.APP_VERSION,
+		commitHash: env.COMMIT_SHA || env.GITHUB_SHA || env.VERCEL_GIT_COMMIT_SHA || env.CF_PAGES_COMMIT_SHA,
+		region: env.VERCEL_REGION || env.AWS_REGION || env.FLY_REGION || env.CF_REGION
+	};
+}
+function getConsoleMethod(level) {
+	return level;
+}
+const colors = {
+	reset: "\x1B[0m",
+	bold: "\x1B[1m",
+	dim: "\x1B[2m",
+	red: "\x1B[31m",
+	green: "\x1B[32m",
+	yellow: "\x1B[33m",
+	blue: "\x1B[34m",
+	magenta: "\x1B[35m",
+	cyan: "\x1B[36m",
+	white: "\x1B[37m",
+	gray: "\x1B[90m"
+};
+function getLevelColor(level) {
+	switch (level) {
+		case "error": return colors.red;
+		case "warn": return colors.yellow;
+		case "info": return colors.cyan;
+		case "debug": return colors.gray;
+		default: return colors.white;
+	}
+}
+/** Headers that should never be passed to hooks for security */
+const SENSITIVE_HEADERS = [
+	"authorization",
+	"cookie",
+	"set-cookie",
+	"x-api-key",
+	"x-auth-token",
+	"proxy-authorization"
+];
+function filterSafeHeaders(headers) {
+	const safeHeaders = {};
+	for (const [key, value] of Object.entries(headers)) if (!SENSITIVE_HEADERS.includes(key.toLowerCase())) safeHeaders[key] = value;
+	return safeHeaders;
+}
+/**
+* Match a path against a glob pattern.
+* Supports * (any chars except /) and ** (any chars including /).
+*/
+function matchesPattern(path, pattern) {
+	const regexPattern = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, "{{GLOBSTAR}}").replace(/\*/g, "[^/]*").replace(/{{GLOBSTAR}}/g, ".*").replace(/\?/g, "[^/]");
+	return new RegExp(`^${regexPattern}$`).test(path);
+}
+
+//#endregion
+export { SENSITIVE_HEADERS, colors, detectEnvironment, filterSafeHeaders, formatDuration, getConsoleMethod, getLevelColor, isClient, isDev, isServer, matchesPattern };
+//# sourceMappingURL=utils.mjs.map

package/dist/utils.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.mjs","names":[],"sources":["../src/utils.ts"],"sourcesContent":["import type { EnvironmentContext, LogLevel } from './types'\n\nexport function formatDuration(ms: number): string {\n  if (ms < 1000) {\n    return `${Math.round(ms)}ms`\n  }\n  return `${(ms / 1000).toFixed(2)}s`\n}\n\nexport function isServer(): boolean {\n  return typeof window === 'undefined'\n}\n\nexport function isClient(): boolean {\n  return typeof window !== 'undefined'\n}\n\nexport function isDev(): boolean {\n  if (typeof process !== 'undefined') {\n    return process.env.NODE_ENV !== 'production'\n  }\n  if (typeof window !== 'undefined') {\n    return true\n  }\n  return false\n}\n\nexport function detectEnvironment(): Partial<EnvironmentContext> {\n  const env = typeof process !== 'undefined' ? process.env : {}\n  const defaultEnvironment = isDev() ? 'development' : 'production'\n\n  return {\n    environment: env.NODE_ENV || defaultEnvironment,\n    service: env.SERVICE_NAME || 'app',\n    version: env.APP_VERSION,\n    commitHash: env.COMMIT_SHA\n      || env.GITHUB_SHA\n      || env.VERCEL_GIT_COMMIT_SHA\n      || env.CF_PAGES_COMMIT_SHA,\n    region: env.VERCEL_REGION\n      || env.AWS_REGION\n      || env.FLY_REGION\n      || env.CF_REGION,\n  }\n}\n\nexport function getConsoleMethod(level: LogLevel): LogLevel {\n  return level\n}\n\nexport const colors = {\n  reset: '\\x1B[0m',\n  bold: '\\x1B[1m',\n  dim: '\\x1B[2m',\n  red: '\\x1B[31m',\n  green: '\\x1B[32m',\n  yellow: '\\x1B[33m',\n  blue: '\\x1B[34m',\n  magenta: '\\x1B[35m',\n  cyan: '\\x1B[36m',\n  white: '\\x1B[37m',\n  gray: '\\x1B[90m',\n} as const\n\nexport function getLevelColor(level: string): string {\n  switch (level) {\n    case 'error':\n      return colors.red\n    case 'warn':\n      return colors.yellow\n    case 'info':\n      return colors.cyan\n    case 'debug':\n      return colors.gray\n    default:\n      return colors.white\n  }\n}\n\n/** Headers that should never be passed to hooks for security */\nexport const SENSITIVE_HEADERS = [\n  'authorization',\n  'cookie',\n  'set-cookie',\n  'x-api-key',\n  'x-auth-token',\n  'proxy-authorization',\n]\n\nexport function filterSafeHeaders(headers: Record<string, string>): Record<string, string> {\n  const safeHeaders: Record<string, string> = {}\n\n  for (const [key, value] of Object.entries(headers)) {\n    if (!SENSITIVE_HEADERS.includes(key.toLowerCase())) {\n      safeHeaders[key] = value\n    }\n  }\n\n  return safeHeaders\n}\n\n/**\n * Match a path against a glob pattern.\n * Supports * (any chars except /) and ** (any chars including /).\n */\nexport function matchesPattern(path: string, pattern: string): boolean {\n  const regexPattern = pattern\n    .replace(/[.+^${}()|[\\]\\\\]/g, '\\\\$&') // Escape special regex chars except * and ?\n    .replace(/\\*\\*/g, '{{GLOBSTAR}}') // Temp placeholder for **\n    .replace(/\\*/g, '[^/]*') // * matches anything except /\n    .replace(/{{GLOBSTAR}}/g, '.*') // ** matches anything including /\n    .replace(/\\?/g, '[^/]') // ? matches single char except /\n\n  const regex = new RegExp(`^${regexPattern}$`)\n  return regex.test(path)\n}\n"],"mappings":";AAEA,SAAgB,eAAe,IAAoB;AACjD,KAAI,KAAK,IACP,QAAO,GAAG,KAAK,MAAM,GAAG,CAAC;AAE3B,QAAO,IAAI,KAAK,KAAM,QAAQ,EAAE,CAAC;;AAGnC,SAAgB,WAAoB;AAClC,QAAO,OAAO,WAAW;;AAG3B,SAAgB,WAAoB;AAClC,QAAO,OAAO,WAAW;;AAG3B,SAAgB,QAAiB;AAC/B,KAAI,OAAO,YAAY,YACrB,QAAO,QAAQ,IAAI,aAAa;AAElC,KAAI,OAAO,WAAW,YACpB,QAAO;AAET,QAAO;;AAGT,SAAgB,oBAAiD;CAC/D,MAAM,MAAM,OAAO,YAAY,cAAc,QAAQ,MAAM,EAAE;CAC7D,MAAM,qBAAqB,OAAO,GAAG,gBAAgB;AAErD,QAAO;EACL,aAAa,IAAI,YAAY;EAC7B,SAAS,IAAI,gBAAgB;EAC7B,SAAS,IAAI;EACb,YAAY,IAAI,cACX,IAAI,cACJ,IAAI,yBACJ,IAAI;EACT,QAAQ,IAAI,iBACP,IAAI,cACJ,IAAI,cACJ,IAAI;EACV;;AAGH,SAAgB,iBAAiB,OAA2B;AAC1D,QAAO;;AAGT,MAAa,SAAS;CACpB,OAAO;CACP,MAAM;CACN,KAAK;CACL,KAAK;CACL,OAAO;CACP,QAAQ;CACR,MAAM;CACN,SAAS;CACT,MAAM;CACN,OAAO;CACP,MAAM;CACP;AAED,SAAgB,cAAc,OAAuB;AACnD,SAAQ,OAAR;EACE,KAAK,QACH,QAAO,OAAO;EAChB,KAAK,OACH,QAAO,OAAO;EAChB,KAAK,OACH,QAAO,OAAO;EAChB,KAAK,QACH,QAAO,OAAO;EAChB,QACE,QAAO,OAAO;;;;AAKpB,MAAa,oBAAoB;CAC/B;CACA;CACA;CACA;CACA;CACA;CACD;AAED,SAAgB,kBAAkB,SAAyD;CACzF,MAAM,cAAsC,EAAE;AAE9C,MAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,QAAQ,CAChD,KAAI,CAAC,kBAAkB,SAAS,IAAI,aAAa,CAAC,CAChD,aAAY,OAAO;AAIvB,QAAO;;;;;;AAOT,SAAgB,eAAe,MAAc,SAA0B;CACrE,MAAM,eAAe,QAClB,QAAQ,qBAAqB,OAAO,CACpC,QAAQ,SAAS,eAAe,CAChC,QAAQ,OAAO,QAAQ,CACvB,QAAQ,iBAAiB,KAAK,CAC9B,QAAQ,OAAO,OAAO;AAGzB,QADc,IAAI,OAAO,IAAI,aAAa,GAAG,CAChC,KAAK,KAAK"}

package/dist/workers.d.mts

@@ -0,0 +1,46 @@
+import { LoggerConfig, RequestLogger } from "./types.mjs";
+
+//#region src/workers/index.d.ts
+/**
+ * Options for createWorkersLogger
+ */
+interface WorkersLoggerOptions {
+  /** Override the request ID (default: cf-ray header) */
+  requestId?: string;
+  /** Headers to include in logs (default: none) */
+  headers?: string[];
+}
+/**
+ * Initialize mxllog for Cloudflare Workers.
+ * Call once at module scope.
+ *
+ * @example
+ * ```ts
+ * initWorkersLogger({
+ *   env: { service: 'my-api' },
+ * })
+ * ```
+ */
+declare function initWorkersLogger(options?: LoggerConfig): void;
+/**
+ * Create a request-scoped logger for Cloudflare Workers.
+ * Auto-extracts cf-ray, request.cf context, method, and path.
+ *
+ * @example
+ * ```ts
+ * export default {
+ *   async fetch(request: Request) {
+ *     const log = createWorkersLogger(request)
+ *
+ *     log.set({ user: { id: '123' } })
+ *     log.emit({ status: 200 })
+ *
+ *     return new Response('ok')
+ *   }
+ * }
+ * ```
+ */
+declare function createWorkersLogger<T extends object = Record<string, unknown>>(request: Request, options?: WorkersLoggerOptions): RequestLogger<T>;
+//#endregion
+export { WorkersLoggerOptions, createWorkersLogger, initWorkersLogger };
+//# sourceMappingURL=workers.d.mts.map

package/dist/workers.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workers.d.mts","names":[],"sources":["../src/workers/index.ts"],"mappings":";;;;;AAMA;UAAiB,oBAAA;;EAEf,SAAA;EAEO;EAAP,OAAA;AAAA;;;;AAsEF;;;;;;;;iBArCgB,iBAAA,CAAkB,OAAA,GAAS,YAAA;;;;;;;;;;;;;;;;;;;iBAqC3B,mBAAA,oBAAuC,MAAA,kBAAA,CAAyB,OAAA,EAAS,OAAA,EAAS,OAAA,GAAS,oBAAA,GAA4B,aAAA,CAAc,CAAA"}