@hakam-aldeen-kh/blix 0.4.2 → 0.6.0

package/dist/capture/index.d.ts

@@ -1,5 +1,3 @@
-import { AxiosInstance } from 'axios';
-
 /**
  * Blix — HTTP capture entry point.
  *
@@ -8,19 +6,122 @@ import { AxiosInstance } from 'axios';
  * encryption or auth interceptors, so this interceptor runs last in axios's
  * LIFO request stack and therefore sees the plaintext request body.
  *
+ * Typed structurally rather than against axios: axios is an optional peer, and
+ * an app that only uses `fetch` must be able to type-check Blix without it.
+ *
  * No-op when `process.env.NODE_ENV !== "development"`.
  */
-
+/**
+ * The part of an axios interceptor manager Blix uses.
+ *
+ * The callbacks are typed `any`, and have to be: axios types them against its
+ * own config and response types, and a callback's parameter is checked
+ * contravariantly — `unknown` there would reject a real axios instance. `use`
+ * and `eject` themselves use method syntax, whose parameters are checked
+ * bivariantly, which is what lets `AxiosInterceptorManager<V>` satisfy this
+ * for any `V`.
+ */
+interface InterceptorManagerLike {
+    use(onFulfilled?: ((value: any) => any) | null, onRejected?: ((error: any) => any) | null): number;
+    eject(id: number): void;
+}
+/**
+ * What `attachHttpMonitor` needs from an axios instance: `interceptors`, and
+ * nothing else. Structural, like `HttpClientLike` — Blix does not import
+ * axios's types, so a fetch-only app never needs axios installed to type-check
+ * against Blix, and a real `AxiosInstance` still passes with no cast.
+ */
+interface HttpMonitorTarget {
+    interceptors: {
+        request: InterceptorManagerLike;
+        response: InterceptorManagerLike;
+    };
+}
 /**
  * Attaches HTTP-capture interceptors to an axios instance.
  *
  * Call this at module init time (e.g. at the bottom of your `axios.ts`),
  * after registering any encryption interceptors so that the monitor sees the
  * plaintext body first.
+ *
+ * Idempotent per instance, and returns a disposer that ejects both
+ * interceptors. A second install used to register a second pair: every request
+ * then started two entries, both response interceptors settled the second, and
+ * the first stayed pending for the rest of the session.
  */
