vedatrace 0.1.9 → 0.2.1

package/README.md

@@ -72,6 +72,10 @@ const logger = vedatrace({
     mask: '[REDACTED]'
   },
   
+  // Advanced
+  immediateFlush: false,           // Flush on each log (dev mode, edge runtimes)
+  runtime: 'auto',                 // Force runtime: 'node' | 'browser' | 'cloudflare' | 'deno' | 'bun'
+  
   // Callbacks
   onError: (err) => console.error('VedaTrace error:', err),
   onSuccess: () => console.log('Logs sent')
@@ -174,13 +178,15 @@ function MyComponent() {
 ```typescript
 import { vedatrace } from 'vedatrace'
 
+// Works seamlessly - no special configuration needed
+// Timer starts automatically on first log (in handler context)
+const logger = vedatrace({ 
+  apiKey: env.VEDATRACE_API_KEY,
+  service: 'worker'
+})
+
 export default {
   async fetch(req, env, ctx) {
-    const logger = vedatrace({ 
-      apiKey: env.VEDATRACE_API_KEY,
-      service: 'worker'
-    })
-    
     logger.info('Request received', { 
       method: req.method,
       url: req.url 
@@ -194,6 +200,8 @@ export default {
 }
 ```
 
+The SDK automatically detects edge runtimes (Cloudflare Workers, Deno, Bun) and uses lazy timer initialization - the flush timer starts on the first log call, which happens inside your handler where async I/O is allowed.
+
 ## Advanced Usage
 
 ### Custom Transports
@@ -308,6 +316,18 @@ Manually flush pending logs. Returns a Promise.
 
 Stop the background flush timer. Call this for explicit cleanup in long-running processes or before shutdown.
 
+### `logger.start()`
+
+Manually start the flush timer. Usually not needed - the timer starts automatically on first log. Useful if you want to ensure the timer is running before any logs are sent.
+
+### `logger.runtime`
+
+Get the detected runtime environment. Returns: `'node' | 'browser' | 'cloudflare' | 'deno' | 'bun' | 'edge'`
+
+```typescript
+console.log(logger.runtime) // 'cloudflare' when running in Workers
+```
+
 ## License
 
 MIT

package/dist/index.cjs

@@ -5,28 +5,60 @@ Object.defineProperty(exports, '__esModule', { value: true });
 var transports_index = require('./transports/index.cjs');
 
 class VedaTraceBatcher {
-  constructor(transports, config, onError, onSuccess, immediateFlush = false, autoStart = false) {
+  constructor(transports, config, immediateFlush = false) {
     this.transports = transports;
     this.config = config;
-    this.onError = onError;
-    this.onSuccess = onSuccess;
     this.immediateFlush = immediateFlush;
-    if (autoStart && !immediateFlush) {
-      this.startFlushTimer();
-    }
+    this.context = config.executionContext;
   }
   queue = [];
   flushTimer = null;
+  flushDebounceTimer = null;
   isFlushing = false;
   pendingFlush = null;
-  /** Add log to queue */
+  context;
+  /** Attach execution context after initialization */
+  setContext(ctx) {
+    this.context = ctx;
+  }
+  /** Get current context */
+  getContext() {
+    return this.context;
+  }
+  /** Add log to queue with context-aware flush */
   add(log) {
     this.queue.push(log);
-    if (this.immediateFlush || this.queue.length >= this.config.batchSize) {
+    if (!this.flushTimer && !this.immediateFlush) {
+      this.startFlushTimer();
+    }
+    if (this.immediateFlush || this.context) {
+      this.debouncedFlush();
+    } else if (this.queue.length >= this.config.batchSize) {
       this.flush();
     }
   }
-  /** Flush logs to all transports */
+  /** Debounced flush - prevents rapid-fire flushes */
+  debouncedFlush() {
+    if (this.flushDebounceTimer) {
+      clearTimeout(this.flushDebounceTimer);
+    }
+    this.flushDebounceTimer = setTimeout(() => {
+      this.flushDebounceTimer = null;
+      this.flush().catch((error) => {
+        if (this.config.onError) {
+          this.config.onError(
+            error instanceof Error ? error : new Error(String(error))
+          );
+        } else {
+          console.error(
+            "[VedaTrace] Debounced flush error:",
+            error instanceof Error ? error.message : String(error)
+          );
+        }
+      });
+    }, 100);
+  }
+  /** Flush logs to all transports with waitUntil protection */
   async flush() {
     if (this.isFlushing) {
       return this.pendingFlush ?? Promise.resolve();
@@ -37,13 +69,16 @@ class VedaTraceBatcher {
     this.isFlushing = true;
     const logsToSend = [...this.queue];
     this.queue = [];
-    this.pendingFlush = this.sendWithRetry(logsToSend).finally(() => {
+    const flushPromise = this.sendWithRetry(logsToSend).finally(() => {
       this.isFlushing = false;
       this.pendingFlush = null;
     });
-    return this.pendingFlush;
+    this.pendingFlush = flushPromise;
+    if (this.context) {
+      this.context.waitUntil(flushPromise);
+    }
+    return flushPromise;
   }
-  /** Send logs with retry logic */
   async sendWithRetry(logs, attempt = 0) {
     const errors = [];
     for (const transport of this.transports) {
@@ -61,16 +96,17 @@ class VedaTraceBatcher {
       const combinedError = new Error(
         `Failed to send logs after ${this.config.maxRetries} retries: ${errors.map((e) => e.message).join(", ")}`
       );
-      if (this.onError) {
-        this.onError(combinedError);
+      if (this.config.onError) {
+        this.config.onError(combinedError);
       } else {
         console.error("[VedaTrace]", combinedError.message);
       }
       return;
     }
-    this.onSuccess?.();
+    if (this.config.onSuccess) {
+      this.config.onSuccess();
+    }
   }
-  /** Start the flush interval timer */
   startFlushTimer() {
     if (this.flushTimer) {
       clearInterval(this.flushTimer);
@@ -78,8 +114,8 @@ class VedaTraceBatcher {
     this.flushTimer = setInterval(() => {
       if (this.queue.length > 0) {
         this.flush().catch((error) => {
-          if (this.onError) {
-            this.onError(
+          if (this.config.onError) {
+            this.config.onError(
               error instanceof Error ? error : new Error(String(error))
             );
           } else {
@@ -95,63 +131,84 @@ class VedaTraceBatcher {
       this.flushTimer.unref();
     }
   }
-  /** Stop the flush timer */
   stop() {
     if (this.flushTimer) {
       clearInterval(this.flushTimer);
       this.flushTimer = null;
     }
+    if (this.flushDebounceTimer) {
+      clearTimeout(this.flushDebounceTimer);
+      this.flushDebounceTimer = null;
+    }
   }
-  /** Start the flush timer (for manual control in edge runtimes) */
   start() {
     if (!this.flushTimer && !this.immediateFlush) {
       this.startFlushTimer();
     }
   }
-  /** Delay helper */
   delay(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
   }
-  /** Get current queue size */
   getQueueSize() {
     return this.queue.length;
   }
+  setExecutionContext(ctx) {
+    this.context = ctx;
+  }
 }
 
 function detectRuntime() {
-  if (typeof process !== "undefined" && process.versions?.node) {
-    return "node";
-  }
-  if (typeof globalThis !== "undefined" && "navigator" in globalThis && typeof self === "undefined") {
-    return "browser";
-  }
-  if (typeof caches !== "undefined") {
+  if (typeof navigator !== "undefined" && navigator.userAgent === "Cloudflare-Workers") {
     return "cloudflare";
   }
-  const maybeDeno = globalThis;
-  if (maybeDeno?.version) {
+  const g = globalThis;
+  if (g?.Deno && g.Deno.version?.deno) {
     return "deno";
   }
-  const maybeBun = globalThis;
-  if (maybeBun?.Bun) {
+  if (g?.Bun) {
     return "bun";
   }
+  if (typeof g?.WebSocketPair !== "undefined") {
+    return "cloudflare";
+  }
+  if (typeof process !== "undefined" && process.versions?.node) {
+    return "node";
+  }
+  if (typeof window !== "undefined" && typeof document !== "undefined") {
+    return "browser";
+  }
+  if (typeof fetch !== "undefined" && typeof window === "undefined" && typeof process === "undefined") {
+    return "edge";
+  }
   return "edge";
 }
 function isEdgeRuntime() {
   const runtime = detectRuntime();
   return runtime === "cloudflare" || runtime === "deno" || runtime === "bun" || runtime === "edge";
 }
+function isServerless() {
+  const runtime = detectRuntime();
+  return runtime === "cloudflare" || runtime === "edge";
+}
+function isLongRunning() {
+  const runtime = detectRuntime();
+  return runtime === "node" || runtime === "bun" || runtime === "deno";
+}
+function isBrowser() {
+  return detectRuntime() === "browser";
+}
 
-const SDK_VERSION = "1.0.0";
+const SDK_VERSION = process.env.npm_package_version ?? "0.0.0";
 class VedaTraceLogger {
   batcher = null;
   runtime;
   config;
   childDefaults;
+  _context;
   constructor(config = {}, childDefaults = {}) {
     this.runtime = config.runtime ?? detectRuntime();
     this.childDefaults = childDefaults;
+    this._context = config.executionContext;
     this.config = {
       service: config.service,
       apiKey: config.apiKey,
@@ -161,61 +218,68 @@ class VedaTraceLogger {
       flushInterval: config.flushInterval ?? 5e3,
       maxRetries: config.maxRetries ?? 3,
       retryDelay: config.retryDelay ?? 1e3,
-      onError: config.onError,
-      onSuccess: config.onSuccess,
       debug: config.debug ?? false,
       immediateFlush: config.immediateFlush ?? false,
-      unrefTimer: config.unrefTimer
+      unrefTimer: config.unrefTimer ?? false
     };
     if (!config.disabled) {
       this.initializeBatcher(config);
     }
   }
-  /** Initialize the batcher with transports */
   initializeBatcher(config) {
     const transports = config.transports ?? [];
-    if (config.apiKey && transports.length === 0) ;
     if (transports.length > 0) {
+      const batcherConfig = {
+        batchSize: this.config.batchSize,
+        flushInterval: this.config.flushInterval,
+        maxRetries: this.config.maxRetries,
+        retryDelay: this.config.retryDelay,
+        unrefTimer: this.config.unrefTimer,
+        executionContext: this._context,
+        onError: config.onError,
+        onSuccess: config.onSuccess
+      };
       this.batcher = new VedaTraceBatcher(
         transports,
-        {
-          batchSize: this.config.batchSize,
-          flushInterval: this.config.flushInterval,
-          maxRetries: this.config.maxRetries,
-          retryDelay: this.config.retryDelay,
-          unrefTimer: this.config.unrefTimer
-        },
-        this.config.onError,
-        this.config.onSuccess,
+        batcherConfig,
         this.config.immediateFlush
       );
     }
   }
-  /** Set batcher (called from factory function) */
   setBatcher(batcher) {
     this.batcher = batcher;
   }
-  /** Log at debug level */
+  /** Attach execution context for waitUntil support (Cloudflare Workers / Pages) */
+  withContext(ctx) {
+    this._context = ctx;
+    if (this.batcher) {
+      this.batcher.setContext(ctx);
+    }
+    return this;
+  }
+  /** Check if context is attached */
+  hasContext() {
+    return this._context !== void 0;
+  }
+  /** Get current execution context */
+  getContext() {
+    return this._context;
+  }
   debug(message, metadata) {
     this.log("debug", message, metadata);
   }
-  /** Log at info level */
   info(message, metadata) {
     this.log("info", message, metadata);
   }
-  /** Log at warn level */
   warn(message, metadata) {
     this.log("warn", message, metadata);
   }
-  /** Log at error level */
   error(message, metadata) {
     this.log("error", message, metadata);
   }
-  /** Log at fatal level */
   fatal(message, metadata) {
     this.log("fatal", message, metadata);
   }
-  /** Internal log method */
   log(level, message, metadata) {
     if (!this.batcher) {
       return;
@@ -230,7 +294,7 @@ class VedaTraceLogger {
       timestamp: Date.now(),
       metadata: cleanMetadata,
       _sdk: {
-        source: this.detectEnvironment(),
+        source: detectRuntime(),
         version: SDK_VERSION
       }
     };
@@ -243,7 +307,6 @@ class VedaTraceLogger {
     }
     this.batcher.add(logEntry);
   }
-  /** Create a child logger with default metadata */
   child(defaults) {
     const mergedDefaults = { ...this.childDefaults, ...defaults };
     const childLogger = new VedaTraceLogger(
@@ -252,7 +315,8 @@ class VedaTraceLogger {
         apiKey: this.config.apiKey,
         endpoint: this.config.endpoint,
         environment: this.config.environment,
-        disabled: !this.batcher
+        disabled: !this.batcher,
+        executionContext: this._context
       },
       mergedDefaults
     );
@@ -261,33 +325,132 @@ class VedaTraceLogger {
     }
     return childLogger;
   }
-  /** Flush pending logs */
   async flush() {
     if (this.batcher) {
-      await this.batcher.flush();
+      const flushPromise = this.batcher.flush();
+      if (this._context) {
+        this._context.waitUntil(flushPromise);
+      }
+      return flushPromise;
     }
   }
-  /** Stop the batcher and flush timer */
   stop() {
     if (this.batcher) {
       this.batcher.stop();
     }
   }
-  /** Start the flush timer (for manual control in edge runtimes) */
   start() {
     if (this.batcher) {
       this.batcher.start();
     }
   }
-  /** Detect runtime environment (legacy, kept for compatibility) */
-  detectEnvironment() {
-    if (typeof globalThis !== "undefined" && "navigator" in globalThis) {
-      return "browser";
+}
+
+class BrowserLifecycle {
+  constructor(config) {
+    this.config = config;
+    this.boundVisibilityHandler = this.handleVisibilityChange.bind(this);
+    this.boundPageHideHandler = this.handlePageHide.bind(this);
+    this.boundBeforeUnloadHandler = this.handleBeforeUnload.bind(this);
+    this.boundUnloadHandler = this.handleUnload.bind(this);
+  }
+  boundVisibilityHandler;
+  boundPageHideHandler;
+  boundBeforeUnloadHandler;
+  boundUnloadHandler;
+  isAttached = false;
+  pendingFlush = null;
+  /** Start listening for browser lifecycle events */
+  attach() {
+    if (this.isAttached) return;
+    if (typeof document !== "undefined") {
+      document.addEventListener("visibilitychange", this.boundVisibilityHandler);
+      window.addEventListener("pagehide", this.boundPageHideHandler);
+      window.addEventListener("beforeunload", this.boundBeforeUnloadHandler);
+      window.addEventListener("unload", this.boundUnloadHandler);
+    }
+    this.isAttached = true;
+    if (this.config.debug) {
+      console.log("[VedaTrace] Browser lifecycle handlers attached");
+    }
+  }
+  /** Stop listening for browser lifecycle events */
+  detach() {
+    if (!this.isAttached) return;
+    if (typeof document !== "undefined") {
+      document.removeEventListener(
+        "visibilitychange",
+        this.boundVisibilityHandler
+      );
+      window.removeEventListener("pagehide", this.boundPageHideHandler);
+      window.removeEventListener("beforeunload", this.boundBeforeUnloadHandler);
+      window.removeEventListener("unload", this.boundUnloadHandler);
     }
-    if (typeof process !== "undefined" && process.versions?.node) {
-      return "node";
+    this.isAttached = false;
+    if (this.config.debug) {
+      console.log("[VedaTrace] Browser lifecycle handlers detached");
     }
-    return "edge";
+  }
+  /** Handle visibility change - flush when page becomes hidden */
+  handleVisibilityChange() {
+    if (document.visibilityState === "hidden") {
+      if (this.config.debug) {
+        console.log("[VedaTrace] Page became hidden, flushing logs");
+      }
+      this.scheduleFlush();
+    }
+  }
+  /** Handle pagehide event - primary flush handler for Safari */
+  handlePageHide(event) {
+    if (this.config.debug) {
+      console.log(
+        "[VedaTrace] Page hide event",
+        event.persisted ? "(cached)" : "(navigation)"
+      );
+    }
+    if (event.persisted) {
+      this.scheduleFlush();
+    } else {
+      this.finalFlush();
+    }
+  }
+  /** Handle beforeunload - backup flush mechanism */
+  handleBeforeUnload(event) {
+    if (this.config.debug) {
+      console.log("[VedaTrace] Before unload event");
+    }
+    this.finalFlush();
+  }
+  /** Handle unload - fallback for older browsers */
+  handleUnload() {
+    if (this.config.debug) {
+      console.log("[VedaTrace] Unload event");
+    }
+    this.finalFlush();
+  }
+  /** Schedule a debounced flush (for visibility change) */
+  scheduleFlush() {
+    if (this.pendingFlush) return;
+    this.pendingFlush = this.config.flush().finally(() => {
+      this.pendingFlush = null;
+    });
+  }
+  /**
+   * Final flush using keepalive fetch
+   * For sending logs after the page context is destroyed
+   */
+  finalFlush() {
+    for (const transport of this.config.transports) {
+      if (transport.name === "http" && "flush" in transport) {
+        transport.flush?.();
+      }
+    }
+    this.config.flush().catch(() => {
+    });
+  }
+  /** Check if handlers are attached */
+  isActive() {
+    return this.isAttached;
   }
 }
 
@@ -365,31 +528,55 @@ function redactPii(value, mask) {
   return result;
 }
 
+const RUNTIME_FLUSH_INTERVALS = {
+  node: 3e3,
+  bun: 3e3,
+  deno: 3e3,
+  browser: 3e3,
+  cloudflare: 1e3,
+  edge: 1e3
+};
 function vedatrace(config = {}) {
+  const runtime = detectRuntime();
   const logger = new VedaTraceLogger(config);
-  const isEdge = isEdgeRuntime();
-  const shouldImmediateFlush = config.immediateFlush ?? isEdge;
-  const shouldAutoStart = config.autoStart ?? !isEdge;
   if (config.apiKey && (!config.transports || config.transports.length === 0)) {
-    const httpConfig = { apiKey: config.apiKey };
+    const isBrowserEnv = isBrowser();
+    const isServerlessEnv = isServerless();
+    const isLongRunningEnv = isLongRunning();
+    const HttpTransport = isBrowserEnv ? transports_index.VedaTraceHttpTransportBrowser : transports_index.VedaTraceHttpTransport;
+    const httpConfig = {
+      apiKey: config.apiKey,
+      keepalive: isBrowserEnv
+    };
     if (config.endpoint) httpConfig.endpoint = config.endpoint;
-    const httpTransport = new transports_index.VedaTraceHttpTransport(httpConfig);
+    const httpTransport = new HttpTransport(httpConfig);
+    let immediateFlush = config.immediateFlush ?? false;
+    let shouldUnrefTimer = false;
+    if (isServerlessEnv) {
+      immediateFlush = config.immediateFlush ?? !config.executionContext;
+    } else if (isLongRunningEnv) {
+      immediateFlush = config.immediateFlush ?? false;
+      shouldUnrefTimer = true;
+    } else if (isBrowserEnv) {
+      immediateFlush = config.immediateFlush ?? false;
+    }
+    const flushInterval = config.flushInterval ?? RUNTIME_FLUSH_INTERVALS[runtime] ?? 3e3;
     const batcher = new VedaTraceBatcher(
       [httpTransport],
       {
         batchSize: config.batchSize ?? 100,
-        flushInterval: config.flushInterval ?? (isEdge ? 1e3 : 5e3),
+        flushInterval,
         maxRetries: config.maxRetries ?? 3,
         retryDelay: config.retryDelay ?? 1e3,
-        unrefTimer: config.unrefTimer
+        unrefTimer: config.unrefTimer ?? shouldUnrefTimer,
+        executionContext: config.executionContext,
+        onError: config.onError,
+        onSuccess: config.onSuccess
       },
-      config.onError,
-      config.onSuccess,
-      shouldImmediateFlush,
-      shouldAutoStart
+      immediateFlush
     );
     logger.setBatcher(batcher);
-    if (typeof process !== "undefined") {
+    if (typeof process !== "undefined" && isLongRunningEnv) {
       const flushLogs = async () => {
         await batcher.flush();
       };
@@ -397,6 +584,15 @@ function vedatrace(config = {}) {
       process.on("SIGTERM", flushLogs);
       process.on("SIGINT", flushLogs);
     }
+    if (isBrowserEnv) {
+      const lifecycle = new BrowserLifecycle({
+        transports: [httpTransport],
+        flush: () => batcher.flush(),
+        debug: config.debug
+      });
+      lifecycle.attach();
+      logger._lifecycle = lifecycle;
+    }
   }
   return logger;
 }
@@ -415,11 +611,16 @@ function devVedatrace(config = {}) {
 
 exports.VedaTraceConsoleTransport = transports_index.VedaTraceConsoleTransport;
 exports.VedaTraceHttpTransport = transports_index.VedaTraceHttpTransport;
+exports.VedaTraceHttpTransportBrowser = transports_index.VedaTraceHttpTransportBrowser;
+exports.BrowserLifecycle = BrowserLifecycle;
 exports.VedaTraceBatcher = VedaTraceBatcher;
 exports.VedaTraceLogger = VedaTraceLogger;
 exports.default = vedatrace;
 exports.detectRuntime = detectRuntime;
 exports.devVedatrace = devVedatrace;
+exports.isBrowser = isBrowser;
 exports.isEdgeRuntime = isEdgeRuntime;
+exports.isLongRunning = isLongRunning;
+exports.isServerless = isServerless;
 exports.redact = redact;
 exports.vedatrace = vedatrace;