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

package/dist/wide-event.js

@@ -0,0 +1,284 @@
+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;
+  // @ts-expect-error TS6133 -- preserved for future use (richer event categorization)
+  _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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@visulima/pail",
-  "version": "4.0.0-alpha.1",
+  "version": "4.0.0-alpha.11",
   "description": "Highly configurable Logger for Node.js, Edge and Browser.",
   "keywords": [
     "ansi",
@@ -55,7 +55,7 @@
     "warning-logging",
     "winston"
   ],
-  "homepage": "https://www.visulima.com/docs/package/pail",
+  "homepage": "https://visulima.com/packages/pail/",
   "bugs": {
     "url": "https://github.com/visulima/visulima/issues"
   },
@@ -114,6 +114,18 @@
       "types": "./dist/processor/opentelemetry-processor.d.ts",
       "default": "./dist/processor/opentelemetry-processor.js"
     },
+    "./processor/sampling": {
+      "types": "./dist/processor/sampling-processor.d.ts",
+      "default": "./dist/processor/sampling-processor.js"
+    },
+    "./processor/environment": {
+      "types": "./dist/processor/environment-processor.d.ts",
+      "default": "./dist/processor/environment-processor.js"
+    },
+    "./error": {
+      "types": "./dist/error.d.ts",
+      "default": "./dist/error.js"
+    },
     "./reporter/file": {
       "types": "./dist/reporter/file/json-file-reporter.d.ts",
       "default": "./dist/reporter/file/json-file-reporter.js"
@@ -178,22 +190,38 @@
         "default": "./dist/reporter/http/http-reporter.js"
       }
     },
-    "./progress-bar": {
-      "types": "./dist/progress-bar.d.ts",
-      "default": "./dist/progress-bar.js"
-    },
-    "./spinner": {
-      "types": "./dist/spinner.d.ts",
-      "default": "./dist/spinner.js"
-    },
-    "./interactive": {
-      "types": "./dist/interactive/index.d.ts",
-      "default": "./dist/interactive/index.js"
-    },
     "./object-tree": {
       "types": "./dist/object-tree.d.ts",
       "default": "./dist/object-tree.js"
     },
