@web-ts-toolkit/access-router-react 0.31.5 → 0.33.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.
Files changed (6) hide show
  1. package/README.md +297 -16
  2. package/index.d.mts +283 -49
  3. package/index.d.ts +283 -49
  4. package/index.js +645 -188
  5. package/index.mjs +643 -188
  6. package/package.json +9 -4
package/index.mjs CHANGED
@@ -1,10 +1,51 @@
1
1
  // src/create-model-hook.ts
2
- import { useState, useEffect as useEffect2, useRef as useRef2, useCallback as useCallback2 } from "react";
2
+ import { useState, useEffect as useEffect2, useRef as useRef2, useCallback as useCallback2, useLayoutEffect } from "react";
3
+ import { ServiceError } from "@web-ts-toolkit/access-router-client";
3
4
 
4
5
  // src/fetch.ts
5
6
  import { useEffect, useRef, useCallback } from "react";
6
- function isAbortError(err) {
7
- return err instanceof DOMException && err.name === "AbortError";
7
+ function composeAbortSignals(callerSignal, internalSignal) {
8
+ if (!callerSignal) {
9
+ return { signal: internalSignal, release: () => {
10
+ } };
11
+ }
12
+ if (callerSignal.aborted) {
13
+ return { signal: callerSignal, release: () => {
14
+ } };
15
+ }
16
+ if (internalSignal.aborted) {
17
+ return { signal: internalSignal, release: () => {
18
+ } };
19
+ }
20
+ if (callerSignal === internalSignal) {
21
+ return { signal: internalSignal, release: () => {
22
+ } };
23
+ }
24
+ const composed = new AbortController();
25
+ const detach = () => {
26
+ callerSignal.removeEventListener("abort", onCallerAbort);
27
+ internalSignal.removeEventListener("abort", onInternalAbort);
28
+ };
29
+ const settle = (source) => {
30
+ composed.abort(source.reason);
31
+ detach();
32
+ };
33
+ const onCallerAbort = () => settle(callerSignal);
34
+ const onInternalAbort = () => settle(internalSignal);
35
+ callerSignal.addEventListener("abort", onCallerAbort, { once: true });
36
+ internalSignal.addEventListener("abort", onInternalAbort, { once: true });
37
+ return {
38
+ signal: composed.signal,
39
+ // Idempotent: detach is safe to call even after the listeners already
40
+ // fired and detached on abort.
41
+ release: detach
42
+ };
43
+ }
44
+ function mergeRequestConfig(requestConfig, signal) {
45
+ if (signal === void 0) {
46
+ return { ...requestConfig ?? {} };
47
+ }
48
+ return { ...requestConfig ?? {}, signal };
8
49
  }
9
50
  function useAbortManager() {
10
51
  const ref = useRef(null);
@@ -18,14 +59,109 @@ function useAbortManager() {
18
59
  ref.current = null;
19
60
  };
20
61
  }, []);
21
- return { replace };
62
+ const managerRef = useRef(null);
63
+ if (managerRef.current === null) {
64
+ managerRef.current = { replace };
65
+ }
66
+ return managerRef.current;
67
+ }
68
+ var RequestKeyError = class extends Error {
69
+ constructor(message) {
70
+ super(message);
71
+ this.name = "RequestKeyError";
72
+ }
73
+ };
74
+ function requestKeyFor(value) {
75
+ return requestKeyForImpl(value, { stack: /* @__PURE__ */ new WeakSet() });
22
76
  }
