@logbrew/sdk 0.1.38 → 0.1.39

package/browser-breadcrumbs.cjs

@@ -1,196 +1,406 @@
 "use strict";
 
+/**
+ * @import { IssueBreadcrumbLevel } from "./index.cjs"
+ */
+
+/**
+ * @typedef {Readonly<{
+ *   category: string;
+ *   data?: Readonly<Record<string, number | string>>;
+ *   level?: IssueBreadcrumbLevel;
+ *   message?: string;
+ *   type: string;
+ * }>} BrowserBreadcrumb
+ * @typedef {(breadcrumb: BrowserBreadcrumb) => boolean} AddBreadcrumb
+ * @typedef {() => void} Restore
+ * @typedef {(this: unknown, ...args: readonly unknown[]) => unknown} ObservedMethod
+ * @typedef {Readonly<{ method: string; url: string | undefined }>} HttpRequest
+ * @typedef {Readonly<{ method?: unknown; url?: unknown }> | undefined} FetchInput
+ * @typedef {Readonly<{ method?: unknown }> | undefined} FetchInit
+ * @typedef {Readonly<{ status?: unknown }> | undefined} FetchResponse
+ * @typedef {(this: unknown, input: FetchInput, init: FetchInit) => Promise<FetchResponse>} FetchMethod
+ * @typedef {Readonly<{
+ *   addEventListener?: (type: string, listener: () => void) => unknown;
+ *   status?: unknown;
+ * }>} XhrInstance
+ * @typedef {(this: XhrInstance, method: unknown, url: unknown, ...rest: readonly unknown[]) => unknown} XhrOpen
+ * @typedef {(this: XhrInstance, ...args: readonly unknown[]) => unknown} XhrSend
+ * @typedef {Readonly<{ open?: XhrOpen; send?: XhrSend }>} XhrPrototype
+ * @typedef {"debug" | "error" | "info" | "log" | "warn"} ConsoleMethod
+ * @typedef {Readonly<Partial<Record<ConsoleMethod, ObservedMethod>>>} BrowserConsole
+ * @typedef {Readonly<{ pushState?: ObservedMethod; replaceState?: ObservedMethod }>} BrowserHistory
+ * @typedef {Readonly<{
+ *   addEventListener?: (type: string, listener: () => void) => unknown;
+ *   console?: BrowserConsole;
+ *   fetch?: FetchMethod;
+ *   history?: BrowserHistory;
+ *   location?: Readonly<{ href?: unknown; pathname?: unknown }>;
+ *   removeEventListener?: (type: string, listener: () => void) => unknown;
+ *   XMLHttpRequest?: Readonly<{ prototype?: XhrPrototype }>;
+ * }>} BrowserWindow
+ * @typedef {Readonly<{ addBreadcrumb: (breadcrumb: BrowserBreadcrumb) => unknown }>} BreadcrumbClient
+ * @typedef {Readonly<{
+ *   console?: boolean;
+ *   ignoredUrls?: readonly unknown[];
+ *   navigation?: boolean;
+ *   network?: boolean;
+ * }>} BrowserBreadcrumbOptions
+ */
+
 const MAX_MESSAGE_LENGTH = 512;
 const MAX_URL_LENGTH = 256;
