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