vedatrace 0.1.9 → 0.2.0

package/dist/index.d.cts

@@ -1,77 +1,132 @@
-import { b as VedaTraceTransport, B as BatcherConfig, I as InternalLogEntry, V as VedaTraceLoggerInterface, R as RuntimeType$1, a as VedaTraceConfig, L as LogMetadata, c as RedactionConfig } from './types-DUNRMOTv.cjs';
-export { d as VedaTraceLevel, e as VedaTraceLog } from './types-DUNRMOTv.cjs';
-export { ConsoleFormat, ConsoleTransportConfig, HttpTransportConfig, VedaTraceConsoleTransport, VedaTraceHttpTransport } from './transports/index.cjs';
+import { b as VedaTraceTransport, B as BatcherConfig, c as VedaTraceEdgeContext, I as InternalLogEntry, V as VedaTraceLoggerInterface, R as RuntimeType$1, a as VedaTraceConfig, L as LogMetadata, d as RedactionConfig } from './types-BU0UESs9.cjs';
+export { e as VedaTraceLevel, f as VedaTraceLog } from './types-BU0UESs9.cjs';
+export { ConsoleFormat, ConsoleTransportConfig, HttpTransportConfig, VedaTraceConsoleTransport, VedaTraceHttpTransport, VedaTraceHttpTransportBrowser } from './transports/index.cjs';
 
 /**
- * Log batcher with background flushing
- * Handles queueing, batching, and retry logic
+ * VedaTrace Batcher - Context-Aware for Cloudflare Workers
+ *
+ * Key features:
+ * 1. Stores EdgeContext for waitUntil() integration
+ * 2. setContext() method for post-initialization context attachment
+ * 3. Fire-and-forget flush wrapped in ctx.waitUntil() when context is available
+ * 4. Debounced flush to avoid excessive network calls
+ * 5. Automatic flush on each log entry when context is present
+ * 6. All callbacks moved into BatcherConfig for cleaner API
  */
 
 declare class VedaTraceBatcher {
     private transports;
     private config;
-    private onError?;
-    private onSuccess?;
     private immediateFlush;
     private queue;
     private flushTimer;
+    private flushDebounceTimer;
     private isFlushing;
     private pendingFlush;
-    constructor(transports: VedaTraceTransport[], config: BatcherConfig, onError?: ((error: Error) => void) | undefined, onSuccess?: (() => void) | undefined, immediateFlush?: boolean, autoStart?: boolean);
-    /** Add log to queue */
+    private context;
+    constructor(transports: VedaTraceTransport[], config: BatcherConfig, immediateFlush?: boolean);
+    /** Attach execution context after initialization */
+    setContext(ctx: VedaTraceEdgeContext): void;
+    /** Get current context */
+    getContext(): VedaTraceEdgeContext | undefined;
+    /** Add log to queue with context-aware flush */
     add(log: InternalLogEntry): void;
-    /** Flush logs to all transports */
+    /** Debounced flush - prevents rapid-fire flushes */
+    private debouncedFlush;
+    /** Flush logs to all transports with waitUntil protection */
     flush(): Promise<void>;
-    /** Send logs with retry logic */
     private sendWithRetry;
-    /** Start the flush interval timer */
     private startFlushTimer;
-    /** Stop the flush timer */
     stop(): void;
-    /** Start the flush timer (for manual control in edge runtimes) */
     start(): void;
-    /** Delay helper */
     private delay;
-    /** Get current queue size */
     getQueueSize(): number;
+    setExecutionContext(ctx: VedaTraceEdgeContext): void;
 }
 
 /**
  * Core VedaTrace Logger implementation
+ * Supports Cloudflare Workers / Pages via withContext() integration
  */
 
 declare class VedaTraceLogger implements VedaTraceLoggerInterface {
     private batcher;
     runtime: RuntimeType$1;
     private config;
-    private childDefaults;
+    private readonly childDefaults;
+    private _context;
     constructor(config?: VedaTraceConfig, childDefaults?: LogMetadata);
-    /** Initialize the batcher with transports */
     private initializeBatcher;
-    /** Set batcher (called from factory function) */
     setBatcher(batcher: VedaTraceBatcher): void;
-    /** Log at debug level */
+    /** Attach execution context for waitUntil support (Cloudflare Workers / Pages) */
+    withContext(ctx: VedaTraceEdgeContext): this;
+    /** Check if context is attached */
+    hasContext(): boolean;
+    /** Get current execution context */
+    getContext(): VedaTraceEdgeContext | undefined;
     debug(message: string, metadata?: LogMetadata): void;
-    /** Log at info level */
     info(message: string, metadata?: LogMetadata): void;
-    /** Log at warn level */
     warn(message: string, metadata?: LogMetadata): void;
-    /** Log at error level */
     error(message: string | Error, metadata?: LogMetadata): void;
-    /** Log at fatal level */
     fatal(message: string | Error, metadata?: LogMetadata): void;
-    /** Internal log method */
     private log;
-    /** Create a child logger with default metadata */
     child(defaults: LogMetadata): VedaTraceLoggerInterface;
-    /** Flush pending logs */
     flush(): Promise<void>;
-    /** Stop the batcher and flush timer */
     stop(): void;
-    /** Start the flush timer (for manual control in edge runtimes) */
     start(): void;
-    /** Detect runtime environment (legacy, kept for compatibility) */
-    private detectEnvironment;
+}
+
+/**
+ * Browser lifecycle management for VedaTrace
+ *
+ * Handles:
+ * - visibilitychange: flush when page becomes hidden
+ * - pagehide: final flush when user leaves the page
+ * - beforeunload: backup flush before page unload
+ *
+ * Uses fetch with keepalive: true for final flush to ensure
+ * the request completes after the tab is closed.
+ */
+
+interface BrowserLifecycleConfig {
+    transports: VedaTraceTransport[];
+    flush(): Promise<void>;
+    debug?: boolean;
+}
+/**
+ * Browser lifecycle manager
+ * Attaches event listeners and handles graceful flush on page exit
+ */
+declare class BrowserLifecycle {
+    private config;
+    private boundVisibilityHandler;
+    private boundPageHideHandler;
+    private boundBeforeUnloadHandler;
+    private boundUnloadHandler;
+    private isAttached;
+    private pendingFlush;
+    constructor(config: BrowserLifecycleConfig);
+    /** Start listening for browser lifecycle events */
+    attach(): void;
+    /** Stop listening for browser lifecycle events */
+    detach(): void;
+    /** Handle visibility change - flush when page becomes hidden */
+    private handleVisibilityChange;
+    /** Handle pagehide event - primary flush handler for Safari */
+    private handlePageHide;
+    /** Handle beforeunload - backup flush mechanism */
+    private handleBeforeUnload;
+    /** Handle unload - fallback for older browsers */
+    private handleUnload;
+    /** Schedule a debounced flush (for visibility change) */
+    private scheduleFlush;
+    /**
+     * Final flush using keepalive fetch
+     * For sending logs after the page context is destroyed
+     */
+    private finalFlush;
+    /** Check if handlers are attached */
+    isActive(): boolean;
 }
 
 /**
@@ -83,46 +138,55 @@ declare class VedaTraceLogger implements VedaTraceLoggerInterface {
  */
 declare function redact(obj: unknown, config?: RedactionConfig): unknown;
 
