@visulima/pail 3.0.3 → 3.2.0

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`.
@@ -485,6 +571,498 @@ bar.update(50, { speed: "2.5" });
 bar.stop();
 ```
 
+### Gradient Character Arrays
+
+Create smooth gradient animations by providing arrays of characters that progressively fill:
+
+```typescript
+import { createPail } from "@visulima/pail";
+
+const logger = createPail({ interactive: true });
+
+// Shade gradient (light to dark)
+const bar = logger.createProgressBar({
+    total: 100,
+    barCompleteChar: ["░", "▒", "▓", "█"], // Gradient array
+    barIncompleteChar: " ",
+    format: "Downloading [{bar}] {percentage}%",
+});
+
+bar.start();
+for (let i = 0; i <= 100; i++) {
+    bar.update(i);
+}
+bar.stop();
+```
+
+Supported gradients:
+
+- **Shades**: `["░", "▒", "▓", "█"]` (light to dark)
+- **Blocks**: `["▁", "▂", "▃", "▄", "▅", "▆", "▇", "█"]` (small to large)
+- **Temperature**: `["🔵", "🟢", "🟡", "🟠", "🔴"]` (cold to hot)
+- **Custom**: Any array of characters for your own gradient effect
+
+### Composite Progress Bars
+
+Track multiple related progress bars simultaneously with automatic color layering based on progress percentage. This is perfect for operations with multiple parallel sources or stages:
+
+```typescript
+import { createPail } from "@visulima/pail";
+import colorize from "@visulima/colorize";
+
+const logger = createPail({ interactive: true });
+
+// Create a composite multi-bar that displays all bars as a single layered composite
+const multiBar = logger.createMultiProgressBar({
+    composite: true, // Enable composite mode
+    format: "[{bar}]  ① {r}%  ② {y}%  ③ {b}%",
+});
+
+const source1 = multiBar.create(100, 0, { r: "0", y: "0", b: "0" });
+const source2 = multiBar.create(100, 0, { r: "0", y: "0", b: "0" });
+const source3 = multiBar.create(100, 0, { r: "0", y: "0", b: "0" });
+
+// Apply colors to each source
+multiBar.setBarColor(source1, colorize.red);
+multiBar.setBarColor(source2, colorize.yellow);
+multiBar.setBarColor(source3, colorize.blue);
+
+// Update sources with different speeds
+for (let i = 0; i <= 100; i++) {
+    source1.update(i); // Red: 100% progress
+    source2.update(Math.floor(i * 0.7)); // Yellow: 70% progress
+    source3.update(Math.floor(i * 0.4)); // Blue: 40% progress
+    await new Promise((r) => setTimeout(r, 40));
+}
+
+multiBar.stop();
+```
+
+**Output example:**
+
+```txt
+[▒▒▒▒▒▒▒▒▒▒▓▓▓▓▓▓▓▓██████████████████████]  ① 100%  ② 70%  ③ 40%
+```
+
+#### Color Layering & Character Shading
+
+The composite bar uses character shading to represent overlapping progress bars:
+
+| Character        | Meaning            | Example             |
+| ---------------- | ------------------ | ------------------- |
+| **█** (solid)    | One bar visible    | Red at 100%         |
+| **▓** (medium)   | Two bars overlap   | Red + Yellow        |
+| **▒** (light)    | Three bars overlap | Red + Yellow + Blue |
+| **░** (lightest) | Four+ bars overlap | All bars present    |
+
+#### How It Works
+
+The composite bar renders based on **progress percentage at each position**:
+
+1. **At position 0-40%**: Only Red (①) is filled → shows **█** with red color
+2. **At position 40-70%**: Red + Yellow (①+②) filled → shows **▓** with yellow color (highest index shown)
+3. **At position 70-100%**: All three (①+②+③) filled → shows **▒** with blue color (highest index)
+
+The **highest-indexed bar's color** is used at each position, creating a natural progression.
+
+**Dynamic Visibility Based on Progress:**
+
+The bar with the **smallest progress percentage** is shown on top for maximum visibility:
+
+- Red at 30%, Yellow at 60% → Red is visible first (30% < 60%)
+- When Red reaches 30% and Yellow is only at 20% → Yellow becomes visible (20% < 30%)
+- This ensures slower-progressing operations are always visible and not hidden beneath faster ones
+
+#### Use Cases
+
+1. **Multi-source Download**: Show progress from multiple download sources
+2. **Parallel Tasks**: Monitor concurrent operations (build, test, lint)
+3. **Pipeline Stages**: Upload → Process → Finalize with different completion times
+4. **Batch Operations**: Parse → Validate → Compile at different speeds
+5. **Resource Tracking**: CPU, Memory, Disk usage in parallel
+
+Each progress bar:
+
+- Updates independently at its own speed
+- Can have different total values and progress rates
+- Uses color to distinguish sources
+- Shows through character shading when overlapping
+
+## Spinners (Server Only)
+
+Pail includes a comprehensive spinner system inspired by cli-progress, with support for single and multi-spinner modes, various styles, and interactive terminal output.
+
+### Single Spinner
+
+```typescript
+import { createPail } from "@visulima/pail";
+
+const logger = createPail({ interactive: true });
+const spinner = logger.createSpinner({
+    text: "Loading...",
+    color: "blue",
+});
+
+spinner.start();
+spinner.succeed("Loaded!");
+spinner.fail("Failed!");
+spinner.stop();
+```
+
+### Multi Spinner
+
+```typescript
+import { createPail } from "@visulima/pail";
+
+const logger = createPail({ interactive: true });
+const multiSpinner = logger.createMultiSpinner({
+    style: "dots", // Apply style to all spinners
+});
+
+const spinner1 = multiSpinner.create("Loading A");
+const spinner2 = multiSpinner.create("Loading B");
+const spinner3 = multiSpinner.create("Loading C");
+
+// Update spinners as needed
+spinner1.succeed("Loaded A!");
+spinner2.succeed("Loaded B!");
+spinner3.succeed("Loaded C!");
+
+// Clean up when done
+multiSpinner.stop();
+```
+
+### Custom Spinner
+
+Create fully customized spinners with your own characters and formatting:
+
+```typescript
+import { createPail } from "@visulima/pail";
+
+const logger = createPail({ interactive: true });
+const spinner = logger.createSpinner({
+    text: "🚀 Downloading {filename}: [{bar}] {percentage}% | Speed: {speed} MB/s | ETA: {eta}s",
+    barCompleteChar: "🚀",
+    barIncompleteChar: "⚪",
+    width: 20,
+});
+
+spinner.start(0, 0, {
+    filename: "large-file.zip",
+    speed: "0.0",
+});
+
+// Update with payload data
+spinner.update(50, { speed: "2.5" });
+spinner.succeed();
+```
+
+## Object Tree
+
+Render objects and data structures as formatted ASCII trees for better terminal visualization and debugging:
+
+```typescript
+import { renderObjectTree } from "@visulima/pail/object-tree";
+
+const data = {
+    user: {
+        name: "John Doe",
+        email: "john@example.com",
+        profile: {
+            age: 30,
+            location: "New York",
+            skills: ["JavaScript", "TypeScript", "Node.js"],
+        },
+    },
+    settings: {
+        theme: "dark",
+        notifications: true,
+    },
+};
+
+console.log(renderObjectTree(data));
+```
+
+**Output:**
+
+```txt
+├─ user:
+│  ├─ name: John Doe
+│  ├─ email: john@example.com
+│  └─ profile:
+│     ├─ age: 30
+│     ├─ location: New York
+│     └─ skills:
+├─ settings:
+│  ├─ theme: dark
+│  └─ notifications: true
+```
+
+> **Note:** `renderObjectTree` is exported as a separate module (`@visulima/pail/object-tree`) to reduce main bundle size. It works in both **Node.js** and **Browser** environments and is a pure utility function with no platform-specific dependencies.
+
+### Custom Rendering
+
+Customize how object trees are rendered:
+
+```typescript
+import { renderObjectTree } from "@visulima/pail/object-tree";
+
+const obj = {
+    name: "John",
+    age: 30,
+    address: {
+        street: "Main St",
+        city: "New York",
+    },
+};
+
+// Custom rendering with sorting and formatting
+const tree = renderObjectTree(obj, {
+    sortFn: (a, b) => a.localeCompare(b), // Sort keys alphabetically
+    renderFn: (node) => {
+        if (typeof node === "string") return node.toUpperCase();
+        return ["boolean", "string", "number"].includes(typeof node) ? String(node) : undefined;
+    },
+    joined: true, // Return as single string (false for array of lines)
+});
+
+console.log(tree);
+```
+
+### Configuration Options
+
+| Option              | Description                                           | Default              |
+| ------------------- | ----------------------------------------------------- | -------------------- |
+| `joined`            | Return as single string or array of lines             | `true`               |
+| `sortFn`            | Function to sort object keys (null for natural order) | `null`               |
+| `renderFn`          | Function to render node values                        | Renders primitives   |
+| `separator`         | Separator between key and value                       | `": "`               |
+| `keyNeighbour`      | Connector for keys with siblings                      | `"├─ "`              |
+| `keyNoNeighbour`    | Connector for last keys                               | `"└─ "`              |
+| `spacerNeighbour`   | Spacer for branches with siblings                     | `"│  "`              |
+| `spacerNoNeighbour` | Spacer for branches without siblings                  | `"   "`              |
+| `breakCircularWith` | Text for circular references                          | `" (circular ref.)"` |
+
+### Use Cases
+
+1. **Debugging**: Visualize complex object structures during development
+2. **Logging**: Pretty-print objects for better readability in logs
+3. **API Responses**: Display JSON API responses in tree format
+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/index.browser.d.ts

@@ -1,9 +1,10 @@
-import { P as PailBrowserType } from './packem_shared/pail.browser-Bs2ng_Qj.js';
-import { C as ConstructorOptions } from './packem_shared/types-RidvA4RN.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-RidvA4RN.js';
+import { P as PailBrowserType } from './packem_shared/pail.browser-By9KjOH7.js';
+import { C as ConstructorOptions } from './packem_shared/types-D3ycu8-x.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-D3ycu8-x.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>;

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-CPDOE_d1.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 };