@visulima/pail 3.2.2 → 4.0.0-alpha.10

package/dist/wide-event.d.ts

@@ -0,0 +1,300 @@
+import type { PailBrowserImpl } from "./pail.d.ts";
+import type { DefaultLogTypes, LoggerFunction } from "./types.d.ts";
+/**
+ * A pail instance with dynamically generated log methods.
+ * This is the minimal interface WideEvent needs from a pail logger.
+ */
+type PailLike<T extends string = string> = PailBrowserImpl<T> & Record<DefaultLogTypes | T, LoggerFunction>;
+/**
+ * Makes all properties in T optional recursively.
+ */
+type DeepPartial<T> = {
+    [K in keyof T]?: T[K] extends Record<string, unknown> ? DeepPartial<T[K]> : T[K];
+};
+/**
+ * Severity levels for wide events.
+ */
+export type WideEventLevel = "debug" | "error" | "info" | "warn";
+/**
+ * An entry in the request lifecycle log.
+ */
+export interface RequestLogEntry {
+    /**
+     * Additional structured context for this log entry.
+     */
+    context?: Record<string, unknown>;
+    /**
+     * Severity level of this entry.
+     */
+    level: WideEventLevel;
+    /**
+     * Human-readable message describing what happened.
+     */
+    message: string;
+    /**
+     * ISO 8601 timestamp of when this entry was recorded.
+     */
+    timestamp: string;
+}
+/**
+ * Serialized error information included in the emitted wide event.
+ */
+export interface SerializedError {
+    cause?: SerializedError;
+    data?: unknown;
+    message: string;
+    name: string;
+    stack?: string;
+    status?: number;
+}
+/**
+ * Options for finishing a wide event with HTTP context.
+ */
+export interface WideEventFinishOptions {
+    /**
+     * An error that occurred during the operation.
+     * Will be serialized and included in the emitted event.
+     */
+    error?: Error;
+    /**
+     * HTTP response status code.
+     */
+    status?: number;
+}
+/**
+ * Options for creating a WideEvent instance.
+ * @template T - Custom logger type names
+ */
+export interface WideEventOptions<T extends string = string> {
+    /**
+     * Auto-emit the event when disposed via `Symbol.dispose`.
+     * Works with TC39 Explicit Resource Management (`using`).
+     * @default true
+     */
+    autoEmit?: boolean;
+    /**
+     * Event name identifying this wide event, e.g. "api.checkout", "worker.send-email".
+     */
+    name: string;
+    /**
+     * The pail logger instance to use for emission.
+     */
+    pail: PailLike<T>;
+    /**
+     * Service name for this event. Overrides any service name from pail's scope.
+     */
+    service?: string;
+    /**
+     * Base log type to use when emitting. Defaults to "info".
+     * The actual type may be escalated based on logged warnings/errors.
+     */
+    type?: DefaultLogTypes | T;
+}
+/**
+ * A wide event logger that accumulates context incrementally and emits
+ * a single comprehensive log event through pail.
+ *
+ * Instead of scattering multiple log calls throughout an operation,
+ * use `set()` to build up context as information becomes available,
+ * then emit once at the end. Lifecycle methods (`info()`, `warn()`, `error()`,
+ * `debug()`) record timestamped entries in a `requestLogs` array and
+ * automatically escalate the event's severity level.
+ *
+ * Implements `Disposable` for use with TC39 Explicit Resource Management.
+ * @template TData - Shape of the accumulated event data
+ * @template T - Custom logger type names from the pail instance
+ * @example
+ * ```typescript
+ * // Manual finish
+ * const ev = createWideEvent({ pail: logger, name: "api.checkout" });
+ * ev.set({ user: { id: 1 } });
+ * ev.info("Validated cart");
+ * ev.set({ cart: { items: 3, total: 9999 } });
+ * ev.finish({ status: 200 });
+ *
+ * // Auto-emit with Explicit Resource Management
+ * using ev = createWideEvent({ pail: logger, name: "api.checkout" });
+ * ev.set({ user: { id: 1 } });
+ * // emits automatically when scope exits
+ *
+ * // Typed data shape
+ * interface CheckoutData {
+ *   user: { id: number; plan: string };
+ *   cart: { items: number; total: number };
+ * }
+ * const ev = createWideEvent<CheckoutData>({ pail: logger, name: "api.checkout" });
+ * ev.set({ user: { id: 1, plan: "pro" } }); // fully typed
+ * ```
+ */
+export declare class WideEvent<TData extends Record<string, unknown> = Record<string, unknown>, T extends string = string> implements Disposable {
+    [Symbol.dispose]: () => void;
+    readonly name: string;
+    private readonly autoEmit;
+    private data;
+    private emitted;
+    private attachedError?;
+    private level;
+    private readonly pail;
+    private readonly requestLogs;
+    private readonly service;
+    private readonly startTime;
+    private status;
+    private readonly timestamp;
+    private readonly type;
+    constructor(options: WideEventOptions<T>);
+    /**
+     * Record a debug-level lifecycle log entry.
+     * Does not escalate the event level.
+     * @param message Description of what happened
+     * @param context Optional structured context
+     * @returns `this` for chaining
+     */
+    debug(message: string, context?: Record<string, unknown>): this;
+    /**
+     * Emit the wide event through the pail logger. Can only be called once;
+     * subsequent calls are no-ops.
+     *
+     * Automatically calculates duration, determines the log type based on
+     * the highest severity level reached, and serializes any attached error.
+     *
+     * Prefer `finish()` for HTTP request contexts where you have a status code.
+     * @param typeOverride Override the log type for this emission
+     */
+    emit(typeOverride?: DefaultLogTypes | T): void;
+    /**
+     * Record an error-level lifecycle log entry and attach the error.
+     * Escalates the event level to "error".
+     * @param message Description of what went wrong
+     * @param error The error that occurred
+     * @param context Optional structured context
+     * @returns `this` for chaining
+     */
+    error(message: string, error?: Error, context?: Record<string, unknown>): this;
+    /**
+     * Finish and emit the wide event with HTTP context.
+     * Sets the response status and optional error before emitting.
+     * @example
+     * ```typescript
+     * ev.finish({ status: 200 });
+     * ev.finish({ status: 500, error: new Error("DB timeout") });
+     * ```
+     * @param options Status code and/or error
+     */
+    finish(options?: WideEventFinishOptions): void;
+    /**
+     * Get a read-only snapshot of the accumulated data.
+     */
+    getData(): Readonly<TData>;
+    /**
+     * Get the current severity level of the event.
+     * The level auto-escalates as `warn()` or `error()` entries are added.
+     */
+    getLevel(): WideEventLevel;
+    /**
+     * Get a read-only copy of the request lifecycle log entries.
+     */
+    getRequestLogs(): ReadonlyArray<RequestLogEntry>;
+    /**
+     * Record an info-level lifecycle log entry.
+     * Does not escalate the event level.
+     * @param message Description of what happened
+     * @param context Optional structured context
+     * @returns `this` for chaining
+     */
+    info(message: string, context?: Record<string, unknown>): this;
+    /**
+     * Accumulate context into the wide event via deep merge.
+     * Call as many times as needed throughout the operation.
+     * @example
+     * ```typescript
+     * ev.set({ user: { id: 1 } });
+     * ev.set({ user: { plan: "pro" } });
+     * // data = { user: { id: 1, plan: "pro" } }
+     * ```
+     * @param data Partial data to merge into the event
+     * @returns `this` for chaining
+     */
+    set(data: DeepPartial<TData>): this;
+    /**
+     * Attach an error to the event. Automatically escalates the event
+     * level to "error".
+     * @param error The error to attach
+     * @returns `this` for chaining
+     */
+    setError(error: Error): this;
+    /**
+     * Set the HTTP response status code.
+     * @param status HTTP status code
+     * @returns `this` for chaining
+     */
+    setStatus(status: number): this;
+    /**
+     * Record a warn-level lifecycle log entry.
+     * Escalates the event level to "warn" (unless already "error").
+     * @param message Description of the warning
+     * @param context Optional structured context
+     * @returns `this` for chaining
+     */
+    warn(message: string, context?: Record<string, unknown>): this;
+    /**
+     * Disposable implementation. Auto-emits the event if `autoEmit` is true
+     * and the event hasn't been manually emitted yet.
+     *
+     * Enables usage with TC39 Explicit Resource Management:
+     * ```typescript
+     * using ev = createWideEvent({ pail: logger, name: "api.checkout" });
+     * ev.set({ user: { id: 1 } });
+     * // auto-emits here when scope exits
+     * ```
+     */
+    [Symbol.dispose](): void;
+    /**
+     * Add an entry to the request lifecycle log and escalate level if needed.
+     */
+    private addLogEntry;
+    /**
+     * Escalate the event level if the new level has higher severity.
+     */
+    private escalateLevel;
+}
+/**
+ * Create a wide event logger that accumulates context and emits a single
+ * comprehensive log event through pail.
+ * @template TData - Shape of the accumulated event data
+ * @template T - Custom logger type names from the pail instance
+ * @param options Configuration options
+ * @returns A new WideEvent instance
+ * @example
+ * ```typescript
+ * import { createPail } from "@visulima/pail";
+ * import { createWideEvent } from "@visulima/pail/wide-event";
+ *
+ * const logger = createPail();
+ *
+ * // In a request handler:
+ * const ev = createWideEvent({ pail: logger, name: "api.checkout" });
+ *
+ * ev.set({ user: { id: 1, plan: "pro" } });
+ * ev.info("Validated cart", { itemCount: 3 });
+ * ev.set({ cart: { id: 42, items: 3, total: 9999 } });
+ * ev.info("Payment processed");
+ * ev.finish({ status: 200 });
+ *
+ * // Emits a single structured log:
+ * // {
+ * //   event: "api.checkout",
+ * //   timestamp: "2025-01-24T10:23:45.612Z",
+ * //   duration: "127ms",
+ * //   duration_ms: 127,
+ * //   status: 200,
+ * //   user: { id: 1, plan: "pro" },
+ * //   cart: { id: 42, items: 3, total: 9999 },
+ * //   requestLogs: [
+ * //     { level: "info", message: "Validated cart", timestamp: "...", context: { itemCount: 3 } },
+ * //     { level: "info", message: "Payment processed", timestamp: "..." }
+ * //   ]
+ * // }
+ * ```
+ */
+export declare const createWideEvent: <TData extends Record<string, unknown> = Record<string, unknown>, T extends string = string>(options: WideEventOptions<T>) => WideEvent<TData, T>;
+export {};