+type RuntimeType = "node" | "browser" | "cloudflare" | "deno" | "bun" | "edge";
 /**
  * Runtime environment detection utility
  * Detects Node.js, Browser, Cloudflare Workers, Deno, Bun
  */
-type RuntimeType = "node" | "browser" | "cloudflare" | "deno" | "bun" | "edge";
 declare function detectRuntime(): RuntimeType;
 declare function isEdgeRuntime(): boolean;
+declare function isServerless(): boolean;
+declare function isLongRunning(): boolean;
+declare function isBrowser(): boolean;
 
 /**
  * VedaTrace SDK - Universal JavaScript logging
  *
- * Import examples:
- * import { vedatrace } from 'vedatrace'
- * import { VedaTraceHttpTransport } from 'vedatrace/transports'
- * import { vedaTraceMiddleware } from 'vedatrace/express'
+ * Supports all JavaScript environments:
+ * - Cloudflare Workers / Pages: waitUntil() for background flush
+ * - Node.js: standard batching with process event handlers
+ * - Bun: standard batching with unref timers
+ * - Deno: standard batching with unref timers
+ * - Browser: batching with visibility lifecycle handling
+ * - Generic Edge: immediate flush fallback
+ *
+ * @example
+ * // Cloudflare Worker
+ * const logger = vedatrace({ apiKey: 'key', service: 'app' }).withContext(ctx)
+ *
+ * @example
+ * // Node.js / Express
+ * const logger = vedatrace({ apiKey: 'key', service: 'app' })
+ * // Automatic shutdown handlers via process.on()
+ *
+ * @example
+ * // Browser
+ * const logger = vedatrace({ apiKey: 'key', service: 'app' })
+ * // Automatic flush on visibilitychange / pagehide
  */
 
 /**
  * Create a VedaTrace logger instance
  *
- * @example
- * ```typescript
- * const logger = vedatrace({
- *   apiKey: 'your-api-key',
- *   service: 'my-service'
- * })
- *
- * logger.info('Hello world')
- * logger.error('Something went wrong', { error: err })
- * ```
+ * Handles all runtimes with environment-appropriate strategies:
+ * 1. Cloudflare/Edge: immediate flush with waitUntil if context available
+ * 2. Node/Bun/Deno: standard batching with process/unref timers
+ * 3. Browser: batching with visibility lifecycle handlers
  */
 declare function vedatrace(config?: VedaTraceConfig): VedaTraceLoggerInterface;
 /**
  * Create a console-only logger for development
- *
- * @example
- * ```typescript
- * const logger = devVedatrace({ service: 'my-service' })
- * ```
  */
 declare function devVedatrace(config?: Omit<VedaTraceConfig, "apiKey" | "transports">): VedaTraceLoggerInterface;
 
