@steve31415/baselib 3.22.0 → 3.24.0

package/dist/log-browser.d.ts

@@ -11,5 +11,24 @@ export interface BrowserLoggerOptions {
     console?: boolean;
 }
 export declare function createBrowserLogger(opts?: BrowserLoggerOptions): Logger;
-/** Route uncaught errors and unhandled rejections into the logger. */
+/**
+ * Make the shared `logger` forward to `instance`. Call once at boot, right
+ * after createBrowserLogger; tests install a recorder.
+ */
+export declare function installBrowserLogger(instance: Logger | null): void;
+/**
+ * The page's logger, importable from any module — no threading a Logger
+ * through props and constructors. It forwards to the instance given to
+ * installBrowserLogger; before that (or in a test that installs none)
+ * events go to the devtools console rather than being lost.
+ */
+export declare const logger: Logger;
+/**
+ * Route uncaught errors, unhandled rejections, and failed resource loads
+ * (`<img>`, `<script>`, `<link>`, media) into the logger. A resource load
+ * failure fires a non-bubbling `error` on its element, which only a
+ * capturing window listener sees; it logs WARN while the browser reports
+ * itself online and INFO while offline (expected then), once per URL per
+ * page so a re-rendering broken element cannot flood the dataset.
+ */
 export declare function installGlobalErrorHandlers(logger: Logger): void;

package/dist/log-browser.js

