@visulima/pail 4.0.0-alpha.10 → 4.0.0-alpha.12

package/dist/reporter/http/http-reporter.edge-light.d.ts

@@ -1,40 +1,432 @@
-import type { AbstractHttpReporterOptions } from "./abstract-http-reporter.d.ts";
-import { AbstractHttpReporter } from "./abstract-http-reporter.d.ts";
-/**
- * HTTP Reporter for Edge Runtime environments.
- *
- * A reporter optimized for Edge Runtime environments (Next.js Edge, Cloudflare Workers, etc.)
- * that sends logs to HTTP endpoints. Edge compatibility mode is enabled by default.
- * Supports batching, retries, and rate limiting. Compression is disabled for Edge compatibility.
- * @template L - The log level type
- * @example
- * ```typescript
- * import { createPail } from "@visulima/pail";
- * import { HttpReporterEdgeLight } from "@visulima/pail/reporter/http/edge-light";
- *
- * const logger = createPail({
- *   reporters: [
- *     new HttpReporterEdgeLight({
- *       url: "https://api.example.com/logs",
- *       method: "POST",
- *       headers: {
- *         "Authorization": "Bearer token"
- *       },
- *       enableBatchSend: true,
- *       batchSize: 50
- *     })
- *   ]
- * });
- *
- * logger.info("Edge function started");
- * ```
- */
+import '@visulima/colorize';
+import '@visulima/interactive-manager';
+import { stringify } from 'safe-stable-stringify';
+/**
+Matches any [primitive value](https://developer.mozilla.org/en-US/docs/Glossary/Primitive).
+
+@category Type
+*/
+type Primitive = null | undefined | string | number | boolean | symbol | bigint;
+/**
+Create a union type by combining primitive types and literal types without sacrificing auto-completion in IDEs for the literal type part of the union.
+
+Currently, when a union type of a primitive type is combined with literal types, TypeScript loses all information about the combined literals. Thus, when such type is used in an IDE with autocompletion, no suggestions are made for the declared literals.
+
+This type is a workaround for [Microsoft/TypeScript#29729](https://github.com/Microsoft/TypeScript/issues/29729). It will be removed as soon as it's not needed anymore.
+
+@example
+```
+import type {LiteralUnion} from 'type-fest';
+
+// Before
+
+type Pet = 'dog' | 'cat' | string;
+
+const petWithoutAutocomplete: Pet = '';
+// Start typing in your TypeScript-enabled IDE.
+// You **will not** get auto-completion for `dog` and `cat` literals.
+
+// After
+
+type Pet2 = LiteralUnion<'dog' | 'cat', string>;
+
+const petWithAutoComplete: Pet2 = '';
+// You **will** get auto-completion for `dog` and `cat` literals.
+```
+
+@category Type
+*/
+type LiteralUnion<LiteralType, BaseType extends Primitive> = LiteralType | (BaseType & Record<never, never>);
+/**
+* Global namespace for extending Pail's metadata interface.
+*
+* This global declaration allows other packages and applications to extend
+* the Meta interface with custom properties by declaring additional properties
+* in the VisulimaPail.CustomMeta interface.
+* @example
+* ```typescript
+* declare global {
+*   namespace VisulimaPail {
+*     interface CustomMeta<L> {
+*       userId?: string;
+*       requestId?: string;
+*     }
+*   }
+* }
+* ```
+*/
+declare global {
+  namespace VisulimaPail {
+    interface CustomMeta<L> {}
+  }
+}
+/**
+* Metadata object containing all information about a log entry.
+*
+* This interface defines the structure of metadata that is passed to reporters
+* and processors. It contains all the contextual information about a log message
+* including the message itself, timing information, error details, and more.
+* @template L - The log level type
+*/
+interface Meta<L> extends VisulimaPail.CustomMeta<L> {
+  badge: string | undefined;
+  context: any[] | undefined;
+  date: Date | string;
+  error: Error | undefined;
+  groups: string[];
+  label: string | undefined;
+  message: Primitive | ReadonlyArray<unknown> | Record<PropertyKey, unknown>;
+  prefix: string | undefined;
+  repeated?: number;
+  scope: string[] | undefined;
+  suffix: string | undefined;
+  traceError: Error | undefined;
+  type: {
+    level: ExtendedRfc5424LogLevels | L;
+    name: string;
+  };
+}
+/**
+* Extended RFC 5424 Log Levels.
+*
+* Standard syslog severity levels as defined in RFC 5424, plus additional
+* levels commonly used in modern applications. Each level has a numeric
+* priority where lower numbers indicate higher severity.
+* @see https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1
+*/
+type ExtendedRfc5424LogLevels = "alert" | "critical" | "debug" | "emergency" | "error" | "informational" | "notice" | "trace" | "warning";
+/**
+* Read-only Metadata.
+*
+* Immutable version of the Meta interface for use in reporters.
+* @template L - The log level type
+*/
+type ReadonlyMeta<L extends string> = Readonly<Meta<L>>;
+/**
+* Reporter Interface.
+*
+* Base interface for all reporters. Reporters are responsible for
+* outputting log messages to various destinations (console, files, etc.).
+* @template L - The log level type
+*/
+interface Reporter<L extends string> {
+  log: (meta: ReadonlyMeta<L>) => void;
+}
+/**
+* Stringify-Aware Reporter Interface.
+*
+* Extends Reporter with the ability to receive a custom stringify function.
+* Useful for reporters that need to serialize complex objects.
+* @template L - The log level type
+*/
+interface StringifyAwareReporter<L extends string> extends Reporter<L> {
+  /** Set the stringify function for object serialization */
+  setStringify: (stringify: any) => void;
+}
+/**
+* Options for configuring JSON reporters.
+*/
+type AbstractJsonReporterOptions = {
+  /** Error serialization options */
+  error: Partial<{
+    /** Properties to exclude from error serialization */
+    exclude?: string[];
+    /** Maximum depth for error object serialization */
+    maxDepth?: number;
+    /** Whether to use toJSON methods during serialization */
+    useToJSON?: boolean;
+  }>;
+};
+/**
+* Abstract JSON Reporter.
+*
+* Base class for JSON-based reporters that provides common functionality
+* for serializing log metadata to JSON format. Handles error serialization,
+* context processing, and provides a template method for actual output.
+* @template L - The log level type
+* @example
+* ```typescript
+* class CustomJsonReporter extends AbstractJsonReporter {
+*   protected _log(message: string): void {
+*     console.log(message);
+*   }
+* }
+* ```
+*/
+declare abstract class AbstractJsonReporter<L extends string = string> implements StringifyAwareReporter<L> {
+  /** Custom stringify function for object serialization */
+  protected stringify: typeof stringify | undefined;
+  /** Error serialization options */
+  protected errorOptions: AbstractJsonReporterOptions["error"];
+  /**
+  * Creates a new AbstractJsonReporter instance.
+  * @param options Configuration options for JSON formatting and error handling
+  */
+  constructor(options?: Partial<AbstractJsonReporterOptions>);
+  /**
+  * Sets a custom stringify function for object serialization.
+  * @param function_ The stringify function to use for serialization
+  */
+  setStringify(function_: typeof stringify): void;
+  log(meta: ReadonlyMeta<L>): void;
+  /**
+  * Template method for outputting the JSON log message.
+  *
+  * Subclasses must implement this method to define how the JSON message
+  * is actually written (to console, file, network, etc.).
+  * @param message The JSON-formatted log message
+  * @param logLevel The log level of the message
+  * @protected
+  * @abstract
+  */
+  protected abstract _log(message: string, logLevel: LiteralUnion<ExtendedRfc5424LogLevels, L>): void;
+}
+/**
+* Configuration options for the HTTP reporter.
+*/
+type AbstractHttpReporterOptions = AbstractJsonReporterOptions & {
+  /**
+  * Content type for batch log requests. User-specified headers take precedence.
+  * @default "application/json"
+  */
+  batchContentType?: string;
+  /**
+  * Field name to wrap batch entries in when batchMode is "field" (e.g., "batch" for Logflare)
+  * @default undefined
+  */
+  batchFieldName?: string;
+  /**
+  * Batch mode for sending multiple log entries
+  * - "delimiter": Join entries with a delimiter (default)
+  * - "field": Wrap entries in an object with a field name
+  * - "array": Send entries as a plain JSON array
+  * @default "delimiter"
+  */
+  batchMode?: "delimiter" | "field" | "array";
+  /**
+  * Delimiter to use between log entries in batch mode
+  * @default "\n"
+  */
+  batchSendDelimiter?: string;
+  /**
+  * Timeout in milliseconds for sending batches regardless of size
+  * @default 5000
+  */
+  batchSendTimeout?: number;
+  /**
+  * Number of log entries to batch before sending
+  * @default 100
+  */
+  batchSize?: number;
+  /**
+  * Whether to use gzip compression
+  * @default false
+  */
+  compression?: boolean;
+  /**
+  * Content type for single log requests. User-specified headers take precedence.
+  * @default "application/json"
+  */
+  contentType?: string;
+  /**
+  * Whether to enable Edge Runtime compatibility mode
+  * When enabled, TextEncoder and compression are disabled
+  * @default false
+  */
+  edgeCompat?: boolean;
+  /**
+  * Whether to enable batch sending
+  * @default true
+  */
+  enableBatchSend?: boolean;
+  /**
+  * Headers to include in the request. Can be an object or a function that returns headers.
+  */
+  headers?: Record<string, string> | (() => Record<string, string>);
+  /**
+  * Maximum size of a single log entry in bytes
+  * @default 1048576 (1MB)
+  */
+  maxLogSize?: number;
+  /**
+  * Maximum size of the payload (uncompressed) in bytes
+  * @default 5242880 (5MB)
+  */
+  maxPayloadSize?: number;
+  /**
+  * Number of retry attempts before giving up
+  * @default 3
+  */
+  maxRetries?: number;
+  /**
+  * HTTP method to use for requests
+  * @default "POST"
+  */
+  method?: string;
+  /**
+  * Optional callback for debugging log entries before they are sent
+  */
+  onDebug?: (entry: Record<string, unknown>) => void;
+  /**
+  * Optional callback for debugging HTTP requests and responses
+  */
+  onDebugRequestResponse?: (requestResponse: {
+    req: {
+      body: string | Uint8Array;
+      headers: Record<string, string>;
+      method: string;
+      url: string;
+    };
+    res: {
+      body: string;
+      headers: Record<string, string>;
+      status: number;
+      statusText: string;
+    };
+  }) => void;
+  /**
+  * Optional callback for error handling
+  */
+  onError?: (error: Error) => void;
+  /**
+  * Function to transform log data into the payload format.
+  * By default, uses the JSON stringified log entry.
+  */
+  payloadTemplate?: (data: {
+    data?: Record<string, unknown>;
+    logLevel: string;
+    message: string;
+  }) => string;
+  /**
+  * Whether to respect rate limiting by waiting when a 429 response is received
+  * @default true
+  */
+  respectRateLimit?: boolean;
+  /**
+  * Base delay between retries in milliseconds
+  * @default 1000
+  */
+  retryDelay?: number;
+  /**
+  * The URL to send logs to
+  */
+  url: string;
+};
+/**
+* Abstract HTTP Reporter.
+*
+* Base class for HTTP-based reporters that sends logs to HTTP endpoints.
+* Supports batching, compression, retries, and rate limiting.
+* @template L - The log level type
+*/
+declare abstract class AbstractHttpReporter<L extends string = string> extends AbstractJsonReporter<L> implements StringifyAwareReporter<L> {
+  protected url: string;
+  protected method: string;
+  protected headers: Record<string, string> | (() => Record<string, string>);
+  protected contentType: string;
+  protected batchContentType: string;
+  protected onError?: (error: Error) => void;
+  protected onDebug?: (entry: Record<string, unknown>) => void;
+  protected onDebugRequestResponse?: (requestResponse: {
+    req: {
+      body: string | Uint8Array;
+      headers: Record<string, string>;
+      method: string;
+      url: string;
+    };
+    res: {
+      body: string;
+      headers: Record<string, string>;
+      status: number;
+      statusText: string;
+    };
+  }) => void;
+  protected payloadTemplate: (data: {
+    data?: Record<string, unknown>;
+    logLevel: string;
+    message: string;
+  }) => string;
+  protected compression: boolean;
+  protected maxRetries: number;
+  protected retryDelay: number;
+  protected respectRateLimit: boolean;
+  protected enableBatchSend: boolean;
+  protected batchSize: number;
+  protected batchSendTimeout: number;
+  protected batchSendDelimiter: string;
+  protected batchMode: "delimiter" | "field" | "array";
+  protected batchFieldName?: string;
+  protected maxLogSize: number;
+  protected maxPayloadSize: number;
+  protected edgeCompat: boolean;
+  protected batchQueue: string[];
+  protected batchTimeout?: ReturnType<typeof setTimeout>;
+  protected isProcessingBatch: boolean;
+  protected currentBatchSize: number;
+  /**
+  * Creates a new instance of AbstractHttpReporter.
+  * @param config Configuration options for the reporter
+  */
+  constructor(config: AbstractHttpReporterOptions);
+  /**
+  * Processes and ships log entries to the HTTP endpoint.
+  * @param message The JSON-formatted log message
+  * @param logLevel The log level of the message
+  * @protected
+  */
+  protected override _log(message: string, logLevel: LiteralUnion<ExtendedRfc5424LogLevels, L>): void;
+  /**
+  * Adds a payload to the batch queue and triggers sending if conditions are met.
+  */
+  protected addToBatch(payload: string, logEntrySize: number): void;
+  /**
+  * Processes the current batch and sends it to the HTTP endpoint.
+  */
+  protected processBatch(): Promise<void>;
+  /**
+  * Sends a batch of payloads to the HTTP endpoint.
+  */
+  protected sendBatch(batch: string[]): Promise<void>;
+  /**
+  * Sends a single payload to the HTTP endpoint.
+  */
+  protected sendPayload(payload: string, contentType?: string): Promise<void>;
+}
+/**
+* HTTP Reporter for Edge Runtime environments.
+*
+* A reporter optimized for Edge Runtime environments (Next.js Edge, Cloudflare Workers, etc.)
+* that sends logs to HTTP endpoints. Edge compatibility mode is enabled by default.
+* Supports batching, retries, and rate limiting. Compression is disabled for Edge compatibility.
+* @template L - The log level type
+* @example
+* ```typescript
+* import { createPail } from "@visulima/pail";
+* import { HttpReporterEdgeLight } from "@visulima/pail/reporter/http/edge-light";
+*
+* const logger = createPail({
+*   reporters: [
+*     new HttpReporterEdgeLight({
+*       url: "https://api.example.com/logs",
+*       method: "POST",
+*       headers: {
+*         "Authorization": "Bearer token"
+*       },
+*       enableBatchSend: true,
+*       batchSize: 50
+*     })
+*   ]
+* });
+*
+* logger.info("Edge function started");
+* ```
+*/
 declare class HttpReporterEdgeLight<L extends string = string> extends AbstractHttpReporter<L> {
-    /**
-     * Creates a new HTTP Reporter Edge Light instance.
-     * Edge compatibility mode is automatically enabled.
-     * @param options Configuration options for HTTP reporting
-     */
-    constructor(options: Omit<AbstractHttpReporterOptions, "edgeCompat">);
+  /**
+  * Creates a new HTTP Reporter Edge Light instance.
+  * Edge compatibility mode is automatically enabled.
+  * @param options Configuration options for HTTP reporting
+  */
+  constructor(options: Omit<AbstractHttpReporterOptions, "edgeCompat">);
 }
