API Reference

Complete API documentation for Pail.

Core Functions

`createPail<T, L>(options?)`

Creates a new Pail logger instance.

Type Parameters:

T - Custom logger type names (default: string)
L - Custom log level types (default: string)

Parameters:

options? - Configuration options (see Configuration)

Returns: PailServerType<T, L> (server) or PailBrowserType<T, L> (browser)

Example:

import { createPail } from "@visulima/pail";

const logger = createPail({
    logLevel: "debug",
    types: {
        http: { label: "HTTP", logLevel: "info" },
    },
});

`pail`

Default pre-configured logger instance.

Example:

import { pail } from "@visulima/pail";

pail.info("Hello world");

Logger Methods

Logging Methods

All default log types are available as methods:

logger.alert(message, ...args);
logger.critical(message, ...args);
logger.debug(message, ...args);
logger.emergency(message, ...args);
logger.error(message, ...args);
logger.info(message, ...args);
logger.log(message, ...args);
logger.notice(message, ...args);
logger.pending(message, ...args);
logger.start(message, ...args);
logger.stop(message, ...args);
logger.success(message, ...args);
logger.trace(message, ...args);
logger.await(message, ...args);
logger.wait(message, ...args);
logger.warn(message, ...args);
logger.warning(message, ...args);
logger.watch(message, ...args);
logger.complete(message, ...args);

Parameters:

message - Message string, Error object, or Message object
...args - Additional context arguments

Example:

logger.info("User logged in", { userId: 123 });
logger.error(new Error("Something went wrong"));
logger.complete({
    prefix: "[task]",
    message: "Task completed",
    suffix: "(@user)",
});

`scope<N>(...name: string[]): PailServerType<N, L>`

Creates a scoped logger instance.

Parameters:

...name - Scope names (one or more)

Returns: New logger instance with scope applied

Example:

const scopedLogger = logger.scope("api", "users");
scopedLogger.info("Message"); // Includes scope

`unscope(): void`

Removes the current scope.

Example:

logger.scope("api");
logger.unscope(); // Removes scope

`time(label?: string): void`

Starts a timer with the specified label.

Parameters:

label - Timer label (default: "default")

Example:

logger.time("operation");
// ... work ...
logger.timeEnd("operation");

`timeLog(label?: string, ...data: unknown[]): void`

Logs the current elapsed time for a timer without stopping it.

Parameters:

label - Timer label (uses last timer if not specified)
...data - Additional data to include

Example:

logger.time("task");
logger.timeLog("task"); // Logs current elapsed time
logger.timeEnd("task");

`timeEnd(label?: string): void`

Stops a timer and logs the final elapsed time.

Parameters:

label - Timer label (uses last timer if not specified)

Example:

logger.time("operation");
logger.timeEnd("operation"); // Logs final time

`count(label?: string): void`

Increments and logs a counter.

Parameters:

label - Counter label (default: "default")

Example:

logger.count("requests"); // Logs: "requests: 1"
logger.count("requests"); // Logs: "requests: 2"

`countReset(label?: string): void`

Resets a counter to zero.

Parameters:

label - Counter label (default: "default")

Example:

logger.count("requests");
logger.countReset("requests"); // Resets counter

`group(label?: string): void`

Starts a log group.

Parameters:

label - Group label (default: "console.group")

Example:

logger.group("Database Operations");
logger.info("Connecting...");
logger.info("Querying...");
logger.groupEnd();

`groupEnd(): void`

Ends the current log group.

Example:

logger.group("Operations");
logger.groupEnd();

`disable(): void`

Disables all logging output.

Example:

logger.disable();
logger.info("Won't be logged");

`enable(): void`

Enables logging output.

Example:

logger.disable();
logger.enable();
logger.info("Will be logged");

`isEnabled(): boolean`

Checks if logging is currently enabled.

Returns: true if enabled, false if disabled

Example:

if (logger.isEnabled()) {
    logger.debug("Logger is active");
}

`pause(): void`

Pauses logging and starts queuing messages.

Example:

logger.pause();
logger.info("Queued");
logger.resume(); // Messages are now output

`resume(): void`

Resumes logging and flushes all queued messages.

Example:

logger.pause();
logger.resume(); // Queued messages are output

`raw(message: string, ...arguments_: unknown[]): void`

Logs a raw message bypassing normal processing.

Parameters:

message - Raw message string
...arguments_ - Additional arguments

Example:

logger.raw("Direct message", { data: "value" });

`clear(): void`

Clears the console/terminal output.

Example:

logger.clear();

Server-Only Methods

`wrapConsole(): void`

Wraps the global console methods to redirect them through the logger.

Example:

logger.wrapConsole();
console.log("Goes through logger");
logger.restoreConsole();

`restoreConsole(): void`

Restores the original global console methods.

Example:

logger.wrapConsole();
logger.restoreConsole();

`wrapStd(): void`

Wraps stdout and stderr streams to redirect them through the logger.

Example:

logger.wrapStd();
process.stdout.write("Goes through logger");
logger.restoreStd();

`restoreStd(): void`

Restores the original stdout and stderr streams.

Example:

logger.wrapStd();
logger.restoreStd();

`wrapAll(): void`

Wraps all output sources (console and streams).

Example:

logger.wrapAll();
// All output goes through logger
logger.restoreAll();

`restoreAll(): void`

Restores all wrapped output sources.

Example:

