@visulima/pail 3.1.0 → 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`.
@@ -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/index.browser.d.ts

@@ -1,6 +1,6 @@
-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 { 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';

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

package/dist/index.server.d.ts

@@ -1,11 +1,11 @@
 import { InteractiveManager } from './interactive/index.js';
-import { a as PailBrowserImpl } from './packem_shared/pail.browser-CmWcqnn9.js';
+import { a as PailBrowserImpl } from './packem_shared/pail.browser-By9KjOH7.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 { g as ServerConstructorOptions, C as ConstructorOptions, R as Reporter, a as DefaultLogTypes, b as LoggerFunction } from './packem_shared/types-D3ycu8-x.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-D3ycu8-x.js';
 import './packem_shared/index.d-oxZvg_y7.js';
 import 'type-fest';
 import '@visulima/colorize';
@@ -19,6 +19,7 @@ declare class PailServerImpl<T extends string = string, L extends string = strin
     protected readonly interactive: boolean;
     constructor(options: ServerConstructorOptions<T, L>);
     scope<N extends string = T>(...name: string[]): PailServerType<N, L>;
+    child<N extends string = T, LC extends string = L>(options?: Partial<ConstructorOptions<N, LC>> & Partial<Pick<ServerConstructorOptions<N, LC>, "interactive" | "stderr" | "stdout">>): PailServerType<N, LC>;
     getInteractiveManager(): InteractiveManager | undefined;
     wrapStd(): void;
     restoreStd(): void;
@@ -31,9 +32,11 @@ declare class PailServerImpl<T extends string = string, L extends string = strin
     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>;
+type PailServerType<T extends string = string, L extends string = string> = Console & (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> & {
+    force: 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 createPail: <T extends string = string, L extends string = string>(options?: ServerConstructorOptions<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 };