@visulima/pail 4.0.0-alpha.6 → 4.0.0-alpha.7

package/dist/reporter/file/json-file-reporter.js

@@ -1,4 +1,4 @@
-import { AbstractJsonReporter } from '../../packem_shared/AbstractJsonReporter-DWRpTtGw.js';
+import { AbstractJsonReporter } from '../../packem_shared/AbstractJsonReporter-CGKHS8_M.js';
 
 class SafeStreamHandler {
   #ready = true;

package/dist/reporter/http/abstract-http-reporter.js

@@ -20,7 +20,7 @@ const __cjs_getBuiltinModule = (module) => {
 const {
   Buffer
 } = __cjs_getBuiltinModule("node:buffer");
-import { AbstractJsonReporter } from '../../packem_shared/AbstractJsonReporter-DWRpTtGw.js';
+import { AbstractJsonReporter } from '../../packem_shared/AbstractJsonReporter-CGKHS8_M.js';
 const {
   gzipSync
 } = __cjs_getBuiltinModule("node:zlib");

package/dist/reporter/http/http-reporter.edge-light.js

@@ -36,7 +36,7 @@ const ErrorProto = Object.create(
   {},
   {
     cause: {
-      enumerable: true,
+      enumerable: false,
       value: void 0,
       writable: true
     },
@@ -46,32 +46,55 @@ const ErrorProto = Object.create(
       writable: true
     },
     errors: {
-      enumerable: true,
+      enumerable: false,
       value: void 0,
       writable: true
     },
     message: {
-      enumerable: true,
+      enumerable: false,
       value: void 0,
       writable: true
     },
     name: {
-      enumerable: true,
+      enumerable: false,
       value: void 0,
       writable: true
     },
     stack: {
-      enumerable: true,
+      enumerable: false,
       value: void 0,
       writable: true
     }
   }
 );
 const toJsonWasCalled = /* @__PURE__ */ new WeakSet();
+const makePropertiesEnumerable = (object) => {
+  if (!object || typeof object !== "object") {
+    return;
+  }
+  const props = Object.getOwnPropertyNames(object);
+  for (const prop of props) {
+    const descriptor = Object.getOwnPropertyDescriptor(object, prop);
+    if (descriptor) {
+      if (!descriptor.enumerable) {
+        Object.defineProperty(object, prop, {
+          ...descriptor,
+          enumerable: true
+        });
+      }
+      if (descriptor.value && typeof descriptor.value === "object" && !Array.isArray(descriptor.value) && (Object.getPrototypeOf(descriptor.value) === Object.prototype || Object.getPrototypeOf(descriptor.value) === null)) {
+        makePropertiesEnumerable(descriptor.value);
+      }
+    }
+  }
+};
 const toJSON = (from) => {
   toJsonWasCalled.add(from);
   const json = from.toJSON();
   toJsonWasCalled.delete(from);
+  if (json && typeof json === "object" && Object.isExtensible(json)) {
+    makePropertiesEnumerable(json);
+  }
   return json;
 };
 const serializeValue = (value, seen, depth, options) => {
@@ -82,7 +105,7 @@ const serializeValue = (value, seen, depth, options) => {
     return "[object Stream]";
   }
   if (value instanceof Error) {
-    if (seen.includes(value)) {
+    if (seen.has(value)) {
       return "[Circular]";
     }
     depth += 1;
@@ -97,11 +120,14 @@ const serializeValue = (value, seen, depth, options) => {
   if (typeof value === "function") {
     return `[Function: ${value.name || "anonymous"}]`;
   }
+  if (typeof value === "bigint") {
+    return `${value}n`;
+  }
   if (isPlainObject(value)) {
-    depth += 1;
-    if (options.maxDepth && depth >= options.maxDepth) {
+    if (options.maxDepth !== void 0 && options.maxDepth !== Number.POSITIVE_INFINITY && depth + 1 >= options.maxDepth) {
       return {};
     }
+    depth += 1;
     const plainObject = {};
     for (const key in value) {
       plainObject[key] = serializeValue(value[key], seen, depth, options);
@@ -115,7 +141,7 @@ const serializeValue = (value, seen, depth, options) => {
   }
 };
 const _serialize = (error, options, seen, depth) => {
-  seen.push(error);
+  seen.add(error);
   if (options.maxDepth === 0) {
     return {};
   }
@@ -123,31 +149,87 @@ const _serialize = (error, options, seen, depth) => {
     return toJSON(error);
   }
   const protoError = Object.create(ErrorProto);
-  protoError.name = Object.prototype.toString.call(error.constructor) === "[object Function]" ? error.constructor.name : error.name;
-  protoError.message = error.message;
-  protoError.stack = error.stack;
+  Object.defineProperty(protoError, "name", {
+    configurable: true,
+    enumerable: true,
+    value: Object.prototype.toString.call(error.constructor) === "[object Function]" ? error.constructor.name : error.name,
+    writable: true
+  });
+  Object.defineProperty(protoError, "message", {
+    configurable: true,
+    enumerable: true,
+    value: error.message,
+    writable: true
+  });
+  Object.defineProperty(protoError, "stack", {
+    configurable: true,
+    enumerable: true,
+    value: error.stack,
+    writable: true
+  });
   if (Array.isArray(error.errors)) {
     const aggregateErrors = [];
     for (const aggregateError of error.errors) {
       if (!(aggregateError instanceof Error)) {
         throw new TypeError("All errors in the 'errors' property must be instances of Error");
       }
-      if (seen.includes(aggregateError)) {
-        protoError.errors = [];
+      if (seen.has(aggregateError)) {
+        Object.defineProperty(protoError, "errors", {
+          configurable: true,
+          enumerable: true,
+          value: [],
+          writable: true
+        });
         return protoError;
       }
       aggregateErrors.push(_serialize(aggregateError, options, seen, depth));
     }
-    protoError.errors = aggregateErrors;
+    Object.defineProperty(protoError, "errors", {
+      configurable: true,
+      enumerable: true,
+      value: aggregateErrors,
+      writable: true
+    });
   }
-  if (error.cause instanceof Error && !seen.includes(error.cause)) {
-    protoError.cause = _serialize(error.cause, options, seen, depth);
+  if (error.cause !== void 0 && error.cause !== null) {
+    if (error.cause instanceof Error) {
+      if (seen.has(error.cause)) {
+        Object.defineProperty(protoError, "cause", {
+          configurable: true,
+          enumerable: true,
+          value: "[Circular]",
+          writable: true
+        });
+      } else {
+        Object.defineProperty(protoError, "cause", {
+          configurable: true,
+          enumerable: true,
+          value: _serialize(error.cause, options, seen, depth),
+          writable: true
+        });
+      }
+    } else {
+      const serializedCause = serializeValue(error.cause, seen, depth, options);
+      Object.defineProperty(protoError, "cause", {
+        configurable: true,
+        enumerable: true,
+        value: serializedCause,
+        writable: true
+      });
+    }
   }
   for (const key in error) {
-    if (protoError[key] === void 0) {
-      const value = error[key];
-      protoError[key] = serializeValue(value, seen, depth, options);
+    if (key === "name" || key === "message" || key === "stack" || key === "cause" || key === "errors") {
+      continue;
     }
+    const value = error[key];
+    const serializedValue = serializeValue(value, seen, depth, options);
+    Object.defineProperty(protoError, key, {
+      configurable: true,
+      enumerable: true,
+      value: serializedValue,
+      writable: true
+    });
   }
   if (Array.isArray(options.exclude) && options.exclude.length > 0) {
     for (const key of options.exclude) {
@@ -166,7 +248,7 @@ const serialize = (error, options = {}) => _serialize(
     maxDepth: options.maxDepth ?? Number.POSITIVE_INFINITY,
     useToJSON: options.useToJSON ?? false
   },
-  [],
+  /* @__PURE__ */ new Set(),
   0
 );
 

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-DDjDkciI.js';
+export { default as JsonReporter } from '../../packem_shared/JsonReporter-p_BXg6Sj.js';

package/dist/reporter/json/index.js

@@ -1,2 +1,2 @@
-export { AbstractJsonReporter } from '../../packem_shared/AbstractJsonReporter-DWRpTtGw.js';
-export { default as JsonReporter } from '../../packem_shared/JsonReporter-BV5lMnJX.js';
+export { AbstractJsonReporter } from '../../packem_shared/AbstractJsonReporter-CGKHS8_M.js';
+export { default as JsonReporter } from '../../packem_shared/JsonReporter-B3XX8GHN.js';

package/dist/reporter/pretty/index.js

@@ -1 +1 @@
-export { PrettyReporter } from '../../packem_shared/PrettyReporter-BjXCFQlo.js';
+export { PrettyReporter } from '../../packem_shared/PrettyReporter-CvBn-hxP.js';

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

@@ -11,7 +11,8 @@ const {
 import colorize, { red, greenBright, cyan, green, grey, bold, bgGrey, underline, white } from '@visulima/colorize';
 import { A as AbstractPrettyReporter, d as defaultInspectorConfig, b as writeStream, t as terminalSize, c as getLongestBadge, g as getLongestLabel, e as getStringWidth, f as formatLabel, a as EMPTY_SYMBOL, i as inspect, w as wordWrap, r as renderError, W as WrapMode } from '../../packem_shared/abstract-pretty-reporter-jU8WL_6c.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;

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