23
- function stableStringify(value) {
24
- if (value == null) return "";
25
- if (typeof value !== "object") return JSON.stringify(value);
26
- if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
27
- const keys = Object.keys(value).sort();
28
- return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`).join(",")}}`;
77
+ function requestKeyForImpl(value, ctx) {
78
+ if (value === null) return "n:";
79
+ if (value === void 0) return "u:";
80
+ const t = typeof value;
81
+ switch (t) {
82
+ case "boolean":
83
+ return `b:${value}`;
84
+ case "number": {
85
+ if (Number.isNaN(value)) return "n:NaN";
86
+ if (Object.is(value, -0)) return "n:-0";
87
+ return `n:${String(value)}`;
88
+ }
89
+ case "string":
90
+ return `s:${JSON.stringify(value)}`;
91
+ case "bigint":
92
+ throw new RequestKeyError(
93
+ "requestKeyFor: bigint is not supported in request keys; convert to a number or string before passing to a query hook."
94
+ );
95
+ case "function":
96
+ throw new RequestKeyError(
97
+ "requestKeyFor: function values are not supported in request keys; the request contract requires structural data, not callback identity."
98
+ );
99
+ case "symbol":
100
+ throw new RequestKeyError(
101
+ "requestKeyFor: symbol values are not supported in request keys; symbol-keyed properties cannot participate in structural comparison."
102
+ );
103
+ case "object": {
104
+ if (value instanceof Date) {
105
+ return `d:${value.getTime()}`;
106
+ }
107
+ if (value instanceof RegExp || value instanceof Map || value instanceof Set || typeof URL !== "undefined" && value instanceof URL || value instanceof Error) {
108
+ throw new RequestKeyError(
109
+ `requestKeyFor: instance of ${value.constructor?.name ?? "unknown"} is not supported in request keys; pass its plain-data representation (e.g. a URL string, a sorted array of entries) to the query hook instead.`
110
+ );
111
+ }
112
+ if (Array.isArray(value)) {
113
+ if (ctx.stack.has(value)) {
114
+ throw new RequestKeyError("requestKeyFor: cycle detected in array (request key).");
115
+ }
116
+ ctx.stack.add(value);
117
+ let out2 = "[";
118
+ for (let i = 0; i < value.length; i++) {
119
+ if (i > 0) out2 += ",";
120
+ out2 += requestKeyForImpl(value[i], ctx);
121
+ }
122
+ out2 += "]";
123
+ ctx.stack.delete(value);
124
+ return out2;
125
+ }
126
+ const proto = Object.getPrototypeOf(value);
127
+ if (proto !== null && proto !== Object.prototype) {
128
+ throw new RequestKeyError(
129
+ `requestKeyFor: object with prototype ${proto.constructor?.name ?? "unknown"} is not a plain object; only object literals and Object.create(null) shapes are supported in request keys.`
130
+ );
131
+ }
132
+ if (ctx.stack.has(value)) {
133
+ throw new RequestKeyError("requestKeyFor: cycle detected in object (request key).");
134
+ }
135
+ ctx.stack.add(value);
136
+ const symKeys = Object.getOwnPropertySymbols(value);
137
+ if (symKeys.length > 0) {
138
+ throw new RequestKeyError(
139
+ `requestKeyFor: symbol-keyed properties are not supported in request keys; remove symbol keys from the request input before passing it to a query hook.`
140
+ );
141
+ }
142
+ const keys = Object.keys(value).sort();
143
+ let out = "{";
144
+ for (let i = 0; i < keys.length; i++) {
145
+ if (i > 0) out += ",";
146
+ const k = keys[i];
147
+ const desc = Object.getOwnPropertyDescriptor(value, k);
148
+ if (desc === void 0) {
149
+ throw new RequestKeyError(`requestKeyFor: property ${JSON.stringify(k)} has no descriptor (request key).`);
150
+ }
151
+ if ("get" in desc || "set" in desc) {
152
+ throw new RequestKeyError(
153
+ `requestKeyFor: accessor property ${JSON.stringify(k)} is not supported in request keys; getters/setters must not run during dep-key construction.`
154
+ );
155
+ }
156
+ out += `${JSON.stringify(k)}:${requestKeyForImpl(desc.value, ctx)}`;
157
+ }
158
+ out += "}";
159
+ ctx.stack.delete(value);
160
+ return out;
161
+ }
162
+ default:
163
+ throw new RequestKeyError(`requestKeyFor: unsupported value of type ${t}.`);
164
+ }
29
165
  }
30
166
  function useMountRef() {
31
167
  const ref = useRef(true);
@@ -39,6 +175,22 @@ function useMountRef() {
39
175
  }
40
176
 
41
177
  // src/create-model-hook.ts
178
+ function assertSuccess(res) {
179
+ if (!res.success) {
180
+ throw new ServiceError(res);
181
+ }
182
+ return res;
183
+ }
184
+ function useEventCallback(cb) {
185
+ const latest = useRef2(cb);
186
+ useLayoutEffect(() => {
187
+ latest.current = cb;
188
+ });
189
+ const invoker = useCallback2((...args) => {
190
+ return latest.current?.(...args);
191
+ }, []);
192
+ return invoker;
193
+ }
42
194
  function useAutoQuery({
43
195
  doFetch,
44
196
  applyResult,
@@ -46,100 +198,205 @@ function useAutoQuery({
46
198
  deps,
47
199
  onSuccess,
48
200
  onError,
49
- onSettled
201
+ onSettled,
202
+ onFailed,
203
+ onAborted,
204
+ onDisabled
50
205
  }) {
51
206
  const [isLoading, setIsLoading] = useState(false);
52
207
  const [isFetching, setIsFetching] = useState(false);
53
208
  const [error, setError] = useState(null);
209
+ const hasDataRef = useRef2(false);
54
210
  const manager = useAbortManager();
55
211
  const mountRef = useMountRef();
56
- const fetchAndSet = useCallback2(
57
- async (signal) => {
58
- setIsFetching(true);
59
- setError(null);
212
+ const ownerIdRef = useRef2(0);
213
+ const fireCallbacksSafely = useCallback2(
214
+ (settle) => {
60
215
  try {
61
- return await doFetch(signal);
62
- } catch (err) {
63
- if (!isAbortError(err)) setError(err);
64
- throw err;
65
- } finally {
66
- if (!signal?.aborted) setIsFetching(false);
216
+ if ("result" in settle) {
217
+ onSuccess?.(settle.result);
218
+ onSettled?.(settle.result, null);
219
+ } else {
220
+ onError?.(settle.error);
221
+ onSettled?.(null, settle.error);
222
+ }
223
+ } catch (cbErr) {
224
+ queueMicrotask(() => {
225
+ throw cbErr;
226
+ });
67
227
  }
68
228
  },
69
- [doFetch]
229
+ [onSuccess, onError, onSettled]
70
230
  );
71
- const doFetchWithCallbacks = useCallback2(
72
- async (signal) => {
73
- const res = await fetchAndSet(signal);
74
- if (!signal?.aborted) {
231
+ const runWithCallbacks = useCallback2(
232
+ async (controller, doFetchOverride) => {
233
+ const signal = controller.signal;
234
+ const myId = ++ownerIdRef.current;
235
+ setIsFetching(true);
236
+ setError(null);
237
+ if (!hasDataRef.current) setIsLoading(true);
238
+ try {
239
+ const res = await doFetchOverride(signal);
240
+ if (myId !== ownerIdRef.current) {
241
+ return res;
242
+ }
243
+ if (signal.aborted) {
244
+ if (mountRef.current) {
245
+ if (!hasDataRef.current) setIsLoading(false);
246
+ setIsFetching(false);
247
+ onAborted?.();
248
+ }
249
+ return res;
250
+ }
75
251
  applyResult(res);
76
- onSuccess?.(res);
77
- onSettled?.(res, null);
252
+ hasDataRef.current = true;
253
+ setIsLoading(false);
254
+ setIsFetching(false);
255
+ fireCallbacksSafely({ result: res });
256
+ return res;
257
+ } catch (err) {
258
+ if (myId !== ownerIdRef.current) {
259
+ throw err;
260
+ }
261
+ if (signal.aborted) {
262
+ if (mountRef.current) {
263
+ if (!hasDataRef.current) setIsLoading(false);
264
+ setIsFetching(false);
265
+ onAborted?.();
266
+ }
267
+ throw err;
268
+ }
269
+ setError(err);
270
+ if (!hasDataRef.current) setIsLoading(false);
271
+ setIsFetching(false);
272
+ fireCallbacksSafely({ error: err });
273
+ onFailed?.();
274
+ throw err;
78
275
  }
79
- return res;
80
276
  },
81
- [fetchAndSet, applyResult, onSuccess, onSettled]
277
+ [applyResult, fireCallbacksSafely, mountRef, onFailed, onAborted]
82
278
  );
83
279
  useEffect2(() => {
84
- if (!shouldFetch) return;
85
- mountRef.current = true;
86
- setIsLoading(true);
280
+ if (!shouldFetch) {
281
+ setIsLoading(false);
282
+ setIsFetching(false);
283
+ onDisabled?.();
284
+ return;
285
+ }
286
+ setIsLoading(!hasDataRef.current);
87
287
  const controller = new AbortController();
88
288
  manager.replace(controller);
89
- doFetchWithCallbacks(controller.signal).catch((err) => {
90
- if (!mountRef.current || controller.signal.aborted) return;
91
- onError?.(err);
92
- onSettled?.(null, err);
93
- }).finally(() => {
94
- if (mountRef.current && !controller.signal.aborted) setIsLoading(false);
289
+ runWithCallbacks(controller, doFetch).catch(() => {
95
290
  });
96
291
  return () => {
97
- mountRef.current = false;
98
292
  controller.abort();
99
293
  };
100
294
  }, deps);
295
+ const query = useCallback2(
296
+ (doFetchOverride, callerSignal) => {
297
+ const controller = new AbortController();
298
+ manager.replace(controller);
299
+ const composed = callerSignal ? composeAbortSignals(callerSignal, controller.signal) : { signal: controller.signal, release: () => {
300
+ } };
301
+ const effectiveSignal = composed.signal;
302
+ const p = runWithCallbacks(controller, () => doFetchOverride(effectiveSignal));
303
+ p.finally(() => composed.release()).catch(() => {
304
+ });
305
+ return p;
306
+ },
307
+ [runWithCallbacks, manager]
308
+ );
101
309
  const refetch = useCallback2(() => {
102
- setIsLoading(true);
103
310
  const controller = new AbortController();
104
311
  manager.replace(controller);
105
- doFetchWithCallbacks(controller.signal).catch(() => {
106
- }).finally(() => {
107
- if (!controller.signal.aborted) setIsLoading(false);
312
+ const p = runWithCallbacks(controller, doFetch);
313
+ p.catch(() => {
108
314
  });
109
- }, [doFetchWithCallbacks, manager]);
110
- return { isLoading, isFetching, error, setError, refetch, manager, mountRef };
315
+ return p;
316
+ }, [runWithCallbacks, manager, doFetch]);
317
+ const resetError = useCallback2(() => {
318
+ setError(null);
319
+ }, []);
320
+ const resetLoading = useCallback2(() => {
321
+ setIsLoading(false);
322
+ setIsFetching(false);
323
+ hasDataRef.current = false;
324
+ }, []);
325
+ return {
326
+ isLoading,
327
+ isFetching,
328
+ error,
329
+ setError,
330
+ refetch,
331
+ query,
332
+ resetError,
333
+ resetLoading,
334
+ manager,
335
+ mountRef
336
+ };
111
337
  }
112
- function useMutation(execute, options) {
338
+ function useMutation(execute, applyData, options) {
339
+ const [data, setData] = useState(null);
113
340
  const [isPending, setIsPending] = useState(false);
114
341
  const [error, setError] = useState(null);
115
342
  const mountRef = useMountRef();
116
343
  const { onSuccess, onSettled } = options ?? {};
344
+ const activeCountRef = useRef2(0);
345
+ const latestIdRef = useRef2(0);
117
346
  const executeMutate = useCallback2(
118
347
  async (...args) => {
348
+ const myId = ++latestIdRef.current;
349
+ activeCountRef.current += 1;
119
350
  setIsPending(true);
120
- setError(null);
351
+ if (myId === latestIdRef.current) {
352
+ setError(null);
353
+ }
121
354
  try {
122
355
  const result = await execute(...args);
123
356
  if (mountRef.current) {
124
- onSuccess?.(result);
125
- onSettled?.(result, null);
357
+ try {
358
+ onSuccess?.(result);
359
+ onSettled?.(result, null);
360
+ } catch (cbErr) {
361
+ queueMicrotask(() => {
362
+ throw cbErr;
363
+ });
364
+ }
365
+ if (myId === latestIdRef.current) {
366
+ setData(applyData(result));
367
+ }
126
368
  }
127
369
  return result;
128
370
  } catch (err) {
129
371
  const svcErr = err;
130
372
  if (mountRef.current) {
131
- setError(svcErr);
132
- onSettled?.(null, svcErr);
373
+ try {
374
+ onSettled?.(null, svcErr);
375
+ } catch (cbErr) {
376
+ queueMicrotask(() => {
377
+ throw cbErr;
378
+ });
379
+ }
380
+ if (myId === latestIdRef.current) {
381
+ setError(svcErr);
382
+ }
133
383
  }
134
384
  throw svcErr;
135
385
  } finally {
136
- if (mountRef.current) setIsPending(false);
386
+ if (activeCountRef.current > 0) activeCountRef.current -= 1;
387
+ if (mountRef.current) {
388
+ setIsPending(activeCountRef.current > 0);
389
+ }
137
390
  }
138
391
  },
139
- [execute, mountRef, onSuccess, onSettled]
392
+ [execute, applyData, mountRef, onSuccess, onSettled]
140
393
  );
141
- const reset = useCallback2(() => setError(null), []);
142
- return { isPending, error, executeMutate, reset };
394
+ const reset = useCallback2(() => {
395
+ latestIdRef.current += 1;
396
+ setData(null);
397
+ setError(null);
398
+ }, []);
399
+ return { data, isPending, error, executeMutate, reset };
143
400
  }
144
401
  function createModelHooks(config) {
145
402
  const { modelService } = config;
@@ -165,19 +422,52 @@ function createModelHooks(config) {
165
422
  const applyResult = useCallback2((res) => {
166
423
  setData(res.data);
167
424
  }, []);
425
+ let requestKey;
426
+ try {
427
+ requestKey = requestKeyFor({
428
+ select,
429
+ populate,
430
+ sort,
431
+ include,
432
+ tasks,
433
+ basicOptions,
434
+ advancedOptions,
435
+ requestConfig
436
+ });
437
+ } catch (e) {
438
+ if (e instanceof RequestKeyError) {
439
+ throw new Error(`useRead: ${e.message}`, { cause: e });
440
+ }
441
+ throw e;
442
+ }
168
443
  const doFetchById = useCallback2(
169
444
  async (targetId, signal) => {
445
+ const forwardedConfig = mergeRequestConfig(requestConfig, signal);
170
446
  if (advanced) {
171
- return await modelService.readAdvanced(
447
+ const raw2 = await modelService.readAdvanced(
172
448
  targetId,
173
449
  { select, populate, sort, include, tasks },
174
450
  advancedOptions,
175
- { ...requestConfig, signal }
451
+ forwardedConfig
176
452
  ).exec();
453
+ assertSuccess(raw2);
454
+ return raw2;
177
455
  }
178
- return await modelService.read(targetId, basicOptions, { ...requestConfig, signal }).exec();
456
+ const raw = await modelService.read(targetId, basicOptions, forwardedConfig).exec();
457
+ assertSuccess(raw);
458
+ return raw;
179
459
  },
180
- [modelService, advanced, select, populate, sort, include, tasks, basicOptions, advancedOptions, requestConfig]
460
+ // Only re-memoize when the composite key string changes. When a
461
+ // parent re-renders with structurally-equivalent inline arrays or
462
+ // objects, the key is unchanged and `doFetchById` keeps the same
463
+ // identity — the auto-effect's `deps` therefore stays identical
464
+ // and the network request is not retried. The `requestKey` is a
465
+ // structural digest of `select/populate/sort/include/tasks/
466
+ // basicOptions/advancedOptions/requestConfig`; the lint rule can-
467
+ // not see that derivation, so the missing-deps warning is
468
+ // silenced here intentionally.
469
+ // eslint-disable-next-line react-hooks/exhaustive-deps
470
+ [modelService, advanced, requestKey]
181
471
  );
182
472
  const doFetch = useCallback2(
183
473
  (signal) => {
@@ -187,28 +477,35 @@ function createModelHooks(config) {
187
477
  [doFetchById, id]
188
478
  );
189
479
  const shouldFetch = Boolean(id && enabled);
190
- const { isLoading, isFetching, error, refetch } = useAutoQuery({
480
+ const onSuccessStable = useEventCallback(onSuccess);
481
+ const onErrorStable = useEventCallback(onError);
482
+ const onSettledStable = useEventCallback(onSettled);
483
+ const {
484
+ isLoading,
485
+ isFetching,
486
+ error,
487
+ refetch,
488
+ query: runQuery,
489
+ resetError,
490
+ resetLoading
491
+ } = useAutoQuery({
191
492
  doFetch,
192
493
  applyResult,
193
494
  shouldFetch,
194
- deps: [id, enabled, advanced, select, populate, sort, include, tasks, basicOptions, advancedOptions],
195
- onSuccess,
196
- onError,
197
- onSettled
495
+ deps: [id, enabled, advanced, requestKey],
496
+ onSuccess: onSuccessStable,
497
+ onError: onErrorStable,
498
+ onSettled: onSettledStable
198
499
  });
199
500
  const query = useCallback2(
200
- async (readId) => {
201
- const res = await doFetchById(readId);
202
- applyResult(res);
203
- onSuccess?.(res);
204
- onSettled?.(res, null);
205
- return res;
206
- },
207
- [doFetchById, applyResult, onSuccess, onSettled]
501
+ (readId, callOptions) => runQuery((signal) => doFetchById(readId, signal), callOptions?.signal),
502
+ [runQuery, doFetchById]
208
503
  );
209
504
  const reset = useCallback2(() => {
210
505
  setData(initialData);
211
- }, [initialData]);
506
+ resetError();
507
+ resetLoading();
508
+ }, [initialData, resetError, resetLoading]);
212
509
  return { data, isLoading, isFetching, error, query, refetch, reset };
213
510
  }
214
511
  function useList(options = {}) {
@@ -236,84 +533,120 @@ function createModelHooks(config) {
236
533
  const [totalCount, setTotalCount] = useState(0);
237
534
  const latestDataRef = useRef2(data);
238
535
  latestDataRef.current = data;
536
+ const hasSettledRef = useRef2(false);
239
537
  const applyResult = useCallback2((res) => {
240
538
  setData(res.data);
241
539
  setTotalCount(res.totalCount);
242
540
  setPreviousData(void 0);
541
+ hasSettledRef.current = true;
243
542
  }, []);
543
+ const clearPreviousData = useCallback2(() => {
544
+ setPreviousData(void 0);
545
+ }, []);
546
+ let listParamsKey;
547
+ let filterKey;
548
+ let sortKey;
549
+ let requestKey;
550
+ try {
551
+ listParamsKey = requestKeyFor(listParams);
552
+ filterKey = requestKeyFor(filter);
553
+ sortKey = requestKeyFor(sort);
554
+ requestKey = requestKeyFor({
555
+ select,
556
+ populate,
557
+ include,
558
+ tasks,
559
+ basicOptions,
560
+ advancedOptions,
561
+ requestConfig
562
+ });
563
+ } catch (e) {
564
+ if (e instanceof RequestKeyError) {
565
+ throw new Error(`useList: ${e.message}`, { cause: e });
566
+ }
567
+ throw e;
568
+ }
244
569
  const baseFetch = useCallback2(
245
570
  async (args, signal) => {
246
- if (keepPreviousData) {
571
+ if (keepPreviousData && hasSettledRef.current) {
247
572
  setPreviousData(latestDataRef.current);
248
573
  }
574
+ const forwardedConfig = mergeRequestConfig(requestConfig, signal);
249
575
  if (advanced) {
250
- return await modelService.listAdvanced(
576
+ const raw2 = await modelService.listAdvanced(
251
577
  filter ?? {},
252
578
  { sort, select, populate, include, tasks, ...args },
253
579
  advancedOptions,
254
- { ...requestConfig, signal }
580
+ forwardedConfig
255
581
  ).exec();
582
+ assertSuccess(raw2);
583
+ return raw2;
256
584
  }
257
- return await modelService.list(args ?? listParams, basicOptions, { ...requestConfig, signal }).exec();
585
+ const raw = await modelService.list(args ?? listParams, basicOptions, forwardedConfig).exec();
586
+ assertSuccess(raw);
587
+ return raw;
258
588
  },
259
- [
260
- modelService,
261
- advanced,
262
- filter,
263
- sort,
264
- select,
265
- populate,
266
- include,
267
- tasks,
268
- listParams,
269
- basicOptions,
270
- advancedOptions,
271
- requestConfig,
272
- keepPreviousData,
273
- latestDataRef
274
- ]
589
+ // ARR-06: only re-memoize on a structural key change so an
590
+ // inline-`filter`/`sort`/`select` caller passes identity changes
591
+ // every render but `baseFetch` keeps a stable identity and the
592
+ // auto-effect does NOT refetch. `keepPreviousData` is a primitive
593
+ // boolean and participates in the key as a primitive directly.
594
+ // `modelService` is the only stable identity in this list: the
595
+ // hook lifetime is bound to a fixed `modelService`, so its
596
+ // identity is genuinely `[]`-stable for this `useCallback`.
597
+ // `latestDataRef` and `hasSettledRef` are refs whose identities
598
+ // never change; they participate in the request-time capture of
599
+ // `previousData` (ARR-08 req 1) but not in the memo identity.
600
+ // `filterKey`, `sortKey`, `requestKey` are structural digests of
601
+ // `filter`/`sort`/`{select, populate, include, tasks,
602
+ // basicOptions, advancedOptions, requestConfig}`; the lint rule
603
+ // cannot see that derivation, so the missing-deps warning is
604
+ // silenced here intentionally.
605
+ // eslint-disable-next-line react-hooks/exhaustive-deps
606
+ [modelService, advanced, filterKey, sortKey, requestKey, keepPreviousData, latestDataRef]
275
607
  );
276
- const doFetch = useCallback2((signal) => baseFetch(listParams, signal), [baseFetch, listParams]);
277
- const listParamsKey = stableStringify(listParams);
278
- const filterKey = stableStringify(filter);
279
- const sortKey = stableStringify(sort);
608
+ const doFetch = useCallback2((signal) => baseFetch(listParams, signal), [baseFetch, listParamsKey]);
280
609
  const shouldFetch = Boolean((listParams || advanced) && enabled);
281
- const { isLoading, isFetching, error, refetch } = useAutoQuery({
610
+ const onSuccessStable = useEventCallback(onSuccess);
611
+ const onErrorStable = useEventCallback(onError);
612
+ const onSettledStable = useEventCallback(onSettled);
613
+ const {
614
+ isLoading,
615
+ isFetching,
616
+ error,
617
+ refetch,
618
+ query: runQuery,
619
+ resetError,
620
+ resetLoading
621
+ } = useAutoQuery({
282
622
  doFetch,
283
623
  applyResult,
284
624
  shouldFetch,
285
- deps: [
286
- listParamsKey,
287
- filterKey,
288
- advanced,
289
- enabled,
290
- select,
291
- populate,
292
- sortKey,
293
- include,
294
- tasks,
295
- basicOptions,
296
- advancedOptions
297
- ],
298
- onSuccess,
299
- onError,
300
- onSettled
625
+ deps: [listParamsKey, filterKey, advanced, enabled, sortKey, requestKey],
626
+ onSuccess: onSuccessStable,
627
+ onError: onErrorStable,
628
+ onSettled: onSettledStable,
629
+ // ARR-08 req 1: `previousData` must be cleared on every terminal
630
+ // path, not only on success (`applyResult` clears it). The shared
631
+ // `useAutoQuery` lifecycle fires these hooks at the matching
632
+ // branches; the `[]`-stable `clearPreviousData` does not churn
633
+ // those `useCallback` identities that depend on it.
634
+ onFailed: clearPreviousData,
635
+ onAborted: clearPreviousData,
636
+ onDisabled: clearPreviousData
301
637
  });
302
638
  const query = useCallback2(
303
- async (args) => {
304
- const res = await baseFetch(args);
305
- applyResult(res);
306
- onSuccess?.(res);
307
- onSettled?.(res, null);
308
- return res;
309
- },
310
- [baseFetch, applyResult, onSuccess, onSettled]
639
+ (args, callOptions) => runQuery((signal) => baseFetch(args, signal), callOptions?.signal),
640
+ [runQuery, baseFetch]
311
641
  );
312
642
  const reset = useCallback2(() => {
313
643
  setData(initialData ?? []);
314
644
  setPreviousData(void 0);
315
645
  setTotalCount(0);
316
- }, [initialData]);
646
+ hasSettledRef.current = false;
647
+ resetError();
648
+ resetLoading();
649
+ }, [initialData, resetError, resetLoading]);
317
650
  return { data, previousData, totalCount, isLoading, isFetching, error, query, refetch, reset };
318
651
  }
319
652
  function useCreate(options = {}) {
@@ -329,7 +662,6 @@ function createModelHooks(config) {
329
662
  onError,
330
663
  onSettled
331
664
  } = options;
332
- const [data, setData] = useState(null);
333
665
  const mountRef = useMountRef();
334
666
  const execute = useCallback2(
335
667
  async (createData) => {
@@ -344,27 +676,43 @@ function createModelHooks(config) {
344
676
  } else {
345
677
  res = await modelService.create(createData, basicOptions, requestConfig).exec();
346
678
  }
347
- if (mountRef.current) setData(res.data);
679
+ assertSuccess(res);
348
680
  return res;
349
681
  },
682
+ // ARR-06: `modelService` lives in the `createModelHooks`
683
+ // closure but the lint rule's "outer scope" heuristic flags it
684
+ // as unnecessary. It IS necessary: the hook is bound to that
685
+ // specific service instance, and the closure capture is the
686
+ // documented pattern for `createModelHooks`. The same pattern
687
+ // is used in `useRead.useList.useCount.useDistinct` query hooks.
688
+ // eslint-disable-next-line react-hooks/exhaustive-deps
350
689
  [modelService, advanced, select, populate, tasks, basicOptions, advancedOptions, requestConfig, mountRef]
351
690
  );
352
- const { isPending, error, executeMutate, reset: resetError } = useMutation(execute, { onSuccess, onSettled });
691
+ const {
692
+ data,
693
+ isPending,
694
+ error,
695
+ executeMutate,
696
+ reset: resetMutation
697
+ } = useMutation(
698
+ execute,
699
+ (res) => res.data,
700
+ { onSuccess, onSettled }
701
+ );
353
702
  const mutate = useCallback2(
354
703
  async (createData) => {
355
704
  try {
356
705
  return await executeMutate(createData);
357
706
  } catch (err) {
358
- onError?.(err);
707
+ if (mountRef.current) onError?.(err);
359
708
  throw err;
360
709
  }
361
710
  },
362
- [executeMutate, onError]
711
+ [executeMutate, onError, mountRef]
363
712
  );
364
713
  const reset = useCallback2(() => {
365
- setData(null);
366
- resetError();
367
- }, [resetError]);
714
+ resetMutation();
715
+ }, [resetMutation]);
368
716
  return { data, isPending, error, mutate, reset };
369
717
  }
370
718
  function useUpdate(options = {}) {
@@ -380,7 +728,6 @@ function createModelHooks(config) {
380
728
  onError,
381
729
  onSettled
382
730
  } = options;
383
- const [data, setData] = useState(null);
384
731
  const mountRef = useMountRef();
385
732
  const execute = useCallback2(
386
733
  async (updateId, updateData) => {
@@ -396,27 +743,43 @@ function createModelHooks(config) {
396
743
  } else {
397
744
  res = await modelService.update(updateId, updateData, basicOptions, requestConfig).exec();
398
745
  }
399
- if (mountRef.current) setData(res.data);
746
+ assertSuccess(res);
400
747
  return res;
401
748
  },
749
+ // ARR-06: `modelService` lives in the `createModelHooks`
750
+ // closure but the lint rule's "outer scope" heuristic flags it
751
+ // as unnecessary. It IS necessary: the hook is bound to that
752
+ // specific service instance, and the closure capture is the
753
+ // documented pattern for `createModelHooks`. The same pattern
754
+ // is used in `useRead.useList.useCount.useDistinct` query hooks.
755
+ // eslint-disable-next-line react-hooks/exhaustive-deps
402
756
  [modelService, advanced, select, populate, tasks, basicOptions, advancedOptions, requestConfig, mountRef]
403
757
  );
404
- const { isPending, error, executeMutate, reset: resetError } = useMutation(execute, { onSuccess, onSettled });
758
+ const {
759
+ data,
760
+ isPending,
761
+ error,
762
+ executeMutate,
763
+ reset: resetMutation
764
+ } = useMutation(
765
+ execute,
766
+ (res) => res.data,
767
+ { onSuccess, onSettled }
768
+ );
405
769
  const mutate = useCallback2(
406
770
  async (updateId, updateData) => {
407
771
  try {
408
772
  return await executeMutate(updateId, updateData);
409
773
  } catch (err) {
410
- onError?.(err);
774
+ if (mountRef.current) onError?.(err);
411
775
  throw err;
412
776
  }
413
777
  },
414
- [executeMutate, onError]
778
+ [executeMutate, onError, mountRef]
415
779
  );
416
780
  const reset = useCallback2(() => {
417
- setData(null);
418
- resetError();
419
- }, [resetError]);
781
+ resetMutation();
782
+ }, [resetMutation]);
420
783
  return { data, isPending, error, mutate, reset };
421
784
  }
422
785
  function useUpsert(options = {}) {
@@ -432,7 +795,6 @@ function createModelHooks(config) {
432
795
  onError,
433
796
  onSettled
434
797
  } = options;
435
- const [data, setData] = useState(null);
436
798
  const mountRef = useMountRef();
437
799
  const execute = useCallback2(
438
800
  async (upsertData) => {
@@ -447,50 +809,83 @@ function createModelHooks(config) {
447
809
  } else {
448
810
  res = await modelService.upsert(upsertData, basicOptions, requestConfig).exec();
449
811
  }
450
- if (mountRef.current) setData(res.data);
812
+ assertSuccess(res);
451
813
  return res;
452
814
  },
815
+ // ARR-06: `modelService` lives in the `createModelHooks`
816
+ // closure but the lint rule's "outer scope" heuristic flags it
817
+ // as unnecessary. It IS necessary: the hook is bound to that
818
+ // specific service instance, and the closure capture is the
819
+ // documented pattern for `createModelHooks`. The same pattern
820
+ // is used in `useRead.useList.useCount.useDistinct` query hooks.
821
+ // eslint-disable-next-line react-hooks/exhaustive-deps
453
822
  [modelService, advanced, select, populate, tasks, basicOptions, advancedOptions, requestConfig, mountRef]
454
823
  );
455
- const { isPending, error, executeMutate, reset: resetError } = useMutation(execute, { onSuccess, onSettled });
824
+ const {
825
+ data,
826
+ isPending,
827
+ error,
828
+ executeMutate,
829
+ reset: resetMutation
830
+ } = useMutation(
831
+ execute,
832
+ (res) => res.data,
833
+ { onSuccess, onSettled }
834
+ );
456
835
  const mutate = useCallback2(
457
836
  async (upsertData) => {
458
837
  try {
459
838
  return await executeMutate(upsertData);
460
839
  } catch (err) {
461
- onError?.(err);
840
+ if (mountRef.current) onError?.(err);
462
841
  throw err;
463
842
  }
464
843
  },
465
- [executeMutate, onError]
844
+ [executeMutate, onError, mountRef]
466
845
  );
467
846
  const reset = useCallback2(() => {
468
- setData(null);
469
- resetError();
470
- }, [resetError]);
847
+ resetMutation();
848
+ }, [resetMutation]);
471
849
  return { data, isPending, error, mutate, reset };
472
850
  }
473
851
  function useDelete(options = {}) {
474
852
  const { requestConfig, onSuccess, onError, onSettled } = options;
853
+ const mountRef = useMountRef();
475
854
  const execute = useCallback2(
476
855
  async (deleteId) => {
477
856
  const res = await modelService.delete(deleteId, requestConfig).exec();
857
+ assertSuccess(res);
478
858
  return res;
479
859
  },
860
+ // ARR-06: see the `useCreate.execute` disable rationale — same
861
+ // `createModelHooks` closure-capture pattern.
862
+ // eslint-disable-next-line react-hooks/exhaustive-deps
480
863
  [modelService, requestConfig]
481
864
  );
482
- const { isPending, error, executeMutate, reset } = useMutation(execute, { onSuccess, onSettled });
865
+ const {
866
+ isPending,
867
+ error,
868
+ executeMutate,
869
+ reset: resetMutation
870
+ } = useMutation(
871
+ execute,
872
+ () => null,
873
+ { onSuccess, onSettled }
874
+ );
483
875
  const mutate = useCallback2(
484
876
  async (deleteId) => {
485
877
  try {
486
878
  return await executeMutate(deleteId);
487
879
  } catch (err) {
488
- onError?.(err);
880
+ if (mountRef.current) onError?.(err);
489
881
  throw err;
490
882
  }
491
883
  },
492
- [executeMutate, onError]
884
+ [executeMutate, onError, mountRef]
493
885
  );
886
+ const reset = useCallback2(() => {
887
+ resetMutation();
888
+ }, [resetMutation]);
494
889
  return { isPending, error, mutate, reset };
495
890
  }
496
891
  function useCount(options = {}) {
@@ -499,36 +894,65 @@ function createModelHooks(config) {
499
894
  const applyResult = useCallback2((res) => {
500
895
  setData(res.data);
501
896
  }, []);
897
+ let filterKey;
898
+ let requestKey;
899
+ try {
900
+ filterKey = requestKeyFor(filter);
901
+ requestKey = requestKeyFor(requestConfig);
902
+ } catch (e) {
903
+ if (e instanceof RequestKeyError) {
904
+ throw new Error(`useCount: ${e.message}`, { cause: e });
905
+ }
906
+ throw e;
907
+ }
502
908
  const doFetch = useCallback2(
503
909
  async (signal) => {
910
+ const forwardedConfig = mergeRequestConfig(requestConfig, signal);
504
911
  if (advanced) {
505
- return await modelService.countAdvanced(filter ?? {}, void 0, { ...requestConfig, signal }).exec();
912
+ const raw2 = await modelService.countAdvanced(filter ?? {}, forwardedConfig).exec();
913
+ assertSuccess(raw2);
914
+ return raw2;
506
915
  }
507
- return await modelService.count({ ...requestConfig, signal }).exec();
916
+ const raw = await modelService.count(forwardedConfig).exec();
917
+ assertSuccess(raw);
918
+ return raw;
508
919
  },
509
- [modelService, advanced, filter, requestConfig]
920
+ // ARR-06: `filterKey`, `requestKey` are structural digests of
921
+ // `filter` and `requestConfig`; the lint rule cannot see the
922
+ // derivation, so silence the missing-deps warning.
923
+ // eslint-disable-next-line react-hooks/exhaustive-deps
924
+ [modelService, advanced, filterKey, requestKey]
510
925
  );
511
- const filterKey = stableStringify(filter);
512
- const { isLoading, error, refetch } = useAutoQuery({
926
+ const onSuccessStable = useEventCallback(onSuccess);
927
+ const onErrorStable = useEventCallback(onError);
928
+ const onSettledStable = useEventCallback(onSettled);
929
+ const {
930
+ isLoading,
931
+ isFetching,
932
+ error,
933
+ refetch,
934
+ query: runQuery,
935
+ resetError,
936
+ resetLoading
937
+ } = useAutoQuery({
513
938
  doFetch,
514
939
  applyResult,
515
940
  shouldFetch: enabled,
516
- deps: [enabled, advanced, filterKey],
517
- onSuccess,
518
- onError,
519
- onSettled
941
+ deps: [enabled, advanced, filterKey, requestKey],
942
+ onSuccess: onSuccessStable,
943
+ onError: onErrorStable,
944
+ onSettled: onSettledStable
520
945
  });
521
- const query = useCallback2(async () => {
522
- const res = await doFetch();
523
- applyResult(res);
524
- onSuccess?.(res);
525
- onSettled?.(res, null);
526
- return res;
527
- }, [doFetch, applyResult, onSuccess, onSettled]);
946
+ const query = useCallback2(
947
+ (callOptions) => runQuery(doFetch, callOptions?.signal),
948
+ [runQuery, doFetch]
949
+ );
528
950
  const reset = useCallback2(() => {
529
951
  setData(null);
530
- }, []);
531
- return { data, isLoading, error, query, refetch, reset };
952
+ resetError();
953
+ resetLoading();
954
+ }, [resetError, resetLoading]);
955
+ return { data, isLoading, isFetching, error, query, refetch, reset };
532
956
  }
533
957
  function useDistinct(options) {
534
958
  const { field, conditions, enabled = true, requestConfig, onSuccess, onError, onSettled } = options;
@@ -536,36 +960,65 @@ function createModelHooks(config) {
536
960
  const applyResult = useCallback2((res) => {
537
961
  setData(res.data);
538
962
  }, []);
963
+ let conditionsKey;
964
+ let requestKey;
965
+ try {
966
+ conditionsKey = requestKeyFor(conditions);
967
+ requestKey = requestKeyFor(requestConfig);
968
+ } catch (e) {
969
+ if (e instanceof RequestKeyError) {
970
+ throw new Error(`useDistinct: ${e.message}`, { cause: e });
971
+ }
972
+ throw e;
973
+ }
539
974
  const doFetch = useCallback2(
540
975
  async (signal) => {
976
+ const forwardedConfig = mergeRequestConfig(requestConfig, signal);
541
977
  if (conditions && Object.keys(conditions).length > 0) {
542
- return await modelService.distinctAdvanced(field, conditions, { ...requestConfig, signal }).exec();
978
+ const raw2 = await modelService.distinctAdvanced(field, conditions, forwardedConfig).exec();
979
+ assertSuccess(raw2);
980
+ return raw2;
543
981
  }
544
- return await modelService.distinct(field, { ...requestConfig, signal }).exec();
982
+ const raw = await modelService.distinct(field, forwardedConfig).exec();
983
+ assertSuccess(raw);
984
+ return raw;
545
985
  },
546
- [modelService, field, conditions, requestConfig]
986
+ // ARR-06: `conditionsKey`, `requestKey` are structural digests
987
+ // of `conditions` and `requestConfig`; the lint rule cannot see
988
+ // the derivation, so silence the missing-deps warning.
989
+ // eslint-disable-next-line react-hooks/exhaustive-deps
990
+ [modelService, field, conditionsKey, requestKey]
547
991
  );
548
- const conditionsKey = stableStringify(conditions);
549
- const { isLoading, error, refetch } = useAutoQuery({
992
+ const onSuccessStable = useEventCallback(onSuccess);
993
+ const onErrorStable = useEventCallback(onError);
994
+ const onSettledStable = useEventCallback(onSettled);
995
+ const {
996
+ isLoading,
997
+ isFetching,
998
+ error,
999
+ refetch,
1000
+ query: runQuery,
1001
+ resetError,
1002
+ resetLoading
1003
+ } = useAutoQuery({
550
1004
  doFetch,
551
1005
  applyResult,
552
1006
  shouldFetch: enabled,
553
- deps: [enabled, field, conditionsKey],
554
- onSuccess,
555
- onError,
556
- onSettled
1007
+ deps: [enabled, field, conditionsKey, requestKey],
1008
+ onSuccess: onSuccessStable,
1009
+ onError: onErrorStable,
1010
+ onSettled: onSettledStable
557
1011
  });
558
- const query = useCallback2(async () => {
559
- const res = await doFetch();
560
- applyResult(res);
561
- onSuccess?.(res);
562
- onSettled?.(res, null);
563
- return res;
564
- }, [doFetch, applyResult, onSuccess, onSettled]);
1012
+ const query = useCallback2(
1013
+ (callOptions) => runQuery(doFetch, callOptions?.signal),
1014
+ [runQuery, doFetch]
1015
+ );
565
1016
  const reset = useCallback2(() => {
566
1017
  setData(null);
567
- }, []);
568
- return { data, isLoading, error, query, refetch, reset };
1018
+ resetError();
1019
+ resetLoading();
1020
+ }, [resetError, resetLoading]);
1021
+ return { data, isLoading, isFetching, error, query, refetch, reset };
569
1022
  }
570
1023
  return {
571
1024
  useRead,
@@ -579,5 +1032,7 @@ function createModelHooks(config) {
579
1032
  };
580
1033
  }
581
1034
  export {
582
- createModelHooks
1035
+ RequestKeyError,
1036
+ createModelHooks,
1037
+ requestKeyFor
583
1038
  };