@visulima/pail 4.0.0-alpha.9 → 4.0.0

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@visulima/pail",
-  "version": "4.0.0-alpha.9",
+  "version": "4.0.0",
   "description": "Highly configurable Logger for Node.js, Edge and Browser.",
   "keywords": [
-    "ansi",
     "anolilab",
+    "ansi",
     "browser",
     "browser-logger",
     "callsite",
@@ -27,8 +27,8 @@
     "json",
     "json-logger",
     "json-logging",
-    "log level",
     "log",
+    "log level",
     "log-cleaner",
     "log-rotation",
     "log4j",
@@ -37,11 +37,10 @@
     "logger",
     "logging",
     "node",
-    "stream",
-    "pretty",
     "node-logger",
     "pail",
     "pino",
+    "pretty",
     "pretty-error",
     "pretty-log",
     "print",
@@ -49,6 +48,7 @@
     "redact",
     "rotating-log",
     "show error",
+    "stream",
     "timer",
     "universal",
     "visulima",
@@ -56,9 +56,7 @@
     "winston"
   ],
   "homepage": "https://visulima.com/packages/pail/",
-  "bugs": {
-    "url": "https://github.com/visulima/visulima/issues"
-  },
+  "bugs": "https://github.com/visulima/visulima/issues",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/visulima/visulima.git",
@@ -84,11 +82,11 @@
   "type": "module",
   "exports": {
     ".": {
-      "browser": "./dist/index.browser.js",
       "import": {
         "types": "./dist/index.server.d.ts",
         "default": "./dist/index.server.js"
-      }
+      },
+      "browser": "./dist/index.browser.js"
     },
     "./browser": {
       "types": "./dist/index.browser.d.ts",
@@ -143,11 +141,11 @@
       }
     },
     "./reporter/json": {
-      "browser": "./dist/reporter/json/index.browser.js",
       "import": {
         "types": "./dist/reporter/json/index.d.ts",
         "default": "./dist/reporter/json/index.js"
-      }
+      },
+      "browser": "./dist/reporter/json/index.browser.js"
     },
     "./server/reporter/pretty": {
       "import": {
@@ -162,11 +160,11 @@
       }
     },
     "./reporter/pretty": {
-      "browser": "./dist/reporter/pretty/index.browser.js",
       "import": {
         "types": "./dist/reporter/pretty/index.d.ts",
         "default": "./dist/reporter/pretty/index.js"
-      }
+      },
+      "browser": "./dist/reporter/pretty/index.browser.js"
     },
     "./reporter/simple": {
       "types": "./dist/reporter/simple/simple-reporter.server.d.ts",
@@ -177,6 +175,10 @@
       "default": "./dist/reporter/http/abstract-http-reporter.js"
     },
     "./reporter/http": {
+      "import": {
+        "types": "./dist/reporter/http/http-reporter.d.ts",
+        "default": "./dist/reporter/http/http-reporter.js"
+      },
       "edge-light": {
         "types": "./dist/reporter/http/http-reporter.edge-light.d.ts",
         "default": "./dist/reporter/http/http-reporter.edge-light.js"
@@ -184,24 +186,8 @@
       "browser": {
         "types": "./dist/reporter/http/http-reporter.d.ts",
         "default": "./dist/reporter/http/http-reporter.js"
-      },
-      "import": {
-        "types": "./dist/reporter/http/http-reporter.d.ts",
-        "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"
@@ -243,19 +229,19 @@
     "LICENSE.md"
   ],
   "dependencies": {
-    "@visulima/colorize": "2.0.0-alpha.7",
-    "type-fest": "5.5.0"
+    "@visulima/colorize": "2.0.0",
+    "@visulima/interactive-manager": "1.0.0"
   },
   "peerDependencies": {
-    "@opentelemetry/api": "^1.9",
+    "@opentelemetry/api": "^1.9.1",
     "@sveltejs/kit": ">=2.0",
-    "@visulima/redact": "3.0.0-alpha.7",
+    "@visulima/redact": "3.0.0",
     "elysia": ">=1.0",
     "express": ">=4.0",
     "fastify": ">=4.0",
     "hono": ">=4.0",
     "next": ">=14.0",
-    "rotating-file-stream": "3.2.9"
+    "rotating-file-stream": ">=3.2.9"
   },
   "peerDependenciesMeta": {
     "@opentelemetry/api": {
@@ -286,9 +272,8 @@
       "optional": true
     }
   },
-  "optionalDependencies": {},
   "engines": {
-    "node": ">=22.13 <=25.x"
+    "node": "^22.14.0 || >=24.10.0"
   },
   "os": [
     "darwin",

package/dist/constants.d.ts

@@ -1,37 +0,0 @@
-import type { DefaultLoggerTypes } from "./types.d.ts";
-/**
- * Extended RFC 5424 Log Levels
- *
- * The log levels pail uses are those defined in the syslog protocol.
- * Each level is assigned a numeric priority where lower numbers indicate higher priority.
- * @see https://datatracker.ietf.org/doc/html/rfc5424#page-36
- * @example
- * ```typescript
- * import { EXTENDED_RFC_5424_LOG_LEVELS } from "@visulima/pail";
- *
- * console.log(EXTENDED_RFC_5424_LOG_LEVELS.error); // 5
- * ```
- */
-export declare const EXTENDED_RFC_5424_LOG_LEVELS: Record<string, number>;
-/**
- * Default Logger Types Configuration
- *
- * Predefined logger types with their associated colors, labels, and log levels.
- * These types provide semantic meaning to different kinds of log messages.
- * @example
- * ```typescript
- * import { LOG_TYPES } from "@visulima/pail";
- *
- * console.log(LOG_TYPES.error.color); // "red"
- * console.log(LOG_TYPES.success.label); // "success"
- * ```
- */
-export declare const LOG_TYPES: DefaultLoggerTypes;
-/**
- * Empty Symbol
- *
- * A unique symbol used internally to represent empty or undefined message values.
- * This helps distinguish between intentional empty messages and undefined values.
- * @internal
- */
-export declare const EMPTY_SYMBOL: symbol;

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-Cd6A14ZK.js';
-export { default as InteractiveStreamHook } from '../packem_shared/InteractiveStreamHook-ePIURL_U.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;

package/dist/middleware/next/middleware.d.ts

@@ -1,59 +0,0 @@
-/**
- * Minimal type definitions to avoid requiring next as a dependency.
- */
-interface NextRequest {
-    headers: Headers;
-    nextUrl: {
-        pathname: string;
-    };
-}
-interface NextResponse {
-    headers: Headers;
-}
-interface NextResponseConstructor {
-    next: (options?: {
-        request?: {
-            headers?: Headers;
-        };
-    }) => NextResponse;
-}
-/**
- * Options for the Next.js pail middleware.
- */
-interface PailNextMiddlewareOptions {
-    /**
-     * Glob patterns for paths to exclude from logging.
-     * Excluded paths won't get request IDs or timing headers.
-     * @example ["/_next/**", "/favicon.ico"]
-     */
-    exclude?: string[];
-    /**
-     * Glob patterns for paths to include in logging.
-     * If not set, all non-excluded paths are included.
-     */
-    include?: string[];
-}
-/**
- * Create a Next.js edge middleware that sets `x-request-id` and `x-pail-start`
- * headers on the request for downstream use by `withPail()`.
- *
- * This middleware runs at the edge and prepares request metadata.
- * The actual wide event logging happens in `withPail()`.
- * @param NextResponseClass The NextResponse class from "next/server.d.ts";
- * @param options Middleware configuration
- * @returns A middleware function
- * @example
- * ```typescript
- * // middleware.ts
- * import { NextResponse } from "next/server.d.ts";
- * import { pailMiddleware } from "@visulima/pail/middleware/next";
- *
- * const middleware = pailMiddleware(NextResponse, {
- *   exclude: ["/_next/**", "/favicon.ico"],
- * });
- *
- * export default middleware;
- * ```
- */
-export declare const pailMiddleware: (NextResponseClass: NextResponseConstructor, options?: PailNextMiddlewareOptions) => (request: NextRequest) => NextResponse;
-export type { PailNextMiddlewareOptions };

package/dist/middleware/next/storage.d.ts

@@ -1,14 +0,0 @@
-import { AsyncLocalStorage } from "node:async_hooks";
-import type { WideEvent } from "../../wide-event.d.ts";
-/**
- * AsyncLocalStorage instance used to propagate the WideEvent logger
- * through Next.js server actions, route handlers, and server components.
- */
-export declare const pailStorage: AsyncLocalStorage<WideEvent>;
-/**
- * Retrieve the request-scoped WideEvent logger from AsyncLocalStorage.
- * Must be called within a `withPail()` wrapped handler or server action.
- * @returns The request-scoped WideEvent logger
- * @throws Error if called outside of a withPail context
- */
-export declare const useLogger: () => WideEvent;

package/dist/middleware/shared/create-middleware-logger.d.ts

@@ -1,82 +0,0 @@
-import type { PailBrowserImpl } from "../../pail.d.ts";
-import type { DefaultLogTypes, LoggerFunction } from "../../types.d.ts";
-import type { WideEventFinishOptions } from "../../wide-event.d.ts";
-import { WideEvent } from "../../wide-event.d.ts";
-import type { RouteConfig } from "./routes.d.ts";
-/**
- * A pail instance with dynamically generated log methods.
- */
-type PailLike<T extends string = string> = PailBrowserImpl<T> & Record<DefaultLogTypes | T, LoggerFunction>;
-/**
- * Base options shared by all framework middleware adapters.
- * @template T - Custom logger type names from the pail instance
- */
-export interface PailMiddlewareOptions<T extends string = string> {
-    /**
-     * Glob patterns for paths to exclude from logging.
-     * Exclusions take precedence over inclusions.
-     * @example ["/health", "/api/_internal/**"]
-     */
-    exclude?: string[];
-    /**
-     * Glob patterns for paths to include in logging.
-     * If not set, all non-excluded paths are logged.
-     * @example ["/api/**"]
-     */
-    include?: string[];
-    /**
-     * The pail logger instance to use for wide event emission.
-     */
-    pail: PailLike<T>;
-    /**
-     * Route-specific configuration. Maps glob patterns to config.
-     * First matching route wins.
-     * @example { "/api/auth/**": { service: "auth-service" } }
-     */
-    routes?: Record<string, RouteConfig>;
-    /**
-     * Default service name for all wide events.
-     * Can be overridden per-route via `routes`.
-     */
-    service?: string;
-}
-/**
- * Result of creating a middleware logger for a request.
- */
-export interface MiddlewareLoggerResult {
-    /**
-     * Finalize and emit the wide event. Sets status/error before emitting.
-     * Safe to call multiple times — only the first call emits.
-     */
-    finish: (options?: WideEventFinishOptions) => void;
-    /**
-     * The request-scoped WideEvent logger.
-     * Use `set()`, `info()`, `warn()`, `error()`, `debug()` to accumulate context.
-     */
-    logger: WideEvent;
-    /**
-     * Whether this request was skipped (excluded from logging).
-     * When true, `logger` and `finish` should not be used.
-     */
-    skipped: boolean;
-}
-/**
- * Core factory function used by all framework middleware adapters.
- *
- * Creates a WideEvent for the given request, checks route inclusion/exclusion,
- * resolves the service name, and returns a logger + finish callback.
- * @param options Middleware options including pail instance and route config
- * @param request Request metadata for the current HTTP request
- * @param request.headers Safe headers extracted from the request
- * @param request.method The HTTP method (GET, POST, etc.)
- * @param request.path The URL path of the request
- * @param request.requestId A unique identifier for this request
- * @returns A result object with logger, finish callback, and skipped flag
- */
-export declare const createMiddlewareLogger: <T extends string = string>(options: PailMiddlewareOptions<T>, request: {
-    headers?: Record<string, string>;
-    method: string;
-    path: string;
-    requestId: string;
-}) => MiddlewareLoggerResult;
-export {};

package/dist/middleware/shared/headers.d.ts

@@ -1,14 +0,0 @@
-/**
- * Extract safe headers from a Web API Headers object, filtering out
- * sensitive headers like Authorization, Cookie, and API keys.
- * @param headers Web API Headers object
- * @returns Plain object of safe header key-value pairs
- */
-export declare const extractSafeHeaders: (headers: Headers) => Record<string, string>;
-/**
- * Extract safe headers from a Node.js IncomingHttpHeaders object,
- * filtering out sensitive headers.
- * @param headers Node.js IncomingHttpHeaders-like object
- * @returns Plain object of safe header key-value pairs
- */
-export declare const extractSafeNodeHeaders: (headers: Record<string, string | string[] | undefined>) => Record<string, string>;

package/dist/middleware/shared/routes.d.ts

@@ -1,30 +0,0 @@
-/**
- * Check if a path matches a glob pattern.
- */
-export declare const matchesPattern: (path: string, pattern: string) => boolean;
-/**
- * Route configuration for a specific path pattern.
- */
-export interface RouteConfig {
-    /** Override the service name for requests matching this route. */
-    service?: string;
-}
-/**
- * Determine whether a request path should be logged based on include/exclude patterns.
- *
- * - Exclusions take precedence over inclusions.
- * - If no include patterns are provided, all non-excluded paths are logged.
- * @param path The request path
- * @param include Glob patterns of paths to include
- * @param exclude Glob patterns of paths to exclude
- * @returns Whether the path should be logged
- */
-export declare const shouldLog: (path: string, include?: string[], exclude?: string[]) => boolean;
-/**
- * Get the service name override for a given path based on route configuration.
- * Returns the first matching route's service name, or undefined if no match.
- * @param path The request path
- * @param routes Route configuration map (pattern → config)
- * @returns The service name override, or undefined
- */
-export declare const getServiceForPath: (path: string, routes?: Record<string, RouteConfig>) => string | undefined;

package/dist/middleware/shared/storage.d.ts

@@ -1,29 +0,0 @@
-import { AsyncLocalStorage } from "node:async_hooks";
-import type { WideEvent } from "../../wide-event.d.ts";
-/**
- * Create an isolated AsyncLocalStorage instance and a `useLogger` accessor
- * for retrieving the request-scoped WideEvent from anywhere in the call stack.
- *
- * Each framework adapter should call this once at module level to get its own
- * isolated storage instance.
- * @param contextHint A description of the expected context, used in the
- * error message when `useLogger` is called outside of a request scope.
- * @returns An object with `storage` and `useLogger`
- * @example
- * ```typescript
- * const { storage, useLogger } = createLoggerStorage(
- *   "Express middleware context. Make sure evlog middleware is registered."
- * );
- *
- * // In middleware:
- * storage.run(wideEvent, () => next());
- *
- * // In handler:
- * const log = useLogger();
- * log.set({ user: { id: 1 } });
- * ```
- */
-export declare const createLoggerStorage: (contextHint: string) => {
-    storage: AsyncLocalStorage<WideEvent>;
-    useLogger: () => WideEvent;
-};