+    "./wide-event": {
+      "types": "./dist/wide-event.d.ts",
+      "default": "./dist/wide-event.js"
+    },
+    "./middleware/express": {
+      "types": "./dist/middleware/express.d.ts",
+      "default": "./dist/middleware/express.js"
+    },
+    "./middleware/fastify": {
+      "types": "./dist/middleware/fastify.d.ts",
+      "default": "./dist/middleware/fastify.js"
+    },
+    "./middleware/hono": {
+      "types": "./dist/middleware/hono.d.ts",
+      "default": "./dist/middleware/hono.js"
+    },
+    "./middleware/elysia": {
+      "types": "./dist/middleware/elysia.d.ts",
+      "default": "./dist/middleware/elysia.js"
+    },
+    "./middleware/sveltekit": {
+      "types": "./dist/middleware/sveltekit.d.ts",
+      "default": "./dist/middleware/sveltekit.js"
+    },
+    "./middleware/next": {
+      "types": "./dist/middleware/next/handler.d.ts",
+      "default": "./dist/middleware/next/handler.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -203,27 +231,52 @@
     "LICENSE.md"
   ],
   "dependencies": {
-    "type-fest": "^5.3.0",
-    "@visulima/colorize": "2.0.0-alpha.2"
+    "@visulima/colorize": "2.0.0-alpha.10",
+    "@visulima/interactive-manager": "1.0.0-alpha.2",
+    "type-fest": "5.6.0"
   },
   "peerDependencies": {
-    "@opentelemetry/api": "^1.9",
-    "@visulima/redact": "3.0.0-alpha.2",
-    "rotating-file-stream": "^3.2.7"
+    "@opentelemetry/api": "1.9.1",
+    "@sveltejs/kit": ">=2.0",
+    "@visulima/redact": "3.0.0-alpha.10",
+    "elysia": ">=1.0",
+    "express": ">=4.0",
+    "fastify": ">=4.0",
+    "hono": ">=4.0",
+    "next": ">=14.0",
+    "rotating-file-stream": "3.2.9"
   },
   "peerDependenciesMeta": {
     "@opentelemetry/api": {
       "optional": true
     },
+    "@sveltejs/kit": {
+      "optional": true
+    },
     "@visulima/redact": {
       "optional": true
     },
+    "elysia": {
+      "optional": true
+    },
+    "express": {
+      "optional": true
+    },
+    "fastify": {
+      "optional": true
+    },
+    "hono": {
+      "optional": true
+    },
+    "next": {
+      "optional": true
+    },
     "rotating-file-stream": {
       "optional": true
     }
   },
   "engines": {
-    "node": ">=22.13 <=25.x"
+    "node": "^22.14.0 || >=24.10.0"
   },
   "os": [
     "darwin",

package/dist/interactive/index.d.ts

@@ -1,2 +0,0 @@
-export { default as InteractiveManager } from "./interactive-manager.d.ts";
-export { default as InteractiveStreamHook } from "./interactive-stream-hook.d.ts";

package/dist/interactive/index.js

@@ -1,2 +0,0 @@
-export { default as InteractiveManager } from '../packem_shared/InteractiveManager-CZ85hGNW.js';
-export { I as InteractiveStreamHook } from '../packem_shared/interactive-stream-hook-DG4BtN12.js';

package/dist/interactive/interactive-manager.d.ts

@@ -1,108 +0,0 @@
-import type InteractiveStreamHook from "./interactive-stream-hook.d.ts";
-/** Supported stream types for interactive output */
-type StreamType = "stderr" | "stdout";
-/**
- * Interactive Manager.
- *
- * Manages interactive terminal output by coordinating stdout and stderr streams.
- * Enables features like progress bars, spinners, and dynamic updates by temporarily
- * capturing and controlling terminal output. Supports suspending and resuming
- * interactive mode for external output.
- * @example
- * ```typescript
- * const manager = new InteractiveManager(stdoutHook, stderrHook);
- *
- * // Start interactive mode
- * manager.hook();
- *
- * // Update output dynamically
- * manager.update("stdout", ["Processing...", "50% complete"]);
- *
- * // Temporarily suspend for external output
- * manager.suspend("stdout");
- * console.log("External message");
- * manager.resume("stdout");
- *
- * // End interactive mode and show final output
- * manager.unhook();
- * ```
- */
-declare class InteractiveManager {
-    #private;
-    /**
-     * Creates a new InteractiveManager with the given stream hooks.
-     * @param stdout Hook for stdout stream
-     * @param stderr Hook for stderr stream
-     */
-    constructor(stdout: InteractiveStreamHook, stderr: InteractiveStreamHook);
-    /**
-     * Last printed rows count.
-     *
-     * Tracks the number of rows that were last written to the terminal.
-     * Used internally for managing cursor positioning and output updates.
-     */
-    get lastLength(): number;
-    /**
-     * Rows count outside editable area.
-     *
-     * Tracks the number of rows that extend beyond the current terminal height.
-     * Used for managing scrolling and ensuring all output remains visible.
-     */
-    get outside(): number;
-    /**
-     * Hook activity status.
-     *
-     * Indicates whether the interactive hooks are currently active.
-     * When true, streams are being intercepted for interactive output.
-     */
-    get isHooked(): boolean;
-    /**
-     * Suspend status for active hooks.
-     *
-     * Indicates whether interactive mode is temporarily suspended.
-     * When suspended, external output can be written without interference.
-     */
-    get isSuspended(): boolean;
-    /**
-     * Removes lines from the terminal output.
-     *
-     * Erases the specified number of lines from the bottom of the output,
-     * moving the cursor up and clearing the lines. Useful for removing
-     * previous interactive output before displaying new content.
-     * @param stream The stream to erase lines from ("stdout" or "stderr")
-     * @param count Number of lines to remove (defaults to lastLength)
-     * @throws {TypeError} If the specified stream is not available
-     */
-    erase(stream: StreamType, count?: number): void;
-    /**
-     * Hook stdout and stderr streams.
-     * @returns Success status
-     */
-    hook(): boolean;
-    /**
-     * Resume suspend hooks.
-     * @param stream Stream to resume
-     * @param eraseRowCount erase output rows count
-     */
-    resume(stream: StreamType, eraseRowCount?: number): void;
-    /**
-     * Suspend active hooks for external output.
-     * @param stream Stream to suspend
-     * @param erase erase output
-     */
-    suspend(stream: StreamType, erase?: boolean): void;
-    /**
-     * Unhooks both stdout and stderr streams and print their story of logs.
-     * @param separateHistory If `true`, will add an empty line to the history output for individual recorded lines and console logs
-     * @returns Success status
-     */
-    unhook(separateHistory?: boolean): boolean;
-    /**
-     * Update output.
-     * @param stream Stream to write to
-     * @param rows Text lines to write to standard output
-     * @param from Index of the line starting from which the contents of the terminal are being overwritten
-     */
-    update(stream: StreamType, rows: string[], from?: number): void;
-}
-export default InteractiveManager;

package/dist/interactive/interactive-stream-hook.d.ts

@@ -1,68 +0,0 @@
-/**
- * Interactive Stream Hook.
- *
- * A utility class that hooks into Node.js WriteStreams to capture output
- * for interactive terminal applications. It allows temporarily intercepting
- * stream writes to enable features like progress bars and dynamic updates.
- * @example
- * ```typescript
- * const hook = new InteractiveStreamHook(process.stdout);
- * hook.active(); // Start capturing output
- *
- * // Output will be stored in history instead of being written to stdout
- * console.log("This won't appear immediately");
- *
- * hook.inactive(); // Stop capturing and replay stored output
- * ```
- */
-declare class InteractiveStreamHook {
-    #private;
-    /** Constant indicating the stream write operation was successful */
-    static readonly DRAIN = true;
-    /**
-     * Creates a new InteractiveStreamHook for the given stream.
-     * @param stream The Node.js WriteStream to hook into (usually stdout or stderr)
-     */
-    constructor(stream: NodeJS.WriteStream);
-    /**
-     * Activates the stream hook.
-     *
-     * When active, all writes to the stream are captured in history instead of
-     * being written immediately. This allows for interactive features like
-     * progress bars that can update dynamically.
-     */
-    active(): void;
-    /**
-     * Erases the specified number of lines from the terminal.
-     *
-     * Uses ANSI escape sequences to remove lines from the current cursor position
-     * upwards, which is useful for clearing previous output in interactive applications.
-     * @param count Number of lines to erase (including the current line)
-     */
-    erase(count: number): void;
-    /**
-     * Deactivates the stream hook and replays captured output.
-     *
-     * Restores normal stream operation and outputs all captured history.
-     * Optionally adds a newline separator before replaying the history.
-     * @param separateHistory Whether to add a newline before replaying history
-     */
-    inactive(separateHistory?: boolean): void;
-    /**
-     * Renews the stream hook state.
-     *
-     * Restores the original stream write method and shows the cursor.
-     * This is typically called when temporarily suspending interactive mode.
-     */
-    renew(): void;
-    /**
-     * Writes a message directly to the underlying stream.
-     *
-     * Bypasses the hook mechanism and writes directly using the original
-     * stream write method. Useful for writing control sequences or
-     * messages that should not be captured in history.
-     * @param message The message to write to the stream
-     */
-    write(message: string): void;
-}
-export default InteractiveStreamHook;