-declare function attachHttpMonitor(instance: AxiosInstance, options?: {
+declare function attachHttpMonitor(instance: HttpMonitorTarget, options?: {
     dbName?: string;
-}): void;
+}): () => void;
+
+/**
+ * Blix — HTTP capture for native `fetch`.
+ *
+ * `attachHttpMonitor` only sees requests made through an axios instance, so an
+ * app that calls `fetch` directly — the default in a Next.js App Router project
+ * — got an empty Network tab and a reasonable conclusion that Blix was broken.
+ * This wraps `globalThis.fetch` and feeds the same store with the same
+ * `MonitorEntry` shape, marked `client: "fetch"`.
+ *
+ * ## The rules this file is built around
+ *
+ * - **The caller's bodies are never consumed.** `Request` and `Response` bodies
+ *   are one-shot streams. Everything Blix reads it reads from a `clone()`, taken
+ *   before the body can be touched: the request's before `fetch` is called, the
+ *   response's before the caller is handed it.
+ * - **Nothing is buffered without bound.** Bodies are read through a byte
+ *   counter on every read and abandoned past `maxBodyBytes`, whatever
+ *   `Content-Length` claimed. That header is the *encoded* length; the clone
+ *   yields decoded bytes, so a small gzip can inflate far past it.
+ * - **Nothing the caller passed is mutated, and no error is swallowed or
+ *   replaced.** A failure anywhere in capture degrades to "not captured", never
+ *   to a broken request.
+ * - **Browser only.** Next.js patches `fetch` on the server for its data cache;
+ *   Blix never touches that one.
+ *
+ * `captureEncrypted` does not apply here. It correlates by an object the host
+ * holds inside its own interceptor, and `fetch` has no interceptor stage.
+ */
+/**
+ * A rule that keeps a request out of the log. A string matches as a substring,
+ * and a regular expression is tested, against the URL's path and query
+ * (`/api/items?page=2`); a function receives the resolved `URL`.
+ */
+type FetchIgnoreRule = string | RegExp | ((url: URL) => boolean);
+interface FetchMonitorOptions {
+    /** IndexedDB database name — see `attachHttpMonitor`. */
+    dbName?: string;
+    /**
+     * Largest body Blix will read, request or response, in bytes. Default
+     * 5 MB. A larger body is still logged — status, headers, timing — with the
+     * body marked as not captured, and why. `0` captures no bodies at all.
+     */
+    maxBodyBytes?: number;
+    /**
+     * Requests to leave out of the log entirely. An array **replaces** the
+     * defaults; a function receives the defaults and returns the list to use,
+     * which is how to extend them. `[]` captures everything.
+     *
+     * The defaults drop framework dev traffic that would otherwise bury the app's
+     * own requests: Next.js assets, HMR and data requests (`/_next/`), the
+     * Next.js dev overlay (`/__nextjs`), App Router navigation and prefetch
+     * payloads (`?_rsc=`), and webpack HMR (`.hot-update.`, `/__webpack_hmr`).
+     */
+    ignore?: readonly FetchIgnoreRule[] | ((defaults: readonly FetchIgnoreRule[]) => readonly FetchIgnoreRule[]);
+}
+/**
+ * Wraps `globalThis.fetch` so every request the page makes is captured, and
+ * returns a disposer that unwraps it.
+ *
+ * Call once, as early as possible — before the first `fetch` you want to see.
+ * A no-op in production, on the server, and when Blix's wrapper is already
+ * installed (the returned disposer is then a no-op too).
+ *
+ * The disposer restores the exact original `fetch`, but only while Blix's
+ * wrapper is still what `globalThis.fetch` points at. If something else has
+ * patched over it since, restoring would silently remove that patch as well,
+ * so it is left alone and a development warning explains why.
+ */
+declare function attachFetchMonitor(options?: FetchMonitorOptions): () => void;
 
 /**
  * Blix — encrypted-payload capture (opt-in).
@@ -304,7 +405,7 @@ interface ReduxActionMeta {
 }
 /** Query/mutation only: the cache row's current lifecycle state. Deliberately
  * not folded into `MonitorState` — `MonitorState` drives the shared state
- * filter and waterfall colour, and pending/success/error covers this fine;
+ * filter and row colour, and pending/success/error covers this fine;
  * the richer status (fresh/stale/fetching/removed) lives here instead. */
 interface QueryMeta {
     sub: "query" | "mutation";
@@ -353,14 +454,13 @@ interface MonitorEntry {
     /**
      * Start/end as absolute epoch ms (`timeOrigin + startTime`).
      *
-     * The waterfall must use these, never `startTime`/`endTime`: those are
-     * relative to a per-page-load origin, so a persisted entry's `startTime` is
-     * meaningless against the current load's.
+     * Anything comparing two entries in time must use these, never
+     * `startTime`/`endTime`: those are relative to a per-page-load origin, so a
+     * persisted entry's `startTime` is meaningless against the current load's.
      */
     startAbs: number;
     endAbs?: number;
-    /** Which page load captured this. Drives the divider rows and the per-load
-     * waterfall timeline. */
+    /** Which page load captured this. Drives the divider rows in the list. */
     loadId: string;
     status?: number;
     state: MonitorState;
@@ -409,6 +509,15 @@ interface MonitorEntry {
     redux?: ReduxActionMeta;
     /** Query only: the cache row's key, status and observer count. */
     query?: QueryMeta;
+    /**
+     * HTTP only: which capture path recorded this request — `attachHttpMonitor`
+     * (`"axios"`) or `attachFetchMonitor` (`"fetch"`). Deliberately not
+     * `transport`, which is realtime-only and is rendered in place of the method.
+     *
+     * Absent on entries captured before this field existed. Absent means
+     * unknown — never read it as "axios".
+     */
+    client?: "axios" | "fetch";
     /** HTTP only: id of the query/mutation entry that caused this request,
      * when it could be determined — see `monitorContext.ts`. Absence means
      * "unknown", never "not caused by a query". */
@@ -437,10 +546,15 @@ interface Pos {
  * Everything the panel remembers between sessions.
  *
  * Stored in IndexedDB (`meta.prefs`) as the source of truth, mirrored into
- * `localStorage["nm:prefs"]` purely as a synchronous read cache so the panel
- * can restore its geometry without a frame of flash. The mirror is expendable —
+ * `localStorage["<dbName>:prefs"]` — `blix:checkout:prefs` for
+ * `dbName="checkout"` — purely as a synchronous read cache so the panel can
+ * restore its geometry without a frame of flash. The mirror is expendable —
  * any host that clears web storage wipes it, and the IndexedDB copy silently
  * restores it on next boot.
+ *
+ * Both halves are scoped to the database name: web storage, like IndexedDB, is
+ * origin-scoped, so an unscoped key meant every app on one origin shared one
+ * set of preferences.
  */
 interface MonitorPrefs {
     /** Bumped on every write; used to reconcile the two copies. */
@@ -481,10 +595,12 @@ interface MonitorPrefs {
     dataFormat: string;
     /** Active top-level section — `"network"` (HTTP) or `"realtime"` (sockets). */
     section: string;
+    /** Sources rail shown as icons only. A deliberate choice, kept separate from
+     * the automatic collapse a narrow panel applies — re-widening the panel
+     * restores the rail unless the developer collapsed it themselves. */
+    railCollapsed: boolean;
     /** Row height preset: compact | normal | comfy. */
     density: string;
-    /** User-resized column widths, in px, keyed by column id. */
-    columnWidths: Record<string, number>;
 }
 
 /**
@@ -542,12 +658,42 @@ declare function tapRealtimeAdapter<T extends RealtimeAdapterLike>(adapter: T, t
  *
  * So `withInitiatorCapture` wraps the axios instance, takes the stack
  * synchronously in the caller's own frame, and stashes it on the config for
- * `beginMonitor` to read.
+ * `beginMonitor` to read. The fetch wrapper needs no such proxy: it *is* the
+ * call site, so it calls `captureFrames` directly.
+ *
+ * ## Why Blix's own frames are dropped by depth
+ *
+ * Both callers know exactly how many of their own frames sit above the caller's
+ * code, and pass that as `skip`. The alternative — recognizing Blix's frames by
+ * module name — does not survive bundling: the published package is a handful
+ * of hashed `dist/chunk-*.js` files, none of them named after the source
+ * module, so in a real install every Blix frame slipped through and the
+ * Initiator column pointed at Blix itself. Do not add module-name rules for
+ * Blix's own code to `NOISE`.
  *
  * The whole module is behind a statically-foldable `NODE_ENV` check at its call
  * site, so it is dead-code-eliminated from production builds.
  */
 
+/**
+ * What `withInitiatorCapture` needs from an HTTP client — declared
+ * structurally, so axios's types are never imported and an app that only uses
+ * `fetch` never needs axios installed to type-check against Blix.
+ *
+ * `request` is the one entry point every axios-style client has; the verb
+ * helpers are wrapped when present. Method syntax on purpose: method parameters
+ * are compared bivariantly, which is what lets axios's generic, config-typed
+ * signatures satisfy these `unknown`-typed ones without a cast.
+ */
+interface InitiatorCaptureTarget {
+    request(config: unknown): unknown;
+    get?(url: string, config?: unknown): unknown;
+    delete?(url: string, config?: unknown): unknown;
+    head?(url: string, config?: unknown): unknown;
+    post?(url: string, data?: unknown, config?: unknown): unknown;
+    put?(url: string, data?: unknown, config?: unknown): unknown;
+    patch?(url: string, data?: unknown, config?: unknown): unknown;
+}
 /**
  * Wraps the axios instance so every call site records its own stack.
  *
@@ -555,7 +701,11 @@ declare function tapRealtimeAdapter<T extends RealtimeAdapterLike>(adapter: T, t
  * `put`, `patch`, `delete` and `head`. Other entry points (`options`, the
  * `*Form` helpers) pass through unwrapped — requests made through them are
  * still captured, they just carry no initiator stack.
+ *
+ * Generic over the instance, so what the caller gets back is its own type —
+ * an `AxiosInstance` stays an `AxiosInstance`, with `get<T>`, `defaults` and
+ * `interceptors` intact — rather than the minimal shape it was checked against.
  */
-declare function withInitiatorCapture(instance: AxiosInstance): AxiosInstance;
+declare function withInitiatorCapture<T extends InitiatorCaptureTarget>(instance: T): T;
 
-export { type CacheLike, type Corner, type DiffOp, type DockMode, type EncryptedPayload, type FrameDirection, type InitiatorFrame, type MiddlewareApiLike, type MiddlewareLike, type MonitorEntry, type MonitorKind, type MonitorPrefs, type MonitorState, type PersistedEntry, type Pos, type QueryClientLike, type QueryMeta, type RealtimeAdapterLike, type ReduxActionMeta, type ReduxCaptureOptions, type Size, type StateDiff, type StateDiffEntry, type TimingMarks, type WsFrame, attachHttpMonitor, captureEncrypted, createReduxMonitorMiddleware, tapQueryClient, tapRealtimeAdapter, withInitiatorCapture };
+export { type CacheLike, type Corner, type DiffOp, type DockMode, type EncryptedPayload, type FetchIgnoreRule, type FetchMonitorOptions, type FrameDirection, type InitiatorFrame, type MiddlewareApiLike, type MiddlewareLike, type MonitorEntry, type MonitorKind, type MonitorPrefs, type MonitorState, type PersistedEntry, type Pos, type QueryClientLike, type QueryMeta, type RealtimeAdapterLike, type ReduxActionMeta, type ReduxCaptureOptions, type Size, type StateDiff, type StateDiffEntry, type TimingMarks, type WsFrame, attachFetchMonitor, attachHttpMonitor, captureEncrypted, createReduxMonitorMiddleware, tapQueryClient, tapRealtimeAdapter, withInitiatorCapture };

package/dist/capture/index.js

@@ -1,14 +1,16 @@
 import {
+  attachFetchMonitor,
   attachHttpMonitor,
   captureEncrypted,
   tapRealtimeAdapter
-} from "../chunk-OQHKPRNI.js";
+} from "../chunk-4JZEVUOR.js";
 import {
   createReduxMonitorMiddleware,
   tapQueryClient,
   withInitiatorCapture
-} from "../chunk-MRTSIXR7.js";
+} from "../chunk-FIYP47QZ.js";
 export {
+  attachFetchMonitor,
   attachHttpMonitor,
   captureEncrypted,
   createReduxMonitorMiddleware,