@@ -31,6 +31,12 @@ export function createBrowserLogger(opts = {}) {
             // remains best-effort, so a browser give-up is only console-noted.
             batchSize: 20,
             fetchInit: { keepalive: true },
+            // Browser logs have no stdout backstop, and the ERRORs most worth
+            // keeping are often the ones an offline stretch causes: while the
+            // browser reports itself offline, failed attempts don't count, so a
+            // batch waits out the outage (until the page dies or the buffer cap
+            // evicts it) instead of being dropped after ~60 s.
+            isOffline: () => navigator.onLine === false,
             onGiveUp: (batch, error, reason) => console.warn(`log ship dropped a batch (${reason}): ${String(error)}`, {
                 batch_id: batch.id,
                 events: batch.events.length,
@@ -66,17 +72,82 @@ export function createBrowserLogger(opts = {}) {
     // Ship what's pending whenever the page may be going away.
     const flushNow = () => void logger.flush();
     addEventListener('pagehide', flushNow);
+    addEventListener('online', () => shipper?.resume());
     document.addEventListener('visibilitychange', () => {
         if (document.visibilityState === 'hidden')
             flushNow();
     });
     return logger;
 }
-/** Route uncaught errors and unhandled rejections into the logger. */
+let installed = null;
+/**
+ * Make the shared `logger` forward to `instance`. Call once at boot, right
+ * after createBrowserLogger; tests install a recorder.
+ */
+export function installBrowserLogger(instance) {
+    installed = instance;
+}
+const CONSOLE_METHOD = { debug: 'debug', info: 'log', warn: 'warn', error: 'error' };
+function forwardingLogger(context) {
+    const emit = (level, message, meta) => {
+        // Resolved per call, so a module-scope `logger.with(...)` taken before
+        // boot still ships once the app installs its logger.
+        if (installed)
+            (context ? installed.with(context) : installed)[level](message, meta);
+        else
+            console[CONSOLE_METHOD[level]](message, meta ?? '');
+    };
+    return {
+        debug: (m, meta) => emit('debug', m, meta),
+        info: (m, meta) => emit('info', m, meta),
+        warn: (m, meta) => emit('warn', m, meta),
+        error: (m, meta) => emit('error', m, meta),
+        with: (extra) => forwardingLogger({ ...context, ...extra }),
+        flush: () => installed?.flush() ?? Promise.resolve(),
+    };
+}
+/**
+ * The page's logger, importable from any module — no threading a Logger
+ * through props and constructors. It forwards to the instance given to
+ * installBrowserLogger; before that (or in a test that installs none)
+ * events go to the devtools console rather than being lost.
+ */
+export const logger = forwardingLogger(undefined);
+const MAX_RESOURCE_URL = 500;
+function resourceUrl(target) {
+    // The resolved (absolute) URL, as the browser requested it.
+    const element = target;
+    const url = element.currentSrc || element.src || element.href || '';
+    return url.length > MAX_RESOURCE_URL ? `${url.slice(0, MAX_RESOURCE_URL)}…` : url;
+}
+/**
+ * Route uncaught errors, unhandled rejections, and failed resource loads
+ * (`<img>`, `<script>`, `<link>`, media) into the logger. A resource load
+ * failure fires a non-bubbling `error` on its element, which only a
+ * capturing window listener sees; it logs WARN while the browser reports
+ * itself online and INFO while offline (expected then), once per URL per
+ * page so a re-rendering broken element cannot flood the dataset.
+ */
 export function installGlobalErrorHandlers(logger) {
+    const failedResources = new Set();
     addEventListener('error', (e) => {
-        logger.error('uncaught error', { error: e.error ?? e.message });
-    });
+        const target = e.target;
+        if (typeof Element !== 'undefined' && target instanceof Element) {
+            const url = resourceUrl(target);
+            if (failedResources.has(url))
+                return;
+            failedResources.add(url);
+            const online = navigator.onLine !== false;
+            logger[online ? 'warn' : 'info']('resource failed to load', {
+                element: target.tagName.toLowerCase(),
+                url,
+                online,
+            });
+            return;
+        }
+        const event = e;
+        logger.error('uncaught error', { error: event.error ?? event.message });
+    }, true);
     addEventListener('unhandledrejection', (e) => {
         logger.error('unhandled rejection', { error: e.reason });
     });

package/dist/log-core.d.ts

@@ -67,6 +67,13 @@ export interface ShipperOptions {
     fetchFn?: typeof fetch;
     /** Extra fetch options (browser sets keepalive). */
     fetchInit?: RequestInit;
+    /** True while the platform knows it has no network (the browser passes
+     *  `navigator.onLine === false`). A failed attempt made while offline says
+     *  nothing about the batch or the ingest service, so it is not counted
+     *  toward maxAttempts and not reported: the batch waits and retries at the
+     *  longest backoff delay, or at once on resume(). The signal only decides
+     *  what a failure means — attempts still run while "offline". */
+    isOffline?: () => boolean;
     /** A delivery attempt failed; the batch will be retried. */
     onAttemptFailure?: (batch: ShippedBatch, error: unknown) => void;
     /** The batch is abandoned — its events will never reach Axiom. */
@@ -101,6 +108,9 @@ export declare class LogShipper {
      *  — raced with one attempt timeout, so it is bounded even when the pump
      *  is busy with older batches. */
     flush(): Promise<void>;
+    /** Retry every waiting batch now, ahead of its backoff — the browser
+     *  calls this when it comes back online. */
+    resume(): void;
     /** Shutdown path: one parallel last-chance attempt for everything
      *  undelivered, then a sweep that marks the rest dropped. Single-flight
      *  while in flight (racing SIGTERM callers join one promise), but re-arms

package/dist/log-core.js

@@ -111,6 +111,13 @@ export class LogShipper {
             return raceTimeout(Promise.allSettled([...this.inflight]), cap);
         return Promise.resolve();
     }
+    /** Retry every waiting batch now, ahead of its backoff — the browser
+     *  calls this when it comes back online. */
+    resume() {
+        for (const b of this.pending)
+            b.nextAttemptAt = 0;
+        void this.pump();
+    }
     /** Shutdown path: one parallel last-chance attempt for everything
      *  undelivered, then a sweep that marks the rest dropped. Single-flight
      *  while in flight (racing SIGTERM callers join one promise), but re-arms
@@ -229,8 +236,15 @@ export class LogShipper {
             batch.attempting = false;
             if (batch.terminal)
                 return;
-            batch.attempt++;
             batch.settleFirst();
+            if (!outcome.ok && !outcome.terminal && this.opts.isOffline?.()) {
+                // Uncounted: the budget is for failures that could be the batch's
+                // or the service's, and an offline failure is neither.
+                batch.nextAttemptAt = Date.now() + this.retryDelaysMs[this.retryDelaysMs.length - 1];
+                this.schedulePump();
+                return;
+            }
+            batch.attempt++;
             if (outcome.ok) {
                 this.remove(batch);
                 if (outcome.failed > 0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steve31415/baselib",
-  "version": "3.22.0",
+  "version": "3.24.0",
   "description": "Plasticine new-world shared platform library: logging, auth, service-to-service auth, db, HTTP, sync, app updates",
   "type": "module",
   "license": "MIT",