-export { BatcherConfig, InternalLogEntry, LogMetadata, RedactionConfig, RuntimeType$1 as RuntimeType, VedaTraceBatcher, VedaTraceConfig, VedaTraceLogger, VedaTraceLoggerInterface, VedaTraceTransport, vedatrace as default, detectRuntime, devVedatrace, isEdgeRuntime, redact, vedatrace };
+export { BatcherConfig, BrowserLifecycle, InternalLogEntry, LogMetadata, RedactionConfig, RuntimeType$1 as RuntimeType, VedaTraceBatcher, VedaTraceConfig, VedaTraceEdgeContext, VedaTraceLogger, VedaTraceLoggerInterface, VedaTraceTransport, vedatrace as default, detectRuntime, devVedatrace, isBrowser, isEdgeRuntime, isLongRunning, isServerless, redact, vedatrace };

package/dist/index.d.mts

@@ -1,77 +1,132 @@
-import { b as VedaTraceTransport, B as BatcherConfig, I as InternalLogEntry, V as VedaTraceLoggerInterface, R as RuntimeType$1, a as VedaTraceConfig, L as LogMetadata, c as RedactionConfig } from './types-DUNRMOTv.mjs';
-export { d as VedaTraceLevel, e as VedaTraceLog } from './types-DUNRMOTv.mjs';
-export { ConsoleFormat, ConsoleTransportConfig, HttpTransportConfig, VedaTraceConsoleTransport, VedaTraceHttpTransport } from './transports/index.mjs';
+import { b as VedaTraceTransport, B as BatcherConfig, c as VedaTraceEdgeContext, I as InternalLogEntry, V as VedaTraceLoggerInterface, R as RuntimeType$1, a as VedaTraceConfig, L as LogMetadata, d as RedactionConfig } from './types-BU0UESs9.mjs';
+export { e as VedaTraceLevel, f as VedaTraceLog } from './types-BU0UESs9.mjs';
+export { ConsoleFormat, ConsoleTransportConfig, HttpTransportConfig, VedaTraceConsoleTransport, VedaTraceHttpTransport, VedaTraceHttpTransportBrowser } from './transports/index.mjs';
 
 /**
- * Log batcher with background flushing
- * Handles queueing, batching, and retry logic
+ * VedaTrace Batcher - Context-Aware for Cloudflare Workers
+ *
+ * Key features:
+ * 1. Stores EdgeContext for waitUntil() integration
+ * 2. setContext() method for post-initialization context attachment
+ * 3. Fire-and-forget flush wrapped in ctx.waitUntil() when context is available
+ * 4. Debounced flush to avoid excessive network calls
+ * 5. Automatic flush on each log entry when context is present
+ * 6. All callbacks moved into BatcherConfig for cleaner API
  */
 
 declare class VedaTraceBatcher {
     private transports;
     private config;
-    private onError?;
-    private onSuccess?;
     private immediateFlush;
     private queue;
     private flushTimer;
+    private flushDebounceTimer;
     private isFlushing;
     private pendingFlush;
-    constructor(transports: VedaTraceTransport[], config: BatcherConfig, onError?: ((error: Error) => void) | undefined, onSuccess?: (() => void) | undefined, immediateFlush?: boolean, autoStart?: boolean);
-    /** Add log to queue */
+    private context;
+    constructor(transports: VedaTraceTransport[], config: BatcherConfig, immediateFlush?: boolean);
+    /** Attach execution context after initialization */
+    setContext(ctx: VedaTraceEdgeContext): void;
+    /** Get current context */
+    getContext(): VedaTraceEdgeContext | undefined;
+    /** Add log to queue with context-aware flush */
     add(log: InternalLogEntry): void;
-    /** Flush logs to all transports */
+    /** Debounced flush - prevents rapid-fire flushes */
+    private debouncedFlush;
+    /** Flush logs to all transports with waitUntil protection */
     flush(): Promise<void>;
-    /** Send logs with retry logic */
     private sendWithRetry;
-    /** Start the flush interval timer */
     private startFlushTimer;
-    /** Stop the flush timer */
     stop(): void;
-    /** Start the flush timer (for manual control in edge runtimes) */
     start(): void;
-    /** Delay helper */
     private delay;
-    /** Get current queue size */
     getQueueSize(): number;
+    setExecutionContext(ctx: VedaTraceEdgeContext): void;
 }
 
 /**
  * Core VedaTrace Logger implementation
+ * Supports Cloudflare Workers / Pages via withContext() integration
  */
 
 declare class VedaTraceLogger implements VedaTraceLoggerInterface {
     private batcher;
     runtime: RuntimeType$1;
     private config;
-    private childDefaults;
+    private readonly childDefaults;
+    private _context;
     constructor(config?: VedaTraceConfig, childDefaults?: LogMetadata);
-    /** Initialize the batcher with transports */
     private initializeBatcher;
-    /** Set batcher (called from factory function) */
     setBatcher(batcher: VedaTraceBatcher): void;
-    /** Log at debug level */
+    /** Attach execution context for waitUntil support (Cloudflare Workers / Pages) */
+    withContext(ctx: VedaTraceEdgeContext): this;
+    /** Check if context is attached */
+    hasContext(): boolean;
+    /** Get current execution context */
+    getContext(): VedaTraceEdgeContext | undefined;
     debug(message: string, metadata?: LogMetadata): void;
-    /** Log at info level */
     info(message: string, metadata?: LogMetadata): void;
-    /** Log at warn level */
     warn(message: string, metadata?: LogMetadata): void;
-    /** Log at error level */
     error(message: string | Error, metadata?: LogMetadata): void;
-    /** Log at fatal level */
     fatal(message: string | Error, metadata?: LogMetadata): void;
-    /** Internal log method */
     private log;
-    /** Create a child logger with default metadata */
     child(defaults: LogMetadata): VedaTraceLoggerInterface;
-    /** Flush pending logs */
     flush(): Promise<void>;
-    /** Stop the batcher and flush timer */
     stop(): void;
-    /** Start the flush timer (for manual control in edge runtimes) */
     start(): void;
-    /** Detect runtime environment (legacy, kept for compatibility) */
-    private detectEnvironment;
+}
+
+/**
+ * Browser lifecycle management for VedaTrace
+ *
+ * Handles:
+ * - visibilitychange: flush when page becomes hidden
+ * - pagehide: final flush when user leaves the page
+ * - beforeunload: backup flush before page unload
+ *
+ * Uses fetch with keepalive: true for final flush to ensure
+ * the request completes after the tab is closed.
+ */
+
+interface BrowserLifecycleConfig {
+    transports: VedaTraceTransport[];
+    flush(): Promise<void>;
+    debug?: boolean;
+}
+/**
+ * Browser lifecycle manager
+ * Attaches event listeners and handles graceful flush on page exit
+ */
+declare class BrowserLifecycle {
+    private config;
+    private boundVisibilityHandler;
+    private boundPageHideHandler;
+    private boundBeforeUnloadHandler;
+    private boundUnloadHandler;
+    private isAttached;
+    private pendingFlush;
+    constructor(config: BrowserLifecycleConfig);
+    /** Start listening for browser lifecycle events */
+    attach(): void;
+    /** Stop listening for browser lifecycle events */
+    detach(): void;
+    /** Handle visibility change - flush when page becomes hidden */
+    private handleVisibilityChange;
+    /** Handle pagehide event - primary flush handler for Safari */
+    private handlePageHide;
+    /** Handle beforeunload - backup flush mechanism */
+    private handleBeforeUnload;
+    /** Handle unload - fallback for older browsers */
+    private handleUnload;
+    /** Schedule a debounced flush (for visibility change) */
+    private scheduleFlush;
+    /**
+     * Final flush using keepalive fetch
+     * For sending logs after the page context is destroyed
+     */
+    private finalFlush;
+    /** Check if handlers are attached */
+    isActive(): boolean;
 }
 
 /**
@@ -83,46 +138,55 @@ declare class VedaTraceLogger implements VedaTraceLoggerInterface {
  */
 declare function redact(obj: unknown, config?: RedactionConfig): unknown;
 