-export default HttpReporterEdgeLight;
+export { HttpReporterEdgeLight as default };

package/dist/reporter/http/http-reporter.edge-light.js

@@ -284,11 +284,7 @@ class AbstractJsonReporter {
     if (file) {
       rest.file = `${file.name ?? ""}:${String(file.line)}${file.column ? `:${String(file.column)}` : ""}`;
     }
-    if (message === EMPTY_SYMBOL) {
-      rest.message = void 0;
-    } else {
-      rest.message = message;
-    }
+    rest.message = message === EMPTY_SYMBOL ? void 0 : message;
     if (error) {
       rest.error = serialize(error, this.errorOptions);
     }

package/dist/reporter/json/index.browser.d.ts

@@ -1,3 +1,99 @@
-export type { AbstractJsonReporterOptions } from "./abstract-json-reporter.d.ts";
-export { AbstractJsonReporter } from "./abstract-json-reporter.d.ts";
-export { default as JsonReporter } from "./json-reporter.d.ts";
+import { stringify } from 'safe-stable-stringify';
+import { LiteralUnion } from 'type-fest';
+import { R as ReadonlyMeta, E as ExtendedRfc5424LogLevels, S as StringifyAwareReporter } from "../../packem_shared/types.d-C51XNfQz.js";
+import '@visulima/colorize';
+import '@visulima/interactive-manager';
+/**
+* Options for configuring JSON reporters.
+*/
+type AbstractJsonReporterOptions = {
+  /** Error serialization options */
+  error: Partial<{
+    /** Properties to exclude from error serialization */
+    exclude?: string[];
+    /** Maximum depth for error object serialization */
+    maxDepth?: number;
+    /** Whether to use toJSON methods during serialization */
+    useToJSON?: boolean;
+  }>;
+};
+/**
+* Abstract JSON Reporter.
+*
+* Base class for JSON-based reporters that provides common functionality
+* for serializing log metadata to JSON format. Handles error serialization,
+* context processing, and provides a template method for actual output.
+* @template L - The log level type
+* @example
+* ```typescript
+* class CustomJsonReporter extends AbstractJsonReporter {
+*   protected _log(message: string): void {
+*     console.log(message);
+*   }
+* }
+* ```
+*/
+declare abstract class AbstractJsonReporter<L extends string = string> implements StringifyAwareReporter<L> {
+  /** Custom stringify function for object serialization */
+  protected stringify: typeof stringify | undefined;
+  /** Error serialization options */
+  protected errorOptions: AbstractJsonReporterOptions["error"];
+  /**
+  * Creates a new AbstractJsonReporter instance.
+  * @param options Configuration options for JSON formatting and error handling
+  */
+  constructor(options?: Partial<AbstractJsonReporterOptions>);
+  /**
+  * Sets a custom stringify function for object serialization.
+  * @param function_ The stringify function to use for serialization
+  */
+  setStringify(function_: typeof stringify): void;
+  log(meta: ReadonlyMeta<L>): void;
+  /**
+  * Template method for outputting the JSON log message.
+  *
+  * Subclasses must implement this method to define how the JSON message
+  * is actually written (to console, file, network, etc.).
+  * @param message The JSON-formatted log message
+  * @param logLevel The log level of the message
+  * @protected
+  * @abstract
+  */
+  protected abstract _log(message: string, logLevel: LiteralUnion<ExtendedRfc5424LogLevels, L>): void;
+}
+/**
+* Browser JSON Reporter.
+*
+* A JSON reporter for browser environments that outputs structured log data
+* to the browser console. Uses appropriate console methods based on log level.
+* @template L - The log level type
+* @example
+* ```typescript
+* import { createPail } from "@visulima/pail";
+*
+* const logger = createPail({
+*   reporters: [new JsonReporter()]
+* });
+*
+* logger.info("Application started", { version: "1.0.0" });
+* // Outputs: {"level":"info","message":"Application started","context":[{"version":"1.0.0"}],...}
+* ```
+*/
+declare class JsonReporter<L extends string = string> extends AbstractJsonReporter<L> {
+  /**
+  * Creates a new Browser JSON Reporter instance.
+  * @param options Configuration options for JSON formatting
+  */
+  constructor(options?: Partial<AbstractJsonReporterOptions>);
+  /**
+  * Outputs the JSON message to the browser console.
+  *
+  * Uses the appropriate console method based on the log level
+  * (console.log, console.error, console.warn, etc.).
+  * @param message The JSON-formatted log message
+  * @param logLevel The log level determining which console method to use
+  * @protected
+  */
+  protected override _log(message: string, logLevel: LiteralUnion<ExtendedRfc5424LogLevels, L>): void;
+}
+export { AbstractJsonReporter, type AbstractJsonReporterOptions, JsonReporter };

package/dist/reporter/json/index.browser.js

@@ -1,2 +1,2 @@
-export { AbstractJsonReporter } from '../../packem_shared/AbstractJsonReporter-DlugSJpY.js';
-export { default as JsonReporter } from '../../packem_shared/JsonReporter-Dbw82ewj.js';
+export { AbstractJsonReporter } from '../../packem_shared/AbstractJsonReporter-BO8Calb4.js';
+export { default as JsonReporter } from '../../packem_shared/JsonReporter-CCmj7oYL.js';

package/dist/reporter/json/index.d.ts

@@ -1,3 +1,51 @@
-export type { AbstractJsonReporterOptions } from "./abstract-json-reporter.d.ts";
-export { AbstractJsonReporter } from "./abstract-json-reporter.d.ts";
-export { default as JsonReporter } from "./json-reporter.d.ts";
+import { A as AbstractJsonReporterOptions, a as AbstractJsonReporter } from "../../packem_shared/abstract-json-reporter.d-BAgznjyU.js";
+import { E as ExtendedRfc5424LogLevels, L as LiteralUnion, a as StreamAwareReporter } from "../../packem_shared/types.d-BeLumqgD.js";
+import 'safe-stable-stringify';
+import '@visulima/colorize';
+import '@visulima/interactive-manager';
+/**
+* Server JSON Reporter.
+*
+* A JSON reporter for Node.js server environments that outputs structured log data
+* to stdout/stderr streams. Routes error-level logs to stderr and others to stdout.
+* @template L - The log level type
+* @example
+* ```typescript
+* import { createPail } from "@visulima/pail";
+*
+* const logger = createPail({
+*   reporters: [new JsonReporter()]
+* });
+*
+* logger.info("Server started", { port: 3000 });
+* logger.error("Database connection failed", error);
+* ```
+*/
+declare class JsonReporter<L extends string = string> extends AbstractJsonReporter<L> implements StreamAwareReporter<L> {
+  #private;
+  /**
+  * Creates a new Server JSON Reporter instance.
+  * @param options Configuration options for JSON formatting
+  */
+  constructor(options?: Partial<AbstractJsonReporterOptions>);
+  /**
+  * Sets the stdout stream for the reporter.
+  * @param stdout_ The writable stream to use for stdout output
+  */
+  setStdout(stdout_: NodeJS.WriteStream): void;
+  /**
+  * Sets the stderr stream for the reporter.
+  * @param stderr_ The writable stream to use for stderr output
+  */
+  setStderr(stderr_: NodeJS.WriteStream): void;
+  /**
+  * Outputs the JSON message to the appropriate stream.
+  *
+  * Routes error and warning level messages to stderr, others to stdout.
+  * @param message The JSON-formatted log message
+  * @param logLevel The log level determining which stream to use
+  * @protected
+  */
+  protected override _log(message: string, logLevel: LiteralUnion<ExtendedRfc5424LogLevels, L>): void;
+}
+export { AbstractJsonReporter, type AbstractJsonReporterOptions, JsonReporter };

package/dist/reporter/json/index.js

@@ -1,2 +1,2 @@
-export { AbstractJsonReporter } from '../../packem_shared/AbstractJsonReporter-CjtVgHbU.js';
-export { default as JsonReporter } from '../../packem_shared/JsonReporter-BgPvIyC2.js';
+export { AbstractJsonReporter } from '../../packem_shared/AbstractJsonReporter-nOj0Ft1F.js';
+export { default as JsonReporter } from '../../packem_shared/JsonReporter-Ck2PIAEw.js';