evlog 2.4.0 → 2.5.0

package/dist/types-CRj5tGVA.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('evlog:emit:keep', (ctx) => {
+     *   if (ctx.context.user?.premium) {
+     *     ctx.shouldKeep = true
+     *   }
+     * })
+     * ```
+     */
+    'evlog: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('evlog:enrich', (ctx) => {
+     *   ctx.event.deploymentId = process.env.DEPLOYMENT_ID
+     * })
+     * ```
+     */
+    'evlog: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('evlog: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])
+     *   })
+     * })
+     * ```
+     */
+    'evlog:drain': (ctx: DrainContext) => void | Promise<void>;
+  }
+}
+declare module 'nitro/types' {
+  interface NitroRuntimeHooks {
+    'evlog:emit:keep': (ctx: TailSamplingContext) => void | Promise<void>;
+    'evlog:enrich': (ctx: EnrichContext) => void | Promise<void>;
+    'evlog: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/_evlog/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 evlog: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 evlog: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 evlog: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 `evlog: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 'evlog'
+   * import { createAxiomDrain } from 'evlog/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 'evlog/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 evlog 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 evlog logger attached
+ */
+interface H3EventContext {
+  log?: RequestLogger;
+  requestId?: string;
+  status?: number;
+  /** Internal: start time for duration calculation in tail sampling */
+  _evlogStartTime?: number;
+  /** Internal: flag to prevent double emission on errors */
+  _evlogEmitted?: 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 evlog error with all fields at the top level
+ */
+interface ParsedError {
+  message: string;
+  status: number;
+  why?: string;
+  fix?: string;
+  link?: string;
+  raw: unknown;
+}
+//#endregion
+export { TailSamplingContext as C, TailSamplingCondition as S, WideEvent as T, RequestLoggerOptions as _, EnvironmentContext as a, SamplingRates as b, H3EventContext as c, Log as d, LogLevel as f, RequestLogger as g, RequestLogEntry as h, EnrichContext as i, IngestPayload as l, ParsedError as m, DeepPartial as n, ErrorOptions as o, LoggerConfig as p, DrainContext as r, FieldContext as s, BaseWideEvent as t, InternalFields as u, RouteConfig as v, TransportConfig as w, ServerEvent as x, SamplingConfig as y };
+//# sourceMappingURL=types-CRj5tGVA.d.mts.map

package/dist/types-CRj5tGVA.d.mts.map

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