@visulima/pail 4.0.0-alpha.9 → 4.0.1

package/dist/reporter/http/abstract-http-reporter.d.ts

@@ -1,215 +1,260 @@
-import type { LiteralUnion } from "type-fest";
-import type { ExtendedRfc5424LogLevels, StringifyAwareReporter } from "../../types.d.ts";
-import type { AbstractJsonReporterOptions } from "../json/abstract-json-reporter.d.ts";
-import { AbstractJsonReporter } from "../json/abstract-json-reporter.d.ts";
+import { LiteralUnion } from 'type-fest';
+import { E as ExtendedRfc5424LogLevels, S as StringifyAwareReporter } from "../../packem_shared/types.d-bWnqHJKL.js";
+import { A as AbstractJsonReporterOptions, a as AbstractJsonReporter } from "../../packem_shared/abstract-json-reporter.d-wfESoEa-.js";
+import '@visulima/colorize';
+import '@visulima/interactive-manager';
+import "../../packem_shared/index.d-T71KjNAr.js";
 /**
- * Configuration options for the HTTP reporter.
- */
-export 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;
+* 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;
+  /**
+  * 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
+  */
+  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 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
+  */
+  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
- */
-export 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 _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>;
+* 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;
+  protected method: string;
+  protected headers: Record<string, string> | (() => Record<string, string>);
+  protected contentType: string;
+  protected batchContentType: string;
+  protected onError?: (error: Error) => void;
+  protected onDrop?: (droppedCount: number) => void;
+  protected maxQueueSize: number;
+  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);
+  /**
+  * 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());
+  * ```
+  */
+  close(): Promise<void>;
+  /**
+  * 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
+  */
+  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>;
 }
+export { AbstractHttpReporter, AbstractHttpReporterOptions };