@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 +53 -17
- package/dist/client/attach.d.ts +17 -4
- package/dist/index.d.ts +3 -1
- package/dist/index.js +35 -7
- package/package.json +6 -6
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.
|
package/dist/client/attach.d.ts
CHANGED
|
@@ -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
|
|
35
|
-
* unless disabled and returns a controller
|
|
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
|
|
900
|
-
* unless disabled and returns a controller
|
|
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
|
|
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
|
|
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.
|
|
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
|
|
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.
|
|
35
|
+
"eslint": "10.15.0",
|
|
36
36
|
"husky": "9.1.7",
|
|
37
37
|
"jiti": "2.7.0",
|
|
38
|
-
"lint-staged": "17.6.
|
|
38
|
+
"lint-staged": "17.6.1",
|
|
39
39
|
"npm-check-updates": "23.1.1",
|
|
40
40
|
"rimraf": "6.1.4",
|
|
41
|
-
"tsrs": "0.
|
|
41
|
+
"tsrs": "0.25.0-ts7.1.0-beta",
|
|
42
42
|
"typescript": "npm:@typescript/typescript6@6.0.2",
|
|
43
|
-
"vite": "8.3.
|
|
43
|
+
"vite": "8.3.8",
|
|
44
44
|
"vite-plugin-dts": "5.1.2",
|
|
45
45
|
"vitest": "5.1.0"
|
|
46
46
|
},
|