+type RuntimeType = "node" | "browser" | "cloudflare" | "deno" | "bun" | "edge";
 /**
  * Runtime environment detection utility
  * Detects Node.js, Browser, Cloudflare Workers, Deno, Bun
  */
-type RuntimeType = "node" | "browser" | "cloudflare" | "deno" | "bun" | "edge";
 declare function detectRuntime(): RuntimeType;
 declare function isEdgeRuntime(): boolean;
+declare function isServerless(): boolean;
+declare function isLongRunning(): boolean;
+declare function isBrowser(): boolean;
 
 /**
  * VedaTrace SDK - Universal JavaScript logging
  *
- * Import examples:
- * import { vedatrace } from 'vedatrace'
- * import { VedaTraceHttpTransport } from 'vedatrace/transports'
- * import { vedaTraceMiddleware } from 'vedatrace/express'
+ * Supports all JavaScript environments:
+ * - Cloudflare Workers / Pages: waitUntil() for background flush
+ * - Node.js: standard batching with process event handlers
+ * - Bun: standard batching with unref timers
+ * - Deno: standard batching with unref timers
+ * - Browser: batching with visibility lifecycle handling
+ * - Generic Edge: immediate flush fallback
+ *
+ * @example
+ * // Cloudflare Worker
+ * const logger = vedatrace({ apiKey: 'key', service: 'app' }).withContext(ctx)
+ *
+ * @example
+ * // Node.js / Express
+ * const logger = vedatrace({ apiKey: 'key', service: 'app' })
+ * // Automatic shutdown handlers via process.on()
+ *
+ * @example
+ * // Browser
+ * const logger = vedatrace({ apiKey: 'key', service: 'app' })
+ * // Automatic flush on visibilitychange / pagehide
  */
 
 /**
  * Create a VedaTrace logger instance
  *
- * @example
- * ```typescript
- * const logger = vedatrace({
- *   apiKey: 'your-api-key',
- *   service: 'my-service'
- * })
- *
- * logger.info('Hello world')
- * logger.error('Something went wrong', { error: err })
- * ```
+ * Handles all runtimes with environment-appropriate strategies:
+ * 1. Cloudflare/Edge: immediate flush with waitUntil if context available
+ * 2. Node/Bun/Deno: standard batching with process/unref timers
+ * 3. Browser: batching with visibility lifecycle handlers
  */
 declare function vedatrace(config?: VedaTraceConfig): VedaTraceLoggerInterface;
 /**
  * Create a console-only logger for development
- *
- * @example
- * ```typescript
- * const logger = devVedatrace({ service: 'my-service' })
- * ```
  */
 declare function devVedatrace(config?: Omit<VedaTraceConfig, "apiKey" | "transports">): VedaTraceLoggerInterface;
 
-export { BatcherConfig, InternalLogEntry, LogMetadata, RedactionConfig, RuntimeType$1 as RuntimeType, VedaTraceBatcher, VedaTraceConfig, VedaTraceLogger, VedaTraceLoggerInterface, VedaTraceTransport, vedatrace as default, detectRuntime, devVedatrace, isEdgeRuntime, redact, vedatrace };
+export { BatcherConfig, BrowserLifecycle, InternalLogEntry, LogMetadata, RedactionConfig, RuntimeType$1 as RuntimeType, VedaTraceBatcher, VedaTraceConfig, VedaTraceEdgeContext, VedaTraceLogger, VedaTraceLoggerInterface, VedaTraceTransport, vedatrace as default, detectRuntime, devVedatrace, isBrowser, isEdgeRuntime, isLongRunning, isServerless, redact, vedatrace };