@visulima/pail 3.1.0 → 3.2.1

package/README.md

@@ -104,6 +104,27 @@ Pail supports the logging levels described by [RFC 5424][rfc-5424].
 
 - `EMERGENCY`: Emergency: system is unusable.
 
+### Bypass Log Level Filter with Force
+
+Normally, the logger will only output messages at or above the configured level.
+
+However, you can force a log to be emitted regardless of the current level:
+
+```typescript
+import { createPail } from "@visulima/pail";
+
+const logger = createPail({
+    logLevel: "warn", // Only show warning and above
+});
+
+logger.info("This won't be logged"); // Filtered out
+
+logger.force.error("Something went wrong!");
+logger.force.info("This will show even if level is set to 'warn'");
+```
+
+⚠️ **Use this with care**—force is designed for exceptional situations where logs must be guaranteed to appear.
+
 ### Reporters
 
 Reporters are responsible for writing the log messages to the console or a file. `pail` comes with a few built-in reporters:
@@ -112,6 +133,7 @@ Reporters are responsible for writing the log messages to the console or a file.
 | ---------------------------- | ------------------------- |
 | `JsonReporter`               | `JsonReporter`            |
 | `PrettyReporter`             | `PrettyReporter`          |
+| `HttpReporter`               | `HttpReporter`            |
 | x                            | `SimpleReporter`          |
 | x                            | `FileReporter`            |
 
