@micheldever/fetch-debug 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -72,7 +72,7 @@ Call `dispose()` when the debug session ends. It restores the original `fetch` a
72
72
  debug.dispose();
73
73
  ```
74
74
 
75
- Calling `attachFetchDebug` again with the same client returns the existing controller.
75
+ Calling `attachFetchDebug` again with the same client returns the existing controller and ignores the new options; the association is kept in a module-level `WeakMap`. When attaching once to a shared, long-lived client, `source` must therefore be a stable resolver that reads ambient request context on every call. A per-request source cannot be swapped in after the first attach; create a client per request if that is needed.
76
76
 
77
77
  ### Node
78
78
 
@@ -104,7 +104,40 @@ const orders = await client.fetch('https://api.example.com/api/orders');
104
104
  debug.dispose();
105
105
  ```
106
106
 
107
- `MemoryStorageAdapter` keeps overrides for the lifetime of the process. `console: false` skips console installation entirely, which is the usual choice outside a browser.
107
+ `MemoryStorageAdapter` keeps overrides for the lifetime of the process. `console: false` skips console installation entirely, which is the usual choice outside a browser. The same attachment works during server-side rendering; see [Server-side Request Overrides](#server-side-request-overrides) when each request needs its own overrides.
108
+
109
+ ## Registries
110
+
111
+ `attachFetchDebug` creates an override registry for you. Import `createRegistry` when you need to build and own a registry independently of `attachFetchDebug`, such as when scoping overrides to a single request:
112
+
113
+ ```typescript
114
+ import { createRegistry } from '@micheldever/fetch-debug';
115
+ import { StorageEntity } from '@micheldever/storage';
116
+ import { MemoryStorageAdapter } from '@micheldever/storage/adapters/memory';
117
+
118
+ const registry = createRegistry({
119
+ storage: new StorageEntity([new MemoryStorageAdapter()]),
120
+ storageKey: 'my-app:fetch-overrides',
121
+ logPrefix: '[api-debug]',
122
+ });
123
+
124
+ await registry.ready;
125
+
126
+ await registry.set({ pattern: '/api/orders', status: 503 });
127
+ ```
128
+
129
+ `createRegistry({ storage, storageKey, logPrefix })` builds a registry that hydrates from the supplied `StorageEntity` and persists every mutation. The options and defaults match the corresponding `attachFetchDebug` options. The returned `FetchDebugRegistry` exposes:
130
+
131
+ | Member | Description |
132
+ | --- | --- |
133
+ | `ready` | Promise that resolves after stored overrides have been loaded. |
134
+ | `set(input)` | Async. Validate and register an override; returns the stored record. |
135
+ | `get()` | Synchronous. Return every registered override. |
136
+ | `remove(pattern, method?)` | Async. Remove one override and return whether a record was removed. |
137
+ | `clear()` | Async. Remove every override. |
138
+ | `consume(pathname, method)` | Synchronous. Return the override matching a stripped pathname and method, or `undefined`. Matching removes `times: 1` records. |
139
+
140
+ The `FetchDebugRegistry`, `FetchDebugRegistryOptions`, and `FetchDebugOverrideSource` types are exported from the package root.
108
141
 
109
142
  ## Options
110
143
 
@@ -116,6 +149,10 @@ debug.dispose();
116
149
  | `storageKey` | `string` | Logical key used for the stored payload. |
117
150
  | `logPrefix` | `string` | Prefix for messages logged by the console commands. |
118
151
  | `console` | `false \| { enabled?: boolean; namespace?: string; target?: object }` | Console installation. `false` disables it; an object configures it. |
152
+ | `registry` | `FetchDebugRegistry \| false` | Optional. Supply a registry instead of creating one, or `false` to disable registry resolution. A supplied registry is neither hydrated nor persisted by `attachFetchDebug`, and `controller.ready` is that registry's `ready`. |
153
+ | `source` | `FetchDebugOverrideSource` | Optional. Request-scoped resolver consulted before the registry. Receives the query/hash-stripped pathname and the uppercased method. |
154
+
155
+ `source` has the shape `{ consume(pathname: string, method: string): FetchDebugOverride | undefined }`, which is `Pick<FetchDebugRegistry, 'consume'>`. Overrides resolve in this order: `source.consume(...)` first; when it returns `undefined`, the registry is consulted; when neither matches, the request delegates to the original `fetch`.
119
156
 
120
157
  ### Defaults
121
158
 
@@ -123,6 +160,18 @@ debug.dispose();
123
160
  - Logical storage key: `fetch-debug:overrides:v1`
124
161
  - Log prefix: `[fetch-debug]`
125
162
  - Storage: in-memory when no `storage` is supplied
163
+ - Registry: created from `storage` and `storageKey` when `registry` is omitted
164
+ - Source: none; the registry is the only override source
165
+
166
+ ### Disabling the Registry
167
+
168
+ Pass `registry: false` when overrides should come only from `source`, or when the client should behave like an unattached client for override resolution and no override is ever applied:
169
+
170
+ - No registry is created, and no storage hydration or persistence happens.
171
+ - `controller.ready` resolves immediately and `controller.list()` returns `[]`.
172
+ - `controller.override`, `controller.clear`, and `controller.clearAll` reject with `fetch-debug registry is disabled by registry: false`.
173
+ - `controller.help()` still returns the help text.
174
+ - The console is forced off, even when `console` is configured. Passing `console: { enabled: true }` together with `registry: false` throws a `TypeError` when first attaching, with the message `console cannot be enabled when registry is false`. Re-attaching the same client returns the existing controller and does not throw.
126
175
 
127
176
  ## Override Input
128
177
 
@@ -161,7 +210,7 @@ Overrides match the request pathname only. Query strings, hashes, and origins ar
161
210
 
162
211
  ## Console Commands
163
212
 
164
- `attachFetchDebug` installs a console object at `globalThis.fetchDebug` by default. Set `console: false` to disable installation, or pass `{ enabled: false }` for the same effect. Use `namespace` to choose the property name and `target` to install somewhere other than `globalThis`. If the namespace already exists on the target, it is left untouched.
213
+ `attachFetchDebug` installs a console object at `globalThis.fetchDebug` by default. Set `console: false` to disable installation, or pass `{ enabled: false }` for the same effect. Use `namespace` to choose the property name and `target` to install somewhere other than `globalThis`. If the namespace already exists on the target, it is left untouched. `registry: false` forces the console off regardless of these options.
165
214
 
166
215
  | Command | Description |
167
216
  | --- | --- |
@@ -182,7 +231,7 @@ await debug.clear('/api/orders');
182
231
  await debug.clearAll();
183
232
  ```
184
233
 
185
- `controller.ready` resolves after stored overrides have been loaded. Await it before reading `list()` or issuing requests that should match persisted overrides.
234
+ `controller.ready` resolves after stored overrides have been loaded. Await it before reading `list()` or issuing requests that should match persisted overrides. When you supply `registry`, `controller.ready` is that registry's `ready` promise.
186
235
 
187
236
  ## Storage
188
237
 
@@ -207,16 +256,3 @@ The override check runs before the client's original `fetch`, so an override tak
207
256
  ## Consumer Responsibilities
208
257
 
209
258
  This package performs no environment gating. The consumer decides when to attach it and must not attach it in production. The consumer also supplies storage and chooses the console target and namespace.
210
-
211
- ## Runtime Support
212
-
213
- The package runs in browsers and in Node when storage is injected. It reads no browser globals at import time, so importing it in a server build is safe. Call `dispose()` during teardown to restore the original `fetch` and remove the installed console namespace.
214
-
215
- ## Limitations
216
-
217
- - Only the attached client's `fetch` is intercepted. `raw`, static `FetchClient.fetch`, third-party SDKs, and direct `fetch` calls are unaffected.
218
- - Integrating overrides into server-side consumer code is out of scope.
219
- - There is no UI; the console object is the only built-in surface.
220
- - Overrides are not synchronised across tabs.
221
- - There is no option to leave a request pending indefinitely.
222
- - Synthetic responses do not set cookies.
@@ -1,20 +1,32 @@
1
1
  import { FetchClient } from '@micheldever/fetch';
2
2
  import { FetchDebugConsole, FetchDebugConsoleOptions } from '../console/console.js';
3
+ import { FetchDebugRegistry } from '../core/registry.js';
3
4
  import { StorageEntity } from '@micheldever/storage';
4
5
  /**
5
6
  * The minimal fetch client shape intercepted by `attachFetchDebug`.
6
7
  */
7
8
  export type FetchDebugClient = Pick<FetchClient, 'fetch'>;
9
+ /**
10
+ * A request-scoped source of overrides consulted before the registry.
11
+ *
12
+ * The source receives the query/hash-stripped pathname and the uppercased
13
+ * method, and returns an override to apply or `undefined` to fall back to the
14
+ * registry.
15
+ */
16
+ export type FetchDebugOverrideSource = Pick<FetchDebugRegistry, 'consume'>;
8
17
  /**
9
18
  * Options for `attachFetchDebug`.
10
19
  *
11
20
  * The console installs at `globalThis.fetchDebug` by default, the storage key
12
21
  * defaults to the versioned fetch-debug key, and overrides live in memory when
13
- * no storage is supplied.
22
+ * no storage is supplied. Supplying `registry` uses that registry instead of
23
+ * creating one, and `registry: false` disables registry resolution entirely.
14
24
  */
15
25
  export interface AttachOptions {
16
26
  console?: false | FetchDebugConsoleOptions;
17
27
  logPrefix?: string;
28
+ registry?: false | FetchDebugRegistry;
29
+ source?: FetchDebugOverrideSource;
18
30
  storage?: StorageEntity;
19
31
  storageKey?: string;
20
32
  }
@@ -31,9 +43,9 @@ export interface FetchDebugController extends FetchDebugConsole {
31
43
  * Attaches debug overrides to a fetch client.
32
44
  *
33
45
  * Replaces the client's own `fetch` with a wrapper that resolves a matching
34
- * override before delegating to the original method. Installs the console
35
- * unless disabled and returns a controller exposing the console commands,
36
- * hydration state, and teardown.
46
+ * override from the source or registry before delegating to the original
47
+ * method. Installs the console unless disabled and returns a controller
48
+ * exposing the console commands, hydration state, and teardown.
37
49
  *
38
50
  * Calling this again with the same client returns the existing controller
39
51
  * without installing another wrapper.
@@ -41,5 +53,6 @@ export interface FetchDebugController extends FetchDebugConsole {
41
53
  * @param options The attachment options.
42
54
  * @returns The controller for the attached client.
43
55
  * @throws {TypeError} When first attaching and `client.fetch` is not a function.
56
+ * @throws {TypeError} When first attaching, `registry` is `false`, and `console.enabled` is `true`.
44
57
  */
45
58
  export declare function attachFetchDebug(client: FetchDebugClient, options?: AttachOptions): FetchDebugController;
package/dist/index.d.ts CHANGED
@@ -1,4 +1,6 @@
1
1
  export { attachFetchDebug } from './client/attach.js';
2
- export type { AttachOptions, FetchDebugClient, FetchDebugController } from './client/attach.js';
2
+ export type { AttachOptions, FetchDebugClient, FetchDebugController, FetchDebugOverrideSource } from './client/attach.js';
3
3
  export type { FetchDebugConsole, FetchDebugConsoleOptions } from './console/console.js';
4
4
  export type { FetchDebugOverride } from './core/override.js';
5
+ export { createRegistry } from './core/registry.js';
6
+ export type { FetchDebugRegistry, FetchDebugRegistryOptions } from './core/registry.js';
package/dist/index.js CHANGED
@@ -893,12 +893,32 @@ var DEFAULT_LOG_PREFIX = "[fetch-debug]";
893
893
  */
894
894
  var attachedClients = /* @__PURE__ */ new WeakMap();
895
895
  /**
896
+ * Creates a registry that resolves no overrides and rejects every mutation.
897
+ *
898
+ * Used when `registry: false` disables registry resolution while keeping the
899
+ * controller commands available.
900
+ * @returns A registry whose `ready` resolves immediately, whose `consume` returns `undefined`, and whose mutations reject.
901
+ */
902
+ function createDisabledRegistry() {
903
+ function rejectDisabled() {
904
+ return Promise.reject(/* @__PURE__ */ new Error("fetch-debug registry is disabled by registry: false"));
905
+ }
906
+ return {
907
+ clear: rejectDisabled,
908
+ consume: () => void 0,
909
+ get: () => [],
910
+ ready: Promise.resolve(),
911
+ remove: rejectDisabled,
912
+ set: rejectDisabled
913
+ };
914
+ }
915
+ /**
896
916
  * Attaches debug overrides to a fetch client.
897
917
  *
898
918
  * Replaces the client's own `fetch` with a wrapper that resolves a matching
899
- * override before delegating to the original method. Installs the console
900
- * unless disabled and returns a controller exposing the console commands,
901
- * hydration state, and teardown.
919
+ * override from the source or registry before delegating to the original
920
+ * method. Installs the console unless disabled and returns a controller
921
+ * exposing the console commands, hydration state, and teardown.
902
922
  *
903
923
  * Calling this again with the same client returns the existing controller
904
924
  * without installing another wrapper.
@@ -906,6 +926,7 @@ var attachedClients = /* @__PURE__ */ new WeakMap();
906
926
  * @param options The attachment options.
907
927
  * @returns The controller for the attached client.
908
928
  * @throws {TypeError} When first attaching and `client.fetch` is not a function.
929
+ * @throws {TypeError} When first attaching, `registry` is `false`, and `console.enabled` is `true`.
909
930
  */
910
931
  function attachFetchDebug(client, options = {}) {
911
932
  const existing = attachedClients.get(client);
@@ -913,17 +934,24 @@ function attachFetchDebug(client, options = {}) {
913
934
  const previousDescriptor = Object.getOwnPropertyDescriptor(client, "fetch");
914
935
  const original = client.fetch;
915
936
  if (typeof original !== "function") throw new TypeError("client.fetch must be a function");
937
+ if (options.registry === false && typeof options.console === "object" && options.console.enabled === true) throw new TypeError("console cannot be enabled when registry is false");
916
938
  const logPrefix = options.logPrefix ?? DEFAULT_LOG_PREFIX;
917
- const registry = createRegistry({
939
+ const registry = options.registry === false ? createDisabledRegistry() : options.registry ?? createRegistry({
918
940
  logPrefix,
919
941
  storage: options.storage,
920
942
  storageKey: options.storageKey
921
943
  });
922
- const consoleOptions = options.console === false ? { enabled: false } : options.console ?? {};
944
+ const requestedConsole = options.console === false ? { enabled: false } : options.console ?? {};
945
+ const consoleOptions = options.registry === false ? {
946
+ ...requestedConsole,
947
+ enabled: false
948
+ } : requestedConsole;
923
949
  const facade = createFetchDebugConsole(registry, logPrefix, consoleOptions.namespace);
924
950
  const disposeConsole = installFetchDebugConsole(facade, consoleOptions);
925
951
  function wrapper(input, init) {
926
- const override = registry.consume(extractPathname(input), extractMethod(input, init));
952
+ const pathname = extractPathname(input);
953
+ const method = extractMethod(input, init);
954
+ const override = options.source?.consume(pathname, method) ?? registry.consume(pathname, method);
927
955
  if (override) return resolveFetchDebugOverride(override, init?.signal);
928
956
  return Reflect.apply(original, this, [input, init]);
929
957
  }
@@ -952,4 +980,4 @@ function attachFetchDebug(client, options = {}) {
952
980
  attachedClients.set(client, controller);
953
981
  return controller;
954
982
  }
955
- export { attachFetchDebug };
983
+ export { attachFetchDebug, createRegistry };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@micheldever/fetch-debug",
3
- "version": "1.0.0",
3
+ "version": "1.1.0",
4
4
  "type": "module",
5
5
  "description": "Deterministic response overrides for @micheldever/fetch",
6
6
  "license": "MIT",
@@ -29,18 +29,18 @@
29
29
  "@commitlint/config-conventional": "21.2.4",
30
30
  "@micheldever/eslint-config": "2.3.3",
31
31
  "@micheldever/fetch": "2.2.2",
32
- "@micheldever/storage": "2.0.1",
32
+ "@micheldever/storage": "2.1.0",
33
33
  "@types/node": "26.6.6",
34
34
  "@typescript/native": "npm:typescript@7.0.2",
35
- "eslint": "10.14.0",
35
+ "eslint": "10.15.0",
36
36
  "husky": "9.1.7",
37
37
  "jiti": "2.7.0",
38
- "lint-staged": "17.6.0",
38
+ "lint-staged": "17.6.1",
39
39
  "npm-check-updates": "23.1.1",
40
40
  "rimraf": "6.1.4",
41
- "tsrs": "0.23.0-ts7.1.0-beta",
41
+ "tsrs": "0.25.0-ts7.1.0-beta",
42
42
  "typescript": "npm:@typescript/typescript6@6.0.2",
43
- "vite": "8.3.7",
43
+ "vite": "8.3.8",
44
44
  "vite-plugin-dts": "5.1.2",
45
45
  "vitest": "5.1.0"
46
46
  },