logger.wrapAll();
logger.restoreAll();

`wrapException(): void`

Wraps uncaught exception and unhandled rejection handlers.

Example:

logger.wrapException();
// Uncaught errors will be logged automatically

`getInteractiveManager(): InteractiveManager | undefined`

Gets the interactive manager instance if interactive mode is enabled.

Returns: InteractiveManager instance or undefined

Example:

const logger = createPail({ interactive: true });
const manager = logger.getInteractiveManager();

`createProgressBar(options: SingleBarOptions): ProgressBar`

Creates a single progress bar. Requires interactive mode.

Parameters:

options - Progress bar configuration

Returns: ProgressBar instance

Example:

const logger = createPail({ interactive: true });
const bar = logger.createProgressBar({ total: 100 });
bar.start();
bar.update(50);
bar.stop();

`createMultiProgressBar(options?: MultiBarOptions): MultiProgressBar`

Creates a multi-bar progress manager. Requires interactive mode.

Parameters:

options? - Multi-bar configuration

Returns: MultiProgressBar instance

Example:

const logger = createPail({ interactive: true });
const multiBar = logger.createMultiProgressBar();
const bar1 = multiBar.create(100);

`createSpinner(options?: SpinnerOptions): Spinner`

Creates a single spinner. Requires interactive mode.

Parameters:

options? - Spinner configuration

Returns: Spinner instance

Example:

const logger = createPail({ interactive: true });
const spinner = logger.createSpinner({ name: "dots" });
spinner.start("Loading...");
spinner.succeed("Done");

`createMultiSpinner(options?: SpinnerOptions): MultiSpinner`

Creates a multi-spinner manager. Requires interactive mode.

Parameters:

options? - Spinner configuration

Returns: MultiSpinner instance

Example:

const logger = createPail({ interactive: true });
const multiSpinner = logger.createMultiSpinner();
const spinner1 = multiSpinner.create("Loading 1");

Error Classes

`PailError`

Self-documenting error class with structured context fields.

Constructor:

new PailError(options: PailErrorOptions | string);

Properties:

message - Error message
status - HTTP status code (default: 500)
why - Human-readable explanation of why the error occurred
fix - Suggested fix or remediation steps
link - URL to documentation or issue tracker
cause - Original error that caused this error

Methods:

toJSON() - Returns a plain object representation
toString() - Returns a formatted string representation

Example:

import { PailError } from "@visulima/pail";

throw new PailError({
    message: "Database connection failed",
    why: "The connection pool is exhausted",
    fix: "Increase the pool size in your database config or check for connection leaks",
    link: "https://docs.example.com/db-pool",
    status: 503,
    cause: originalError,
});

`createPailError(options)`

Factory function that creates a PailError instance.

Parameters:

options - PailErrorOptions | string - Error options or message string

Returns: PailError instance

Example:

import { createPailError } from "@visulima/pail";

const error = createPailError({
    message: "API rate limit exceeded",
    why: "Too many requests in the current time window",
    fix: "Implement exponential backoff or reduce request frequency",
    status: 429,
});

`PailErrorOptions`

Options for creating a PailError.

interface PailErrorOptions {
    message: string;
    cause?: unknown;
    fix?: string;
    link?: string;
    status?: number;
    why?: string;
}

Types

`ConstructorOptions<T, L>`

Configuration options for creating a logger.

interface ConstructorOptions<T extends string, L extends string> {
    disabled?: boolean;
    logLevel?: LiteralUnion<ExtendedRfc5424LogLevels, L>;
    logLevels?: Partial<Record<ExtendedRfc5424LogLevels, number>> & Record<L, number>;
    messages?: {
        timerEnd?: string;
        timerStart?: string;
    };
    processors?: Processor<L>[];
    rawReporter?: Reporter<L>;
    reporters?: Reporter<L>[];
    scope?: string[] | string;
    throttle?: number;
    throttleMin?: number;
    types?: LoggerTypesConfig<T, L> & Partial<LoggerTypesConfig<DefaultLogTypes, L>>;
}

`ServerConstructorOptions<T, L>`

Server-specific configuration options.

interface ServerConstructorOptions<T extends string, L extends string> extends ConstructorOptions<T, L> {
    interactive?: boolean;
    stderr: NodeJS.WriteStream;
    stdout: NodeJS.WriteStream;
}

`ExtendedRfc5424LogLevels`

Standard log levels.

type ExtendedRfc5424LogLevels = "alert" | "critical" | "debug" | "emergency" | "error" | "informational" | "notice" | "trace" | "warning";

`Message`

Structured message object.

interface Message {
    context?: any[];
    message: any;
    prefix?: string;
    suffix?: string;
}

Utilities

`renderObjectTree(tree, options?)`

Renders an object as an ASCII tree structure.

Parameters:

tree - The object or array to render
options? - Configuration options (see Object Tree Usage)

Returns: string | string[] - Formatted tree as string or array of lines

Example:

import { renderObjectTree } from "@visulima/pail/object-tree";

const obj = {
    name: "John",
    age: 30,
    address: {
        street: "Main St",
        city: "New York",
    },
};

console.log(renderObjectTree(obj));

See also: Object Tree Rendering for detailed usage and examples.

Configuration - Configuration guide
Examples - Usage examples
Object Tree Rendering - Object tree utility

API Reference

On this page

Contribute to our work and keep us going

Ready to help us out?

Submit a pull request

Good first issues