-const CONSOLE_LEVELS = Object.freeze({
-  debug: "debug",
-  error: "error",
-  info: "info",
-  log: "info",
-  warn: "warning"
-});
-
-// Records console calls, fetch and XHR requests, and route changes as issue breadcrumbs.
-// Browser-safe and shared by @logbrew/browser and @logbrew/next/client. Returns an uninstall function
-// that puts back every patched method it still owns.
-function installBrowserBreadcrumbs(browserWindow, client, {
-  console: captureConsole = true,
-  ignoredUrls = [],
-  navigation = true,
-  network = true
-} = {}) {
-  const ignored = new Set(ignoredUrls.map((url) => sanitizeUrl(url, browserWindow)).filter(Boolean));
-  const add = (breadcrumb) => {
-    try {
-      client.addBreadcrumb(breadcrumb);
-    } catch {
-      // Breadcrumbs are advisory and never reach application code.
-    }
-  };
-  const restores = [];
-  if (captureConsole) {
-    restores.push(...patchConsole(browserWindow.console ?? globalThis.console, add));
+const MAX_METHOD_LENGTH = 16;
+const TEXT_START = 0;
+const FIRST_RESTORE = 0;
+const NO_STATUS = 0;
+const CLIENT_ERROR_STATUS = 400;
+const SERVER_ERROR_STATUS = 500;
+const LAST_C0_CONTROL = 31;
+const FIRST_C1_CONTROL = 127;
+const LAST_C1_CONTROL = 159;
+const WHITESPACE_PATTERN = /\s+/gu;
+/** @type {ReadonlyMap<ConsoleMethod, IssueBreadcrumbLevel>} */
+const CONSOLE_LEVELS = new Map([
+  ["debug", "debug"],
+  ["error", "error"],
+  ["info", "info"],
+  ["log", "info"],
+  ["warn", "warning"]
+]);
+/** @type {readonly (keyof BrowserHistory)[]} */
+const NAVIGATION_METHODS = ["pushState", "replaceState"];
+
+/** @type {(value: unknown) => string} */
+const text = String;
+
+/**
+ * @param {unknown} value
+ * @param {number} limit
+ * @returns {string}
+ */
+function boundedText(value, limit) {
+  const characters = Array.from(text(value), (character) => {
+    const code = character.codePointAt(TEXT_START);
+    return code !== undefined && (code <= LAST_C0_CONTROL || (code >= FIRST_C1_CONTROL && code <= LAST_C1_CONTROL))
+      ? " "
+      : character;
+  });
+  return [...characters.join("").replaceAll(WHITESPACE_PATTERN, " ").trim()].slice(TEXT_START, limit).join("");
+}
+
+/**
+ * @param {unknown} value
+ * @param {BrowserWindow} browserWindow
+ * @returns {string | undefined}
+ */
+function sanitizeUrl(value, browserWindow) {
+  if (value === undefined || value === null) {
+    return undefined;
   }
-  if (network) {
-    restores.push(...patchFetch(browserWindow, add, ignored), ...patchXhr(browserWindow, add, ignored));
+  try {
+    const url = new URL(text(value), text(browserWindow.location?.href ?? "http://localhost/"));
+    const sanitized = boundedText(`${url.protocol}//${url.host}${url.pathname}`, MAX_URL_LENGTH);
+    return sanitized === "" ? undefined : sanitized;
+  } catch {
+    return undefined;
   }
-  if (navigation) {
-    restores.push(...patchNavigation(browserWindow, add));
+}
+
+/**
+ * @param {BrowserWindow} browserWindow
+ * @returns {string | undefined}
+ */
+function currentPath(browserWindow) {
+  const pathname = browserWindow.location?.pathname;
+  return typeof pathname === "string" ? boundedText(pathname, MAX_URL_LENGTH) : undefined;
+}
+
+/**
+ * @param {Readonly<Error>} error
+ * @returns {string}
+ */
+function errorName(error) {
+  if (error.name) {
+    return error.name;
   }
-  return () => {
-    for (const restore of restores.splice(0).reverse()) {
-      restore();
+  return "Error";
+}
+
+/**
+ * @param {readonly unknown[]} args
+ * @returns {string}
+ */
+function consoleTemplate(args) {
+  const [first] = args;
+  if (typeof first === "string") {
+    return first;
+  }
+  return first instanceof Error ? errorName(first) : "";
+}
+
+/**
+ * @param {number | undefined} statusCode
+ * @returns {IssueBreadcrumbLevel}
+ */
+function httpLevel(statusCode) {
+  if (statusCode === undefined || statusCode < CLIENT_ERROR_STATUS) {
+    return "info";
+  }
+  return statusCode >= SERVER_ERROR_STATUS ? "error" : "warning";
+}
+
+/**
+ * @param {string} category
+ * @param {HttpRequest} request
+ * @param {unknown} [status]
+ * @returns {BrowserBreadcrumb}
+ */
+function httpBreadcrumb(category, request, status) {
+  const statusCode = typeof status === "number" && Number.isInteger(status) && status > NO_STATUS ? status : undefined;
+  const method = request.method.slice(TEXT_START, MAX_METHOD_LENGTH);
+  return {
+    type: "http",
+
+    category,
+    level: httpLevel(statusCode),
+
+    data: {
+      method: method === "" ? "GET" : method,
+      ...(request.url === undefined ? {} : { url: request.url }),
+      ...(statusCode === undefined ? {} : { status_code: statusCode })
     }
   };
 }
 
+/**
+ * @template {object} Target
+ * @template {keyof Target & string} Name
+ * @param {Target | undefined} target
+ * @param {Name} name
+ * @param {(original: NonNullable<Target[Name]>) => NonNullable<Target[Name]>} wrap
+ * @returns {Restore[]}
+ */
+function replaceMethod(target, name, wrap) {
+  const original = target?.[name];
+  if (target === undefined || typeof original !== "function") {
+    return [];
+  }
+  const replacement = wrap(original);
+  Object.assign(target, { [name]: replacement });
+  return [
+    () => {
+      if (target[name] === replacement) {
+        Object.assign(target, { [name]: original });
+      }
+    }
+  ];
+}
+
+/**
+ * @param {BrowserConsole | undefined} target
+ * @param {AddBreadcrumb} add
+ * @returns {Restore[]}
+ */
 function patchConsole(target, add) {
   if (!target) {
     return [];
   }
-  return Object.entries(CONSOLE_LEVELS).flatMap(([method, level]) => replaceMethod(target, method, (original) => (
-    /** @this {Console} */
-    function logBrewConsoleBreadcrumb(...args) {
-      const message = boundedText(consoleTemplate(args), MAX_MESSAGE_LENGTH);
-      if (message) {
-        add({ type: "debug", category: "console", level, message });
+  /** @type {Restore[]} */
+  const restores = [];
+  for (const [method, level] of CONSOLE_LEVELS) {
+    restores.push(...replaceMethod(target, method, (original) => (
+      /**
+       * @this {unknown}
+       * @param {readonly unknown[]} args
+       * @returns {unknown}
+       */
+      function logBrewConsoleBreadcrumb(...args) {
+        const message = boundedText(consoleTemplate(args), MAX_MESSAGE_LENGTH);
+        if (message) {
+          add({
+            type: "debug",
+
+            category: "console",
+            level,
+            message
+          });
+        }
+        return Reflect.apply(original, this, args);
       }
-      return original.apply(this, args);
-    }
-  )));
+    )));
+  }
+  return restores;
 }
 
+/**
+ * @param {BrowserWindow} browserWindow
+ * @param {AddBreadcrumb} add
+ * @param {Readonly<ReadonlySet<string | undefined>>} ignored
+ * @returns {Restore[]}
+ */
 function patchFetch(browserWindow, add, ignored) {
-  return replaceMethod(browserWindow, "fetch", (original) => /** @this {*} */ async function logBrewFetchBreadcrumb(input, init) {
-    const method = String(init?.method ?? input?.method ?? "GET").toUpperCase();
-    const url = sanitizeUrl(typeof input === "string" || input instanceof URL ? input : input?.url, browserWindow);
-    try {
-      const response = await original.call(this, input, init);
-      if (!ignored.has(url)) {
-        add(httpBreadcrumb("fetch", method, url, response?.status));
+  return replaceMethod(browserWindow, "fetch", (original) => (
+    /**
+     * @this {unknown}
+     * @param {FetchInput} input
+     * @param {FetchInit} init
+     * @returns {Promise<FetchResponse>}
+     */
+    async function logBrewFetchBreadcrumb(input, init) {
+      const request = {
+        method: text(init?.method ?? input?.method ?? "GET").toUpperCase(),
+        url: sanitizeUrl(typeof input === "string" || input instanceof URL ? input : input?.url, browserWindow)
+      };
+      try {
+        const response = await original.call(this, input, init);
+        if (!ignored.has(request.url)) {
+          add(httpBreadcrumb("fetch", request, response?.status));
+        }
+        return response;
+      } catch (error) {
+        if (!ignored.has(request.url)) {
+          add({ ...httpBreadcrumb("fetch", request), level: "error" });
+        }
+        throw error;
       }
-      return response;
-    } catch (error) {
-      if (!ignored.has(url)) {
-        add({ ...httpBreadcrumb("fetch", method, url), level: "error" });
-      }
-      throw error;
     }
-  });
+  ));
 }
 
+/**
+ * @param {BrowserWindow} browserWindow
+ * @param {AddBreadcrumb} add
+ * @param {Readonly<ReadonlySet<string | undefined>>} ignored
+ * @returns {Restore[]}
+ */
 function patchXhr(browserWindow, add, ignored) {
   const prototype = browserWindow.XMLHttpRequest?.prototype;
   if (!prototype) {
     return [];
   }
+  /** @type {WeakMap<XhrInstance, HttpRequest>} */
   const state = new WeakMap();
   return [
-    ...replaceMethod(prototype, "open", (original) => /** @this {XMLHttpRequest} */ function logBrewXhrOpen(method, url, ...rest) {
-      state.set(this, { method: String(method ?? "GET").toUpperCase(), url: sanitizeUrl(url, browserWindow) });
-      return original.call(this, method, url, ...rest);
-    }),
-    ...replaceMethod(prototype, "send", (original) => /** @this {XMLHttpRequest} */ function logBrewXhrSend(...args) {
-      const request = state.get(this);
-      if (request && !ignored.has(request.url) && typeof this.addEventListener === "function") {
-        this.addEventListener("loadend", () => {
-          add(httpBreadcrumb("xhr", request.method, request.url, this.status || undefined));
-        });
+    ...replaceMethod(prototype, "open", (original) => (
+      /**
+       * @this {XhrInstance}
+       * @param {unknown} method
+       * @param {unknown} url
+       * @param {readonly unknown[]} rest
+       * @returns {unknown}
+       */
+      function logBrewXhrOpen(method, url, ...rest) {
+        state.set(this, { method: text(method ?? "GET").toUpperCase(), url: sanitizeUrl(url, browserWindow) });
+        return original.call(this, method, url, ...rest);
       }
-      return original.apply(this, args);
-    })
+    )),
+    ...replaceMethod(prototype, "send", (original) => (
+      /**
+       * @this {XhrInstance}
+       * @param {readonly unknown[]} args
+       * @returns {unknown}
+       */
+      function logBrewXhrSend(...args) {
+        const request = state.get(this);
+        if (request && !ignored.has(request.url) && typeof this.addEventListener === "function") {
+          this.addEventListener("loadend", () => {
+            add(httpBreadcrumb("xhr", request, this.status));
+          });
+        }
+        return Reflect.apply(original, this, args);
+      }
+    ))
   ];
 }
 
+/**
+ * @param {BrowserWindow} browserWindow
+ * @param {AddBreadcrumb} add
+ * @returns {Restore[]}
+ */
 function patchNavigation(browserWindow, add) {
-  const history = browserWindow.history;
+  const { history } = browserWindow;
   if (!history) {
     return [];
   }
   let from = currentPath(browserWindow);
-  const record = () => {
+  /** @returns {void} */
+  function record() {
     const to = currentPath(browserWindow);
-    if (to && to !== from) {
-      add({ type: "navigation", category: "navigation", data: { ...(from ? { from } : {}), to } });
+    if (to !== undefined && to !== "" && to !== from) {
+      add({
+        type: "navigation",
+
+        category: "navigation",
+        data: { ...(from === undefined || from === "" ? {} : { from }), to }
+      });
       from = to;
     }
-  };
-  const restores = ["pushState", "replaceState"].flatMap((method) => replaceMethod(history, method, (original) => (
-    /** @this {History} */
+  }
+  const restores = NAVIGATION_METHODS.flatMap((method) => replaceMethod(history, method, (original) => (
+    /**
+     * @this {unknown}
+     * @param {readonly unknown[]} args
+     * @returns {unknown}
+     */
     function logBrewNavigationBreadcrumb(...args) {
-      const result = original.apply(this, args);
+      const result = Reflect.apply(original, this, args);
       record();
       return result;
     }
   )));
   if (typeof browserWindow.addEventListener === "function") {
     browserWindow.addEventListener("popstate", record);
-    restores.push(() => browserWindow.removeEventListener?.("popstate", record));
+    restores.push(() => {
+      browserWindow.removeEventListener?.("popstate", record);
+    });
   }
   return restores;
 }
 
-function replaceMethod(target, name, wrap) {
-  const original = target?.[name];
-  if (typeof original !== "function") {
-    return [];
-  }
-  const replacement = wrap(original);
-  target[name] = replacement;
-  return [() => {
-    if (target[name] === replacement) {
-      target[name] = original;
-    }
-  }];
-}
-
-function httpBreadcrumb(category, method, url, status) {
-  const statusCode = Number.isInteger(status) && status > 0 ? status : undefined;
-  return {
-    type: "http",
-    category,
-    level: statusCode === undefined || statusCode < 400 ? "info" : statusCode >= 500 ? "error" : "warning",
-    data: {
-      method: method.slice(0, 16) || "GET",
-      ...(url ? { url } : {}),
-      ...(statusCode === undefined ? {} : { status_code: statusCode })
+/**
+ * @param {BrowserWindow} browserWindow
+ * @param {BreadcrumbClient} client
+ * @param {BrowserBreadcrumbOptions} [options]
+ * @returns {Restore}
+ */
+function installBrowserBreadcrumbs(browserWindow, client, {
+  console: captureConsole = true,
+  ignoredUrls = [],
+  navigation = true,
+  network = true
+} = {}) {
+  const ignored = new Set(ignoredUrls.map((url) => sanitizeUrl(url, browserWindow)).filter(Boolean));
+  /**
+   * @param {BrowserBreadcrumb} breadcrumb
+   * @returns {boolean}
+   */
+  function add(breadcrumb) {
+    try {
+      client.addBreadcrumb(breadcrumb);
+    } catch {
+      return false;
     }
-  };
-}
-
-// Records the message template, never the interpolated arguments.
-function consoleTemplate(args) {
-  const [first] = args;
-  if (typeof first === "string") {
-    return first;
+    return true;
   }
-  return first instanceof Error ? first.name || "Error" : "";
-}
-
-function currentPath(browserWindow) {
-  const pathname = browserWindow.location?.pathname;
-  return typeof pathname === "string" ? boundedText(pathname, MAX_URL_LENGTH) : undefined;
-}
-
-// Keeps scheme, host, and path; drops user info, query, and fragment.
-function sanitizeUrl(value, browserWindow) {
-  if (value === undefined || value === null) {
-    return undefined;
+  /** @type {Restore[]} */
+  const restores = [];
+  if (captureConsole) {
+    restores.push(...patchConsole(browserWindow.console ?? globalThis.console, add));
   }
-  try {
-    const url = new URL(String(value), String(browserWindow.location?.href ?? "http://localhost/"));
-    return boundedText(`${url.protocol}//${url.host}${url.pathname}`, MAX_URL_LENGTH) || undefined;
-  } catch {
-    return undefined;
+  if (network) {
+    restores.push(...patchFetch(browserWindow, add, ignored), ...patchXhr(browserWindow, add, ignored));
   }
-}
-
-function boundedText(value, limit) {
-  const characters = Array.from(String(value), (character) => {
-    const code = character.codePointAt(0);
-    return code <= 31 || (code >= 127 && code <= 159) ? " " : character;
-  });
-  return Array.from(characters.join("").replace(/\s+/gu, " ").trim()).slice(0, limit).join("");
+  if (navigation) {
+    restores.push(...patchNavigation(browserWindow, add));
+  }
+  return () => {
+    const pending = restores.splice(FIRST_RESTORE);
+    for (let restore = pending.pop(); restore !== undefined; restore = pending.pop()) {
+      restore();
+    }
+  };
 }
 
 module.exports = { installBrowserBreadcrumbs };

package/capture-support.cjs

@@ -0,0 +1,100 @@
+const { compactMetadata } = require("./log-context.cjs");
+const { NULL_VALUE } = require("./null-value.cjs");
+
+/**
+ * @import { Metadata } from "./index.cjs"
+ * @typedef {(reason: unknown) => void} ErrorHandler
+ * @typedef {Readonly<{
+ *   log: (id: string, timestamp: unknown, attributes: Readonly<Record<string, unknown>>) => void,
+ *   flush: (transport: unknown) => Promise<unknown>,
+ *   pendingEvents: () => number
+ * }>} CaptureClient
+ * @typedef {{
+ *   transport: unknown,
+ *   flushOnEvent: boolean,
+ *   includeErrorStack: boolean,
+ *   logger: unknown,
+ *   metadata: Metadata,
+ *   timestamp: () => unknown,
+ *   eventIdPrefix: unknown,
+ *   onError: ErrorHandler
+ * }} CaptureSettings
+ */
+
+/**
+ * @param {unknown} flushing
+ * @param {ErrorHandler} onError
+ * @returns {Promise<unknown>}
+ */
+async function settledFlush(flushing, onError) {
+  try {
+    return await flushing;
+  } catch (error) {
+    onError(error);
+    return NULL_VALUE;
+  }
+}
+
+/**
+ * @param {unknown} source
+ * @returns {(() => unknown) | undefined}
+ */
+function callableOrUndefined(source) {
+  if (typeof source !== "function") {
+    return undefined;
+  }
+  return () => {
+    /** @type {unknown} */
+    const value = Reflect.apply(source, undefined, []);
+    return value;
+  };
+}
+
+/**
+ * @param {unknown} handler
+ * @returns {ErrorHandler}
+ */
+function errorHandler(handler) {
+  if (typeof handler !== "function") {
+    return () => undefined;
+  }
+  return (reason) => {
+    Reflect.apply(handler, undefined, [reason]);
+  };
+}
+
+/**
+ * @param {unknown} timestamp
+ * @returns {() => unknown}
+ */
+function timestampSource(timestamp) {
+  return callableOrUndefined(timestamp) ?? (() => new Date().toISOString());
+}
+
+/**
+ * @param {Readonly<Record<string, unknown>>} config
+ * @param {string} flushKey
+ * @param {string} defaultName
+ * @returns {CaptureSettings}
+ */
+function captureSettings(config, flushKey, defaultName) {
+  return {
+    transport: config["transport"],
+
+    flushOnEvent: config[flushKey] === true,
+
+    includeErrorStack: config["includeErrorStack"] === true,
+
+    logger: config["logger"] ?? defaultName,
+
+    metadata: compactMetadata(config["metadata"]),
+
+    timestamp: timestampSource(config["timestamp"]),
+
+    eventIdPrefix: config["eventIdPrefix"] ?? defaultName,
+
+    onError: errorHandler(config["onError"])
+  };
+}
+
+module.exports = { callableOrUndefined, captureSettings, errorHandler, settledFlush };