@visulima/pail 4.0.0-alpha.1 → 4.0.0-alpha.11

package/dist/reporter/json/abstract-json-reporter.d.ts

@@ -45,7 +45,7 @@ export declare abstract class AbstractJsonReporter<L extends string = string> im
      * Sets a custom stringify function for object serialization.
      * @param function_ The stringify function to use for serialization
      */
-    setStringify(function_: any): void;
+    setStringify(function_: typeof stringify): void;
     log(meta: ReadonlyMeta<L>): void;
     /**
      * Template method for outputting the JSON log message.

package/dist/reporter/json/index.browser.js

@@ -1,2 +1,2 @@
-export { AbstractJsonReporter } from '../../packem_shared/AbstractJsonReporter-BaZ33PlE.js';
-export { default as JsonReporter } from '../../packem_shared/JsonReporter-BRw4skd5.js';
+export { AbstractJsonReporter } from '../../packem_shared/AbstractJsonReporter-BO8Calb4.js';
+export { default as JsonReporter } from '../../packem_shared/JsonReporter-CCmj7oYL.js';

package/dist/reporter/json/index.js

@@ -1,2 +1,2 @@
-export { AbstractJsonReporter } from '../../packem_shared/AbstractJsonReporter-BaZ33PlE.js';
-export { default as JsonReporter } from '../../packem_shared/JsonReporter-VzgyLEYz.js';
+export { AbstractJsonReporter } from '../../packem_shared/AbstractJsonReporter-nOj0Ft1F.js';
+export { default as JsonReporter } from '../../packem_shared/JsonReporter-Ck2PIAEw.js';

package/dist/reporter/pretty/index.browser.js

@@ -1 +1 @@
-export { default as PrettyReporter } from '../../packem_shared/PrettyReporter-DySIXBjQ.js';
+export { default as PrettyReporter } from '../../packem_shared/PrettyReporter-BtTr13Ha.js';

package/dist/reporter/pretty/index.js

@@ -1 +1 @@
-export { PrettyReporter } from '../../packem_shared/PrettyReporter-DgZB2eBG.js';
+export { PrettyReporter } from '../../packem_shared/PrettyReporter-BCvyNzXO.js';

package/dist/reporter/pretty/pretty-reporter.server.d.ts

@@ -1,7 +1,7 @@
 import type { RenderErrorOptions } from "@visulima/error/error";
 import type { Options as InspectorOptions } from "@visulima/inspector";
+import type { InteractiveManager } from "@visulima/interactive-manager";
 import type { LiteralUnion } from "type-fest";
-import type InteractiveManager from "../../interactive/interactive-manager.d.ts";
 import type { ExtendedRfc5424LogLevels, InteractiveStreamReporter, ReadonlyMeta } from "../../types.d.ts";
 import type { PrettyStyleOptions } from "./abstract-pretty-reporter.d.ts";
 import { AbstractPrettyReporter } from "./abstract-pretty-reporter.d.ts";

package/dist/reporter/raw/raw-reporter.server.d.ts

@@ -1,5 +1,5 @@
 import type { Options as InspectorOptions } from "@visulima/inspector";
-import type InteractiveManager from "../../interactive/interactive-manager.d.ts";
+import type { InteractiveManager } from "@visulima/interactive-manager";
 import type { ReadonlyMeta, StreamAwareReporter } from "../../types.d.ts";
 declare class RawReporter<L extends string = string> implements StreamAwareReporter<L> {
     #private;

package/dist/reporter/simple/simple-reporter.server.d.ts

@@ -1,6 +1,6 @@
 import type { RenderErrorOptions } from "@visulima/error";
 import type { Options as InspectorOptions } from "@visulima/inspector";
-import type InteractiveManager from "../../interactive/interactive-manager.d.ts";
+import type { InteractiveManager } from "@visulima/interactive-manager";
 import type { InteractiveStreamReporter, ReadonlyMeta } from "../../types.d.ts";
 import type { PrettyStyleOptions } from "../pretty/abstract-pretty-reporter.d.ts";
 import { AbstractPrettyReporter } from "../pretty/abstract-pretty-reporter.d.ts";

package/dist/reporter/simple/simple-reporter.server.js

@@ -8,15 +8,11 @@ const {
   stdout,
   stderr
 } = __cjs_getProcess;
-import colorize, { red, greenBright, cyan, green, grey, bold, white, bgGrey, underline } from '@visulima/colorize';
-import { d as defaultInspectorConfig, f as formatLabel, i as inspect, r as renderError } from '../../packem_shared/format-label-De49vNPd.js';
-import { t as terminalSize, g as getStringWidth, w as wordWrap, W as WrapMode } from '../../packem_shared/index-DqKWykfa.js';
-import { E as EMPTY_SYMBOL } from '../../packem_shared/constants-omsTHUWB.js';
-import { A as AbstractPrettyReporter, g as getLongestBadge } from '../../packem_shared/abstract-pretty-reporter-Di_sdm2r.js';
-import { g as getLongestLabel } from '../../packem_shared/get-longest-label-C9PWeyKq.js';
-import { w as writeStream } from '../../packem_shared/write-stream-BG8fhcs3.js';
+import colorize, { red, greenBright, cyan, green, grey, bold, bgGrey, underline, white } from '@visulima/colorize';
+import { A as AbstractPrettyReporter, d as defaultInspectorConfig, w as writeStream, t as terminalSize, b as getLongestBadge, g as getLongestLabel, c as getStringWidth, f as formatLabel, a as EMPTY_SYMBOL, i as inspect, e as wordWrap, r as renderError, W as WrapMode } from '../../packem_shared/abstract-pretty-reporter-CXAKYCb8.js';
 
-const pailFileFilter = (line) => !/[\\/]pail[\\/]dist/.test(line);
+const PAIL_DIST_REGEX = /[\\/]pail[\\/]dist/;
+const pailFileFilter = (line) => !PAIL_DIST_REGEX.test(line);
 class SimpleReporter extends AbstractPrettyReporter {
   #stdout;
   #stderr;
@@ -85,7 +81,7 @@ class SimpleReporter extends AbstractPrettyReporter {
     const groupSpaces = groups.map(() => "    ").join("");
     const items = [];
     if (groups.length > 0) {
-      items.push(`${groupSpaces + grey(`[${groups.at(-1)}]`)} `);
+      items.push(`${groupSpaces + grey(`[${groups.at(-1) ?? ""}]`)} `);
     }
     if (date) {
       items.push(`${grey(this.styles.dateFormatter(typeof date === "string" ? new Date(date) : date))} `);
@@ -108,7 +104,7 @@ class SimpleReporter extends AbstractPrettyReporter {
       items.push(" ".repeat(longestWidth + 1));
     }
     if (repeated) {
-      items.push(`${bgGrey.white(`[${repeated}x]`)} `);
+      items.push(`${bgGrey.white(`[${String(repeated)}x]`)} `);
     }
     if (Array.isArray(scope) && scope.length > 0) {
       items.push(`${grey(`[${scope.join(" > ")}]`)} `);
@@ -144,7 +140,7 @@ ${renderError(value, {
           if (typeof value === "object") {
             return ` ${inspect(value, this.#inspectOptions)}`;
           }
-          const newValue = (hasError ? "\n\n" : " ") + value;
+          const newValue = (hasError ? "\n\n" : " ") + String(value);
           hasError = false;
           return newValue;
         })
@@ -178,7 +174,7 @@ ${renderError(traceError, {
       items.push(` ${groupSpaces}${grey(this.styles.underline.suffix ? underline(suffix) : suffix)}`);
     }
     if (file) {
-      const fileMessage = file.name + (file.line ? `:${file.line}` : "");
+      const fileMessage = (file.name ?? "") + (file.line ? `:${String(file.line)}` : "");
       const callerPad = Math.max(0, titleSize - getStringWidth("Caller: "));
       items.push("\n", grey("Caller: "), " ".repeat(callerPad), fileMessage, "\n");
     }

package/dist/types.d.ts

@@ -1,7 +1,7 @@
 import type { AnsiColors } from "@visulima/colorize";
+import type { InteractiveManager } from "@visulima/interactive-manager";
 import type { stringify } from "safe-stable-stringify";
 import type { LiteralUnion, Primitive } from "type-fest";
-import type InteractiveManager from "./interactive/interactive-manager.d.ts";
 /**
  * Global namespace for extending Pail's metadata interface.
  *
@@ -43,7 +43,7 @@ export interface Meta<L> extends VisulimaPail.CustomMeta<L> {
     label: string | undefined;
     message: Primitive | ReadonlyArray<unknown> | Record<PropertyKey, unknown>;
     prefix: string | undefined;
-    repeated?: number | undefined;
+    repeated?: number;
     scope: string[] | undefined;
     suffix: string | undefined;
     traceError: Error | undefined;
@@ -88,7 +88,7 @@ export interface LoggerFunction {
  */
 export interface LoggerConfiguration<L extends string> {
     badge?: string;
-    color?: AnsiColors | undefined;
+    color?: AnsiColors;
     label: string;
     logLevel: LiteralUnion<ExtendedRfc5424LogLevels, L>;
 }
@@ -217,7 +217,7 @@ export interface ServerConstructorOptions<T extends string, L extends string> ex
     stdout: NodeJS.WriteStream;
 }
 export type Message = {
-    context?: any[] | undefined;
+    context?: any[];
     message: any;
     prefix?: string;
     suffix?: string;

package/dist/utils/write-console-log-based-on-level.d.ts

@@ -1,4 +1,4 @@
 import type { LiteralUnion } from "type-fest";
 import type { ExtendedRfc5424LogLevels } from "../types.d.ts";
-declare const writeConsoleLogBasedOnLevel: <L extends string = string>(level: LiteralUnion<ExtendedRfc5424LogLevels, L>) => (...data: any[]) => void;
+declare const writeConsoleLogBasedOnLevel: <L extends string = string>(level: LiteralUnion<ExtendedRfc5424LogLevels, L>) => ((...data: any[]) => void);
 export default writeConsoleLogBasedOnLevel;

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 {};