@@ -131,6 +153,10 @@ A processor can be added to a logger directly (and is subsequently applied to lo
     > Use `npm install @visulima/redact`, `pnpm add @visulima/redact` or `yarn add @visulima/redact` to install it.
 - `MessageFormatterProcessor` - formats the log message (Util.format-like unescaped string formatting utility) [@visulima/fmt][fmt]
 - `ErrorProcessor` - serializes the error with cause object to a std error object that can be serialized.
+- `OpenTelemetryProcessor` - adds OpenTelemetry trace context to log metadata
+    > The OpenTelemetry processor needs the "@opentelemetry/api" package to work.
+    > Use `npm install @opentelemetry/api`, `pnpm add @opentelemetry/api` or `yarn add @opentelemetry/api` to install it.
+    > Extracts trace ID, span ID, and trace flags from the active OpenTelemetry span and adds them to the log context for distributed tracing correlation.
 
 ## Usage
 
@@ -249,6 +275,66 @@ foo();
 
 ![extended scope](./__assets__/extended-scope.png)
 
+## Child Loggers
+
+Create child loggers that inherit settings from their parent while overriding only what you need. Child loggers are independent instances with their own state (timers, counters, etc.), but they inherit configuration like reporters, processors, types, log levels, and throttle settings.
+
+```typescript
+import { createPail } from "@visulima/pail";
+import { PrettyReporter } from "@visulima/pail/reporter/pretty";
+
+const parent = createPail({
+    logLevel: "informational",
+    types: {
+        http: {
+            label: "HTTP",
+            logLevel: "informational",
+        },
+    },
+    reporters: [new PrettyReporter()],
+});
+
+// Child inherits all parent settings
+const child = parent.child();
+child.http("GET /api/users 200"); // Inherits http type from parent
+child.info("Request processed"); // Inherits log level from parent
+
+// Child can override specific settings
+const debugChild = parent.child({ logLevel: "debug" });
+debugChild.debug("Detailed debug info"); // Uses debug level
+
+// Child can add new types
+const dbChild = parent.child({
+    types: {
+        db: {
+            label: "DB",
+            logLevel: "informational",
+        },
+    },
+});
+dbChild.db("Query executed"); // New type available
+dbChild.http("GET /api 200"); // Still has parent types
+
+// Child scope extends parent scope
+const scopedChild = parent.child({ scope: ["api"] });
+// Logs will include both parent and child scope if parent had scope set
+```
+
+### What Gets Inherited
+
+- **Types**: Child types are merged with parent types (child can add new or override existing)
+- **Reporters**: Child reporters are added to parent reporters (both are used)
+- **Processors**: Child processors are added to parent processors (both are applied)
+- **Log Levels**: Child log levels override parent log levels
+- **Scope**: Child scope extends parent scope (combined into array)
+- **Throttle Settings**: Child inherits parent throttle settings unless overridden
+- **Timer Messages**: Child inherits parent timer messages unless overridden
+
+### What's Independent
+
+- **State**: Each child logger has its own timers, counters, and message queue
+- **Disabled/Paused**: Child logger state is independent from parent
+
 ## Interactive Loggers (Only on if stdout and stderr is a TTY)
 
 To initialize an interactive logger, create a new pail instance with the `interactive` attribute set to `true`.
@@ -765,6 +851,218 @@ console.log(tree);
 4. **Configuration Display**: Show configuration trees in terminal applications
 5. **Data Inspection**: Inspect deeply nested data structures
 
+## HTTP Reporter
+
+The HTTP Reporter sends logs to HTTP endpoints, making it perfect for centralized logging services, log aggregation platforms, or custom logging APIs. It supports batching, compression, retries, rate limiting, and Edge Runtime compatibility.
+
+**Note:** When used in Edge Runtime environments (Next.js Edge, Cloudflare Workers, etc.), the package automatically resolves to an Edge-compatible version that disables compression and uses Edge-compatible APIs. You don't need to import a separate class - just use `HttpReporter` and the package handles the routing.
+
+### Basic Usage
+
+```typescript
+import { createPail } from "@visulima/pail";
+import { HttpReporter } from "@visulima/pail/reporter/http";
+
+const logger = createPail({
+    reporters: [
+        new HttpReporter({
+            url: "https://api.example.com/logs",
+            method: "POST",
+            headers: {
+                Authorization: "Bearer your-token",
+            },
+        }),
+    ],
+});
+
+logger.info("Application started", { version: "1.0.0" });
+```
+
+### Edge Runtime Compatibility
+
+For Edge Runtime environments, enable Edge compatibility mode explicitly (or let the package auto-detect):
+
+```typescript
+import { createPail } from "@visulima/pail";
+import { HttpReporter } from "@visulima/pail/reporter/http";
+
+const logger = createPail({
+    reporters: [
+        new HttpReporter({
+            url: "https://api.example.com/logs",
+            edgeCompat: true, // Enable Edge compatibility (auto-enabled in Edge environments)
+            headers: {
+                Authorization: "Bearer your-token",
+            },
+        }),
+    ],
+});
+
+logger.info("Edge function executed");
+```
+
+When `edgeCompat` is enabled (or automatically enabled in Edge environments), compression is disabled and Edge-compatible APIs are used.
+
+### Batching
+
+HTTP Reporter supports automatic batching to reduce network requests:
+
+```typescript
+const logger = createPail({
+    reporters: [
+        new HttpReporter({
+            url: "https://api.example.com/logs",
+            enableBatchSend: true,
+            batchSize: 100, // Send when 100 logs are queued
+            batchSendTimeout: 5000, // Or send after 5 seconds
+            batchMode: "delimiter", // Options: "delimiter", "array", "field"
+            batchSendDelimiter: "\n", // Delimiter for batch entries
+        }),
+    ],
+});
+```
+
+**Batch Modes:**
+
+- `delimiter` (default): Join entries with a delimiter (e.g., newline-delimited JSON)
+- `array`: Send entries as a JSON array
+- `field`: Wrap entries in an object with a field name (requires `batchFieldName`)
+
+```typescript
+// Field mode example (e.g., for Logflare)
+new HttpReporter({
+    url: "https://api.logflare.app/logs",
+    batchMode: "field",
+    batchFieldName: "batch", // Wraps entries in { batch: [...] }
+});
+```
+
+### Compression
+
+Enable gzip compression to reduce payload size:
+
+```typescript
+const logger = createPail({
+    reporters: [
+        new HttpReporter({
+            url: "https://api.example.com/logs",
+            compression: true, // Enable gzip compression
+        }),
+    ],
+});
+```
+
+**Note:** Compression is automatically disabled when Edge compatibility mode is enabled (either via `edgeCompat: true` or automatically in Edge Runtime environments).
+
+### Retry Logic
+
+Configure retry behavior for failed requests:
+
+```typescript
+const logger = createPail({
+    reporters: [
+        new HttpReporter({
+            url: "https://api.example.com/logs",
+            maxRetries: 3, // Retry up to 3 times
+            retryDelay: 1000, // Base delay: 1 second
+            respectRateLimit: true, // Wait on 429 responses
+        }),
+    ],
+});
+```
+
+### Error Handling
+
+Handle errors with custom callbacks:
+
+```typescript
+const logger = createPail({
+    reporters: [
+        new HttpReporter({
+            url: "https://api.example.com/logs",
+            onError: (error) => {
+                console.error("Failed to send log:", error);
+                // Send to fallback service, alert, etc.
+            },
+            onDebug: (entry) => {
+                console.log("Sending log entry:", entry);
+            },
+            onDebugRequestResponse: ({ req, res }) => {
+                console.log("Request:", req.method, req.url);
+                console.log("Response:", res.status, res.statusText);
+            },
+        }),
+    ],
+});
+```
+
+### Payload Customization
+
+Customize the payload format with a template function:
+
+```typescript
+const logger = createPail({
+    reporters: [
+        new HttpReporter({
+            url: "https://api.example.com/logs",
+            payloadTemplate: ({ data, logLevel, message }) => {
+                return JSON.stringify({
+                    timestamp: new Date().toISOString(),
+                    level: logLevel,
+                    message,
+                    metadata: data,
+                });
+            },
+        }),
+    ],
+});
+```
+
+### Size Limits
+
+Configure maximum sizes to prevent oversized payloads:
+
+```typescript
+const logger = createPail({
+    reporters: [
+        new HttpReporter({
+            url: "https://api.example.com/logs",
+            maxLogSize: 1_048_576, // 1MB per log entry
+            maxPayloadSize: 5_242_880, // 5MB per batch payload
+        }),
+    ],
+});
+```
+
+When a log entry exceeds `maxLogSize`, a `LogSizeError` is thrown. When a batch exceeds `maxPayloadSize`, it's automatically split into smaller batches.
+
+### Configuration Options
+
+| Option                   | Type                                       | Default              | Description                                   |
+| ------------------------ | ------------------------------------------ | -------------------- | --------------------------------------------- |
+| `url`                    | `string`                                   | **required**         | HTTP endpoint URL                             |
+| `method`                 | `string`                                   | `"POST"`             | HTTP method                                   |
+| `headers`                | `Record<string, string> \| (() => ...)`    | `{}`                 | Request headers (object or function)          |
+| `contentType`            | `string`                                   | `"application/json"` | Content type for single requests              |
+| `batchContentType`       | `string`                                   | `"application/json"` | Content type for batch requests               |
+| `enableBatchSend`        | `boolean`                                  | `true`               | Enable automatic batching                     |
+| `batchSize`              | `number`                                   | `100`                | Number of logs to batch before sending        |
+| `batchSendTimeout`       | `number`                                   | `5000`               | Timeout (ms) to send batch regardless of size |
+| `batchMode`              | `"delimiter" \| "array" \| "field"`        | `"delimiter"`        | Batch format mode                             |
+| `batchSendDelimiter`     | `string`                                   | `"\n"`               | Delimiter for batch entries                   |
+| `batchFieldName`         | `string`                                   | `undefined`          | Field name for "field" batch mode             |
+| `compression`            | `boolean`                                  | `false`              | Enable gzip compression                       |
+| `maxRetries`             | `number`                                   | `3`                  | Maximum retry attempts                        |
+| `retryDelay`             | `number`                                   | `1000`               | Base delay between retries (ms)               |
+| `respectRateLimit`       | `boolean`                                  | `true`               | Wait on 429 rate limit responses              |
+| `maxLogSize`             | `number`                                   | `1048576`            | Maximum size per log entry (bytes)            |
+| `maxPayloadSize`         | `number`                                   | `5242880`            | Maximum size per payload (bytes)              |
+| `edgeCompat`             | `boolean`                                  | `false`              | Enable Edge Runtime compatibility             |
+| `onError`                | `(error: Error) => void`                   | `undefined`          | Error callback                                |
+| `onDebug`                | `(entry: Record<string, unknown>) => void` | `undefined`          | Debug callback for log entries                |
+| `onDebugRequestResponse` | `(reqRes: {...}) => void`                  | `undefined`          | Debug callback for HTTP requests/responses    |
+| `payloadTemplate`        | `(data: {...}) => string`                  | `undefined`          | Custom payload formatter                      |
+
 ## Integrations
 
 ### Use with @visulima/boxen

package/dist/constants.d.ts

@@ -0,0 +1,37 @@
+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/index.browser.d.ts

@@ -1,12 +1,47 @@
-import { P as PailBrowserType } from './packem_shared/pail.browser-CmWcqnn9.js';
-import { C as ConstructorOptions } from './packem_shared/types-DVzG8TWL.js';
-export { a as DefaultLogTypes, D as DefaultLoggerTypes, E as ExtendedRfc5424LogLevels, L as LoggerConfiguration, b as LoggerFunction, c as LoggerTypesAwareReporter, d as LoggerTypesConfig, P as Processor, R as Reporter, S as StreamAwareReporter } from './packem_shared/types-DVzG8TWL.js';
-import './packem_shared/index.d-oxZvg_y7.js';
-import 'type-fest';
-import '@visulima/colorize';
-import './interactive/index.js';
-
-declare const createPail: <T extends string = string, L extends string = string>(options?: ConstructorOptions<T, L>) => PailBrowserType<T, L>;
-declare const pail: PailBrowserType<string, string>;
-
-export { ConstructorOptions, PailBrowserType as Pail, createPail, pail };
+import type { PailBrowserType } from "./pail.d.ts";
+import type { ConstructorOptions } from "./types.d.ts";
+/**
+ * Creates a new Pail logger instance configured for browser environments.
+ *
+ * This factory function creates a browser-compatible logger with default processors
+ * and reporters suitable for client-side logging.
+ * @template T - Custom logger types
+ * @template L - Log level types
+ * @param options Configuration options for the logger
+ * @returns A new PailBrowser instance
+ * @example
+ * ```typescript
+ * import { createPail } from "@visulima/pail";
+ *
+ * const logger = createPail({
+ *   logLevel: "debug",
+ *   types: {
+ *     custom: {
+ *       color: "blue",
+ *       label: "CUSTOM",
+ *       logLevel: "info"
+ *     }
+ *   }
+ * });
+ *
+ * logger.info("Hello world!");
+ * logger.custom("Custom message");
+ * ```
+ */
+export declare const createPail: <T extends string = string, L extends string = string>(options?: ConstructorOptions<T, L>) => PailBrowserType<T, L>;
+/**
+ * Default Pail logger instance for browser environments.
+ *
+ * A pre-configured logger instance ready for immediate use in browser environments.
+ * Uses default configuration with JSON reporter and message formatter processor.
+ * @example
+ * ```typescript
+ * import { pail } from "@visulima/pail";
+ *
+ * pail.info("Application started");
+ * pail.error("Something went wrong", new Error("Test error"));
+ * ```
+ */
+export declare const pail: PailBrowserType<string, string>;
+export type { PailBrowserType as Pail } from "./pail.d.ts";
+export type { ConstructorOptions, DefaultLoggerTypes, DefaultLogTypes, ExtendedRfc5424LogLevels, LoggerConfiguration, LoggerFunction, LoggerTypesAwareReporter, LoggerTypesConfig, Processor, Reporter, StreamAwareReporter, } from "./types.d.ts";

package/dist/index.browser.js

@@ -1 +1,12 @@
-var a=Object.defineProperty;var o=(r,e)=>a(r,"name",{value:e,configurable:!0});import{P as t}from"./packem_shared/pail.browser-BmHoDvEA.js";import p from"./processor/message-formatter-processor.js";import i from"./packem_shared/JsonReporter-Dl4m0xZe.js";var m=Object.defineProperty,n=o((r,e)=>m(r,"name",{value:e,configurable:!0}),"e");const s=n(r=>new t({processors:[new p],reporters:[new i],...r}),"createPail"),w=s();export{s as createPail,w as pail};
+import { P as PailBrowser } from './packem_shared/pail.browser-CPjQrsyy.js';
+import MessageFormatterProcessor from './processor/message-formatter-processor.js';
+import JsonReporter from './packem_shared/JsonReporter-DcM2LBX9.js';
+
+const createPail = (options) => new PailBrowser({
+  processors: [new MessageFormatterProcessor()],
+  reporters: [new JsonReporter()],
+  ...options
+});
+const pail = createPail();
+
+export { createPail, pail };

package/dist/index.server.d.ts

@@ -1,40 +1,65 @@
-import { InteractiveManager } from './interactive/index.js';
-import { a as PailBrowserImpl } from './packem_shared/pail.browser-CmWcqnn9.js';
-import { SingleBarOptions, ProgressBar, MultiBarOptions, MultiProgressBar } from './progress-bar.js';
-export { ProgressBarOptions, ProgressBarPayload, ProgressBarStyle, getBarChar } from './progress-bar.js';
-import { SpinnerOptions, Spinner, MultiSpinner } from './spinner.js';
-export { SpinnerIcons, SpinnerStartOptions, SpinnerStyle } from './spinner.js';
-import { g as ServerConstructorOptions, R as Reporter, a as DefaultLogTypes, b as LoggerFunction, C as ConstructorOptions } from './packem_shared/types-DVzG8TWL.js';
-export { D as DefaultLoggerTypes, E as ExtendedRfc5424LogLevels, L as LoggerConfiguration, c as LoggerTypesAwareReporter, d as LoggerTypesConfig, P as Processor, S as StreamAwareReporter } from './packem_shared/types-DVzG8TWL.js';
-import './packem_shared/index.d-oxZvg_y7.js';
-import 'type-fest';
-import '@visulima/colorize';
-
-declare class PailServerImpl<T extends string = string, L extends string = string> extends PailBrowserImpl<T, L> {
-    #private;
-    readonly options: ServerConstructorOptions<T, L>;
-    protected readonly stdout: NodeJS.WriteStream;
-    protected readonly stderr: NodeJS.WriteStream;
-    protected interactiveManager: InteractiveManager | undefined;
-    protected readonly interactive: boolean;
-    constructor(options: ServerConstructorOptions<T, L>);
-    scope<N extends string = T>(...name: string[]): PailServerType<N, L>;
-    getInteractiveManager(): InteractiveManager | undefined;
-    wrapStd(): void;
-    restoreStd(): void;
-    wrapAll(): void;
-    restoreAll(): void;
-    createProgressBar(options: SingleBarOptions): ProgressBar;
-    createMultiProgressBar(options?: MultiBarOptions): MultiProgressBar;
-    createSpinner(options?: SpinnerOptions): Spinner;
-    createMultiSpinner(options?: SpinnerOptions): MultiSpinner;
-    clear(): void;
-    protected extendReporter(reporter: Reporter<L>): Reporter<L>;
-}
-type PailServerType<T extends string = string, L extends string = string> = (new <TC extends string = string, LC extends string = string>(options?: ServerConstructorOptions<TC, LC>) => PailServerType<TC, LC>) & PailServerImpl<T, L> & Record<DefaultLogTypes, LoggerFunction> & Record<T, LoggerFunction>;
-
-declare const createPail: <T extends string = string, L extends string = string>(options?: ConstructorOptions<T, L>) => PailServerType<T, L>;
-declare const pail: PailServerType<string, string>;
-
-export { ConstructorOptions, DefaultLogTypes, LoggerFunction, MultiBarOptions, MultiProgressBar, MultiSpinner, ProgressBar, Reporter, SingleBarOptions, Spinner, SpinnerOptions, createPail, pail };
-export type { PailServerType as Pail };
+import type { PailServerType } from "./pail.d.ts";
+import type { ServerConstructorOptions } from "./types.d.ts";
+/**
+ * Creates a new Pail logger instance configured for server environments.
+ *
+ * This factory function creates a server-compatible logger with default processors
+ * and reporters suitable for Node.js environments. It automatically configures
+ * log levels based on environment variables and sets up pretty printing.
+ * @template T - Custom logger types
+ * @template L - Log level types
+ * @param options Configuration options for the logger
+ * @returns A new PailServer instance
+ * @example
+ * ```typescript
+ * import { createPail } from "@visulima/pail";
+ *
+ * const logger = createPail({
+ *   logLevel: "debug",
+ *   types: {
+ *     http: {
+ *       color: "blue",
+ *       label: "HTTP",
+ *       logLevel: "info"
+ *     }
+ *   }
+ * });
+ *
+ * logger.info("Server started on port 3000");
+ * logger.http("GET /api/users 200");
+ * ```
+ * @example
+ * ```bash
+ * # Control log level via environment variable
+ * PAIL_LOG_LEVEL=debug node app.js
+ * ```
+ */
+export declare const createPail: <T extends string = string, L extends string = string>(options?: ServerConstructorOptions<T, L>) => PailServerType<T, L>;
+/**
+ * Default Pail logger instance for server environments.
+ *
+ * A pre-configured logger instance ready for immediate use in Node.js environments.
+ * Uses default configuration with pretty reporter, message formatter processor,
+ * and automatic log level detection based on environment variables.
+ * @example
+ * ```typescript
+ * import { pail } from "@visulima/pail";
+ *
+ * pail.info("Server listening on port 3000");
+ * pail.error("Database connection failed", error);
+ * pail.success("Migration completed successfully");
+ * ```
+ * @example
+ * ```bash
+ * # Set log level via environment
+ * NODE_ENV=production node app.js
+ * PAIL_LOG_LEVEL=debug node app.js
+ * ```
+ */
+export declare const pail: PailServerType<string, string>;
+export type { PailServerType as Pail } from "./pail.d.ts";
+export type { MultiBarOptions, ProgressBarOptions, ProgressBarPayload, ProgressBarStyle, SingleBarOptions } from "./progress-bar.d.ts";
+export { getBarChar, MultiProgressBar, ProgressBar } from "./progress-bar.d.ts";
+export type { SpinnerIcons, SpinnerOptions, SpinnerStartOptions, SpinnerStyle } from "./spinner.d.ts";
+export { MultiSpinner, Spinner } from "./spinner.d.ts";
+export type { ConstructorOptions, DefaultLoggerTypes, DefaultLogTypes, ExtendedRfc5424LogLevels, LoggerConfiguration, LoggerFunction, LoggerTypesAwareReporter, LoggerTypesConfig, Processor, Reporter, StreamAwareReporter, } from "./types.d.ts";