@visulima/pail 4.0.2 → 4.1.0

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

@@ -37,36 +37,36 @@ const petWithAutoComplete: Pet2 = '';
 */
 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;
-*     }
-*   }
-* }
-* ```
-*/
+ * 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
-*/
+ * 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;
@@ -86,38 +86,38 @@ interface Meta<L> extends VisulimaPail.CustomMeta<L> {
   };
 }
 /**
-* 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
-*/
+ * 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
-*/
+ * 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
-*/
+ * 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
-*/
+ * 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;
@@ -138,8 +138,8 @@ interface StringifyOptions {
   strict?: boolean;
 }
 /**
-* Options for configuring JSON reporters.
-*/
+ * Options for configuring JSON reporters.
+ */
 type AbstractJsonReporterOptions = {
   /** Error serialization options */
   error: Partial<{
@@ -152,145 +152,148 @@ type AbstractJsonReporterOptions = {
   }>;
 };
 /**
-* 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);
-*   }
-* }
-* ```
-*/
+ * 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
-  */
+   * 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
-  */
+   * 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
-  */
+   * 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.
-*/
+ * Configuration options for the HTTP reporter.
+ */
 type AbstractHttpReporterOptions = AbstractJsonReporterOptions & {
   /**
-  * Content type for batch log requests. User-specified headers take precedence.
-  * @default "application/json"
-  */
+   * 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
-  */
+   * 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"
-  */
+   * 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"
-  */
+   * Delimiter to use between log entries in batch mode
+   * @default "\n"
+   */
   batchSendDelimiter?: string;
   /**
-  * Timeout in milliseconds for sending batches regardless of size
-  * @default 5000
-  */
+   * Timeout in milliseconds for sending batches regardless of size
+   * @default 5000
+   */
   batchSendTimeout?: number;
   /**
-  * Number of log entries to batch before sending
-  * @default 100
-  */
+   * Number of log entries to batch before sending
+   * @default 100
+   */
   batchSize?: number;
   /**
-  * Whether to use gzip compression
-  * @default false
-  */
+   * Whether to use gzip compression
+   * @default false
+   */
   compression?: boolean;
   /**
-  * Content type for single log requests. User-specified headers take precedence.
-  * @default "application/json"
-  */
+   * 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
-  */
+   * Whether to enable Edge Runtime compatibility mode.
+   *
+   * When enabled, gzip compression is skipped so the reporter never depends on a
+   * compression implementation the runtime may not provide. Payload size accounting
+   * always uses the Web-standard `TextEncoder` and is unaffected by this flag.
+   * @default false
+   */
   edgeCompat?: boolean;
   /**
-  * Whether to enable batch sending
-  * @default true
-  */
+   * 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 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)
-  */
+   * 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)
-  */
+   * Maximum size of the payload (uncompressed) in bytes
+   * @default 5242880 (5MB)
+   */
   maxPayloadSize?: number;
   /**
-  * Maximum number of entries to keep queued while the endpoint is unavailable.
-  * When the queue exceeds this limit, the oldest entries are dropped (drop-oldest)
-  * so a sustained outage cannot grow memory without bound.
-  * @default 10000
-  */
+   * Maximum number of entries to keep queued while the endpoint is unavailable.
+   * When the queue exceeds this limit, the oldest entries are dropped (drop-oldest)
+   * so a sustained outage cannot grow memory without bound.
+   * @default 10000
+   */
   maxQueueSize?: number;
   /**
-  * Number of retry attempts before giving up
-  * @default 3
-  */
+   * Number of retry attempts before giving up
+   * @default 3
+   */
   maxRetries?: number;
   /**
-  * HTTP method to use for requests
-  * @default "POST"
-  */
+   * HTTP method to use for requests
+   * @default "POST"
+   */
   method?: string;
   /**
-  * Optional callback for debugging log entries before they are sent
-  */
+   * Optional callback for debugging log entries before they are sent
+   */
   onDebug?: (entry: Record<string, unknown>) => void;
   /**
-  * Optional callback for debugging HTTP requests and responses
-  */
+   * Optional callback for debugging HTTP requests and responses
+   */
   onDebugRequestResponse?: (requestResponse: {
     req: {
       body: string | Uint8Array;
@@ -306,45 +309,45 @@ type AbstractHttpReporterOptions = AbstractJsonReporterOptions & {
     };
   }) => void;
   /**
-  * Optional callback invoked when queued log entries are dropped because the queue
-  * exceeded `maxQueueSize`. Receives the number of dropped entries.
-  */
+   * Optional callback invoked when queued log entries are dropped because the queue
+   * exceeded `maxQueueSize`. Receives the number of dropped entries.
+   */
   onDrop?: (droppedCount: number) => void;
   /**
-  * Optional callback for error handling
-  */
+   * 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.
-  */
+   * 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
-  */
+   * 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
-  */
+   * Base delay between retries in milliseconds
+   * @default 1000
+   */
   retryDelay?: number;
   /**
-  * The URL to send logs to
-  */
+   * 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
-*/
+ * 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> {
   #private;
   protected url: string;
@@ -389,100 +392,102 @@ declare abstract class AbstractHttpReporter<L extends string = string> extends A
   protected maxPayloadSize: number;
   protected edgeCompat: boolean;
   protected batchQueue: string[];
+  /** Per-entry UTF-8 byte sizes, kept in lockstep with `batchQueue`, so the tracked queue size never re-encodes payloads. */
+  protected batchSizeQueue: number[];
   protected batchTimeout?: ReturnType<typeof setTimeout>;
   protected isProcessingBatch: boolean;
   protected currentBatchSize: number;
   /**
-  * Creates a new instance of AbstractHttpReporter.
-  * @param config Configuration options for the reporter
-  */
+   * Creates a new instance of AbstractHttpReporter.
+   * @param config Configuration options for the reporter
+   */
   constructor(config: AbstractHttpReporterOptions);
   /**
-  * Flushes all queued log entries to the HTTP endpoint immediately.
-  *
-  * Returns a promise that resolves once the queue has been drained (or rejects
-  * if a batch send fails terminally). Use this before a serverless function or
-  * short-lived process exits so the tail of the batch is not lost.
-  * @example
-  * ```typescript
-  * await reporter.flush();
-  * ```
-  */
+   * Flushes all queued log entries to the HTTP endpoint immediately.
+   *
+   * Returns a promise that resolves once the queue has been drained (or rejects
+   * if a batch send fails terminally). Use this before a serverless function or
+   * short-lived process exits so the tail of the batch is not lost.
+   * @example
+   * ```typescript
+   * await reporter.flush();
+   * ```
+   */
   flush(): Promise<void>;
   /**
-  * Flushes any remaining queued entries and clears pending timers.
-  *
-  * Counterpart to a transport lifecycle `end`/`dispose`. After calling `close()`
-  * the reporter can still be used, but any pending batch timeout is cleared.
-  * @example
-  * ```typescript
-  * process.on("beforeExit", () => reporter.close());
-  * ```
-  */
+   * Flushes any remaining queued entries and clears pending timers.
+   *
+   * Counterpart to a transport lifecycle `end`/`dispose`. After calling `close()`
+   * the reporter can still be used, but any pending batch timeout is cleared.
+   * @example
+   * ```typescript
+   * process.on("beforeExit", () => reporter.close());
+   * ```
+   */
   close(): Promise<void>;
   /**
-  * Alias for {@link close} to match common transport `dispose` conventions.
-  */
+   * Alias for {@link close} to match common transport `dispose` conventions.
+   */
   dispose(): Promise<void>;
   /**
-  * 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
-  */
+   * 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.
-  */
+   * 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.
-  */
+   * Processes the current batch and sends it to the HTTP endpoint.
+   */
   protected processBatch(): Promise<void>;
   /**
-  * Sends a batch of payloads to the HTTP endpoint.
-  */
+   * Sends a batch of payloads to the HTTP endpoint.
+   */
   protected sendBatch(batch: string[]): Promise<void>;
   /**
-  * Sends a single payload to the HTTP endpoint.
-  */
+   * 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");
-* ```
-*/
+ * 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
-  */
+   * 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 { HttpReporterEdgeLight as default };