package/dist/wide-event.js

@@ -0,0 +1,283 @@
+const LEVEL_PRIORITY = {
+  debug: 0,
+  error: 3,
+  info: 1,
+  warn: 2
+};
+const LEVEL_TO_LOG_TYPE = {
+  debug: "debug",
+  error: "error",
+  info: "info",
+  warn: "warn"
+};
+const deepMerge = (target, source) => {
+  const result = { ...target };
+  const keys = Object.keys(source);
+  for (let i = 0; i < keys.length; i += 1) {
+    const key = keys[i];
+    const sourceValue = source[key];
+    const targetValue = result[key];
+    if (sourceValue !== null && typeof sourceValue === "object" && !Array.isArray(sourceValue) && targetValue !== null && typeof targetValue === "object" && !Array.isArray(targetValue)) {
+      result[key] = deepMerge(targetValue, sourceValue);
+    } else {
+      result[key] = sourceValue;
+    }
+  }
+  return result;
+};
+const formatDuration = (ms) => {
+  if (ms < 1e3) {
+    return `${String(ms)}ms`;
+  }
+  return `${(ms / 1e3).toFixed(2)}s`;
+};
+const serializeError = (error) => {
+  const serialized = {
+    message: error.message,
+    name: error.name
+  };
+  if (error.stack) {
+    serialized.stack = error.stack;
+  }
+  const errorWithStatus = error;
+  if (errorWithStatus.status !== void 0) {
+    serialized.status = errorWithStatus.status;
+  } else if (errorWithStatus.statusCode !== void 0) {
+    serialized.status = errorWithStatus.statusCode;
+  }
+  if (errorWithStatus.data !== void 0) {
+    serialized.data = errorWithStatus.data;
+  }
+  if (error.cause instanceof Error) {
+    serialized.cause = serializeError(error.cause);
+  }
+  return serialized;
+};
+class WideEvent {
+  name;
+  autoEmit;
+  data;
+  emitted;
+  attachedError;
+  level;
+  pail;
+  requestLogs;
+  service;
+  startTime;
+  status;
+  timestamp;
+  type;
+  constructor(options) {
+    this.name = options.name;
+    this.pail = options.pail;
+    this.data = {};
+    this.startTime = performance.now();
+    this.timestamp = (/* @__PURE__ */ new Date()).toISOString();
+    this.emitted = false;
+    this.autoEmit = options.autoEmit ?? true;
+    this.type = options.type ?? "info";
+    this.level = "info";
+    this.requestLogs = [];
+    this.service = options.service;
+  }
+  /**
+   * Record a debug-level lifecycle log entry.
+   * Does not escalate the event level.
+   * @param message Description of what happened
+   * @param context Optional structured context
+   * @returns `this` for chaining
+   */
+  debug(message, context) {
+    return this.addLogEntry("debug", message, context);
+  }
+  /**
+   * Emit the wide event through the pail logger. Can only be called once;
+   * subsequent calls are no-ops.
+   *
+   * Automatically calculates duration, determines the log type based on
+   * the highest severity level reached, and serializes any attached error.
+   *
+   * Prefer `finish()` for HTTP request contexts where you have a status code.
+   * @param typeOverride Override the log type for this emission
+   */
+  emit(typeOverride) {
+    if (this.emitted) {
+      return;
+    }
+    this.emitted = true;
+    const durationMs = Math.round(performance.now() - this.startTime);
+    const resolvedLevel = this.attachedError ? "error" : this.level;
+    const type = typeOverride ?? LEVEL_TO_LOG_TYPE[resolvedLevel];
+    const payload = {
+      duration: formatDuration(durationMs),
+      duration_ms: durationMs,
+      event: this.name,
+      timestamp: this.timestamp,
+      ...this.data
+    };
+    if (this.service) {
+      payload.service = this.service;
+    }
+    if (this.status !== void 0) {
+      payload.status = this.status;
+    }
+    if (this.attachedError) {
+      payload.error = serializeError(this.attachedError);
+    }
+    if (this.requestLogs.length > 0) {
+      payload.requestLogs = this.requestLogs;
+    }
+    const logFunction = this.pail[type];
+    logFunction({ message: payload });
+  }
+  /**
+   * Record an error-level lifecycle log entry and attach the error.
+   * Escalates the event level to "error".
+   * @param message Description of what went wrong
+   * @param error The error that occurred
+   * @param context Optional structured context
+   * @returns `this` for chaining
+   */
+  error(message, error, context) {
+    if (error) {
+      this.attachedError = error;
+    }
+    return this.addLogEntry("error", message, context);
+  }
+  /**
+   * Finish and emit the wide event with HTTP context.
+   * Sets the response status and optional error before emitting.
+   * @example
+   * ```typescript
+   * ev.finish({ status: 200 });
+   * ev.finish({ status: 500, error: new Error("DB timeout") });
+   * ```
+   * @param options Status code and/or error
+   */
+  finish(options) {
+    if (options?.status !== void 0) {
+      this.status = options.status;
+    }
+    if (options?.error) {
+      this.attachedError = options.error;
+    }
+    this.emit();
+  }
+  /**
+   * Get a read-only snapshot of the accumulated data.
+   */
+  getData() {
+    return this.data;
+  }
+  /**
+   * Get the current severity level of the event.
+   * The level auto-escalates as `warn()` or `error()` entries are added.
+   */
+  getLevel() {
+    return this.attachedError ? "error" : this.level;
+  }
+  /**
+   * Get a read-only copy of the request lifecycle log entries.
+   */
+  getRequestLogs() {
+    return this.requestLogs;
+  }
+  /**
+   * Record an info-level lifecycle log entry.
+   * Does not escalate the event level.
+   * @param message Description of what happened
+   * @param context Optional structured context
+   * @returns `this` for chaining
+   */
+  info(message, context) {
+    return this.addLogEntry("info", message, context);
+  }
+  /**
+   * Accumulate context into the wide event via deep merge.
+   * Call as many times as needed throughout the operation.
+   * @example
+   * ```typescript
+   * ev.set({ user: { id: 1 } });
+   * ev.set({ user: { plan: "pro" } });
+   * // data = { user: { id: 1, plan: "pro" } }
+   * ```
+   * @param data Partial data to merge into the event
+   * @returns `this` for chaining
+   */
+  set(data) {
+    this.data = deepMerge(this.data, data);
+    return this;
+  }
+  /**
+   * Attach an error to the event. Automatically escalates the event
+   * level to "error".
+   * @param error The error to attach
+   * @returns `this` for chaining
+   */
+  setError(error) {
+    this.attachedError = error;
+    return this;
+  }
+  /**
+   * Set the HTTP response status code.
+   * @param status HTTP status code
+   * @returns `this` for chaining
+   */
+  setStatus(status) {
+    this.status = status;
+    return this;
+  }
+  /**
+   * Record a warn-level lifecycle log entry.
+   * Escalates the event level to "warn" (unless already "error").
+   * @param message Description of the warning
+   * @param context Optional structured context
+   * @returns `this` for chaining
+   */
+  warn(message, context) {
+    return this.addLogEntry("warn", message, context);
+  }
+  /**
+   * Disposable implementation. Auto-emits the event if `autoEmit` is true
+   * and the event hasn't been manually emitted yet.
+   *
+   * Enables usage with TC39 Explicit Resource Management:
+   * ```typescript
+   * using ev = createWideEvent({ pail: logger, name: "api.checkout" });
+   * ev.set({ user: { id: 1 } });
+   * // auto-emits here when scope exits
+   * ```
+   */
+  [Symbol.dispose]() {
+    if (this.autoEmit && !this.emitted) {
+      this.emit();
+    }
+  }
+  /**
+   * Add an entry to the request lifecycle log and escalate level if needed.
+   */
+  addLogEntry(level, message, context) {
+    const entry = {
+      level,
+      message,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    if (context) {
+      entry.context = context;
+    }
+    this.requestLogs.push(entry);
+    this.escalateLevel(level);
+    return this;
+  }
+  /**
+   * Escalate the event level if the new level has higher severity.
+   */
+  escalateLevel(level) {
+    if ((LEVEL_PRIORITY[level] ?? 0) > (LEVEL_PRIORITY[this.level] ?? 0)) {
+      this.level = level;
+    }
+  }
+}
+const createWideEvent = (options) => new WideEvent(options);
+
+export { WideEvent, createWideEvent };