@web-ts-toolkit/access-router-react 0.38.0 → 0.39.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 +29 -13
  2. package/index.d.mts +42 -39
  3. package/index.d.ts +42 -39
  4. package/index.js +213 -167
  5. package/index.mjs +213 -167
  6. package/package.json +3 -3
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  React hooks for `@web-ts-toolkit/access-router-client` model services.
4
4
 
5
- `createModelHooks(modelService)` binds one `ModelService` to eight hooks covering read, list, count, distinct, create, update, upsert, and delete. Each hook instance owns its own local state — there is **no shared cache, no deduplication, no invalidation, and no retry**. Two components calling `useRead({ id: '1' })` against the same `ModelService` issue two independent requests and store two independent copies of the result. If you need cache orchestration, layer these services underneath a query library.
5
+ `createModelHooks({ modelService })` binds one `ModelService` to eight hooks covering read, list, count, distinct, create, update, upsert, and delete. Each hook instance owns its own local state — there is **no shared cache, no deduplication, no invalidation, and no retry**. Two components calling `useRead({ id: '1' })` against the same `ModelService` issue two independent requests and store two independent copies of the result. If you need cache orchestration, layer these services underneath a query library.
6
6
 
7
7
  ## Installation
8
8
 
@@ -15,6 +15,8 @@ Peer dependencies:
15
15
  - `react ^18 || ^19` — verified by a React 18 lane in this package's own test suite (React 19 remains the primary lane)
16
16
  - `@web-ts-toolkit/access-router-client`
17
17
 
18
+ Published builds target `ES2022`. Direct Node consumers should use Node `>=20`; browser apps can bundle the package as long as their toolchain supports ES2022 output.
19
+
18
20
  ## Factory
19
21
 
20
22
  ```ts
@@ -97,7 +99,7 @@ const { data, isLoading, isFetching, error, query, refetch, reset } = useRead({
97
99
  - `id` controls auto-fetching. Set `enabled: false` (or remove `id`) to disable.
98
100
  - `advanced: true` switches to `readAdvanced(...)`, which forwards `select`, `populate`, `sort`, `include`, and `tasks`.
99
101
  - `onSuccess`, `onError`, and `onSettled` are invocation observers and are **not** part of the effect dependency key; re-rendering a parent with a fresh inline arrow every render does not refetch (see Dependency-Key Policy below).
100
- - `query(id, { signal })` re-runs the read imperatively; `refetch()` re-runs with the current options. Both return a promise that resolves the `ServiceError` on failure.
102
+ - `query(id, { signal })` re-runs the read imperatively; `refetch()` re-runs with the current options. Both return a promise that resolves with the response or rejects with a `ServiceError` on failure.
101
103
 
102
104
  ### `useList`
103
105
 
@@ -140,7 +142,7 @@ If `conditions` is empty or omitted, the hook falls back to the basic `distinct(
140
142
 
141
143
  ## Mutation Hooks
142
144
 
143
- `useCreate`, `useUpdate`, `useUpsert`, and `useDelete` expose `mutate(...)`, `isPending`, `error`, and `reset()`. The first three also expose `data` (the last returned projected model). Each `mutate(...)` call returns a promise that resolves the response, or rejects with a `ServiceError` on failure.
145
+ `useCreate`, `useUpdate`, `useUpsert`, and `useDelete` expose `mutate(...)`, `isPending`, `error`, and `reset()`. The first three also expose `data` (the last returned projected model). Each `mutate(...)` call returns a promise that resolves the response, or rejects with a `ServiceError` on failure. Mutation input types are inferred from the bound `ModelService<T, TCreateInput, TUpdateInput, TUpsertInput>` generics. `useCreate().mutate(...)` is intentionally single-record-only and rejects array input; call `modelService.create([...])` directly when you need bulk create.
144
146
 
145
147
  ### `useCreate`
146
148
 
@@ -229,12 +231,18 @@ function FailureExample() {
229
231
 
230
232
  A dependency change, `query()`/`refetch()` invocation, or unmount aborts the in-flight request and replaces it. Cancellation is authoritative: an aborted request never writes `error`, never fires `onError` or `onSettled`, and converges `isLoading`/`isFetching`/`isPending` to false. The hooks decide cancellation on `signal.aborted` rather than `instanceof DOMException`, so axios `CanceledError`, `Error('Canceled')` with `code: 'ERR_CANCELED'`, or any other transport-specific cancellation shape is handled uniformly.
231
233
 
232
- For manual `query()` calls, pass `{ signal }` to compose a caller signal with the hook's internal controller. Aborting either source cancels the effective request.
234
+ For manual `query()` calls, pass `{ signal }` to compose a caller signal with the hook's `requestConfig.signal` and internal controller. Aborting any source cancels the effective request.
233
235
 
234
236
  ```tsx
235
237
  const controller = new AbortController();
236
- const result = await query('org_123', { signal: controller.signal });
237
- controller.abort(); // cancels the in-flight manual request
238
+ const pending = query('org_123', { signal: controller.signal });
239
+ controller.abort(); // cancels the in-flight manual request while it is still pending
240
+
241
+ try {
242
+ await pending;
243
+ } catch (error) {
244
+ console.error('manual query cancelled', error);
245
+ }
238
246
  ```
239
247
 
240
248
  ### `previousData` lifecycle (`useList` only)
@@ -249,10 +257,10 @@ controller.abort(); // cancels the in-flight manual request
249
257
 
250
258
  `reset()` is a synchronous state-clear, not a cancellation:
251
259
 
252
- - Query `reset()` clears `data`/`error`/`isLoading`/`isFetching` (and `previousData` for `useList`).
260
+ - Query `reset()` clears `data`/`error`/`isLoading`/`isFetching` (and `previousData` for `useList`) and invalidates the current query owner's right to publish settlement. A pre-reset success, failure, rejection, or abort may still finish at the transport layer, but it is stale for hook state and callbacks.
253
261
  - Mutation `reset()` clears `data`/`error` and bumps the latest-invocation token. Any already-running mutation loses its claim on the shared `data`/`error` state — when it later settles, its per-invocation `onSuccess`/`onSettled` still fire, but it cannot repopulate the cleared `data`/`error`. `isPending` remains true until the active count reaches zero; `reset` does not implicitly cancel.
254
262
 
255
- If you need to cancel an in-flight query, drop `id`/`listParams` or set `enabled: false` rather than calling `reset`.
263
+ After query `reset()`, `isFetching` reflects authoritative hook activity, not physical transport activity, so it becomes false immediately even if the abandoned request is still finishing underneath. If you need to cancel an in-flight query, drop `id`/`listParams` or set `enabled: false` rather than calling `reset`.
256
264
 
257
265
  ### `refetch()` and `query()`
258
266
 
@@ -271,9 +279,13 @@ function Save() {
271
279
  const { mutate, isPending } = useUpdate({ advanced: true, select: ['name'] as const });
272
280
 
273
281
  const saveTwice = async () => {
274
- const [second] = await Promise.all([mutate('org_1', { name: 'A' }), mutate('org_1', { name: 'B' })]);
275
- // `second.data` reflects whoever settled last as the latest-invocation.
276
- return second.data;
282
+ const [firstResult, secondResult] = await Promise.all([
283
+ mutate('org_1', { name: 'A' }),
284
+ mutate('org_1', { name: 'B' }),
285
+ ]);
286
+ // Promise.all preserves invocation order. Hook state still follows the latest invocation.
287
+ console.log(firstResult.data?.name, secondResult.data?.name);
288
+ return secondResult.data;
277
289
  };
278
290
 
279
291
  return (
@@ -316,13 +328,17 @@ A literal `select` requires `advanced: true` to actually reach the server's narr
316
328
 
317
329
  ## Dependency-Key Policy
318
330
 
319
- The query hooks build one structural key from every request-affecting option and use that key as the React effect dependency. Inline array/object literals at the call site are safe: two `select: ['name']` arrays written at every render produce the same key, so they do not trigger an extra refetch. `Date` compares by instant (`d:<.getTime()>`) and never collides with an ISO-string filter that happens to look like the date. `requireKeyFor` throws a documented `RequestKeyError` (re-thrown by the hook as an `Error` with `cause`) for values it cannot represent deterministically: `bigint`, `function`, `symbol` (and symbol-keyed properties), cycles, accessor properties, and built-in instances such as `RegExp`, `Map`, `Set`, `URL`, `Error`, or non-`Object.prototype` class instances. `Date` and `Object.create(null)` are supported. You can import the helper to construct or validate keys yourself:
331
+ The query hooks build one structural key from every request-affecting option and use that key as the React effect dependency. Inline array/object literals at the call site are safe: two `select: ['name']` arrays written at every render produce the same key, so they do not trigger an extra refetch. `Date` compares by instant (`d:<.getTime()>`) and never collides with an ISO-string filter that happens to look like the date. `requestKeyFor` throws a documented `RequestKeyError`; query hooks catch that, rethrow a plain `Error` with the original `RequestKeyError` in `cause`, and interrupt render before any auto-fetch effect runs. Unsupported values include `bigint`, `function`, `symbol` (and symbol-keyed properties), cycles, accessor properties, and built-in instances such as `RegExp`, `Map`, `Set`, `URL`, `Error`, or non-`Object.prototype` class instances. `Date` and `Object.create(null)` are supported.
332
+
333
+ Request-key work is intentionally bounded. One `requestKeyFor(...)` call accepts at most 64 nested array/object levels, 20,000 first-visit nodes, and 200,000 serialized key characters; inputs beyond those limits throw `RequestKeyError` instead of overflowing the stack, partially truncating the key, or silently colliding. Keep request-key inputs as plain, stable, reasonably small wire data. Repeated object references may be reused within a single `requestKeyFor(...)` call, but there is no global cache retaining caller objects across renders. You can import the helper to construct or validate keys yourself:
320
334
 
321
335
  ```ts
322
336
  import { requestKeyFor, RequestKeyError } from '@web-ts-toolkit/access-router-react';
323
337
 
324
338
  const key = requestKeyFor({ filter: { status: 'active', since: new Date('2026-01-01') } });
325
339
 
340
+ declare const someUserSuppliedFilter: unknown;
341
+
326
342
  try {
327
343
  requestKeyFor(someUserSuppliedFilter);
328
344
  } catch (e) {
@@ -344,7 +360,7 @@ try {
344
360
  ## Notes
345
361
 
346
362
  - These hooks do not implement shared caching, deduplication, invalidation, retry, or background revalidation. They are thin stateful wrappers over `ModelService` from `@web-ts-toolkit/access-router-client`. If you need cache orchestration, use these services underneath a query library.
347
- - `requestConfig` is forwarded to the underlying client request via a fresh shallow copy on every request; the caller's `requestConfig` object, its `headers`, and other fields are not mutated. The hook's internal `requestConfig.signal` is composed with the caller-supplied `query()` `options.signal` and the hook-owned controller signal — aborting any source cancels the effective request.
363
+ - `requestConfig` is forwarded to the underlying client request via a fresh shallow copy on every request; the caller's `requestConfig` object, its `headers`, and other fields are not mutated. `requestConfig.signal` is composed with the caller-supplied `query()` `options.signal` and the hook-owned controller signal, and that one effective signal is used for both transport cancellation and hook settlement classification. Replacing only `requestConfig.signal` does not trigger an automatic refetch.
348
364
 
349
365
  ## Documentation
350
366
 
package/index.d.mts CHANGED
@@ -1,4 +1,4 @@
1
- import { Document, Projection, SelectedKeys, ListModelResponse, ResolvedSelectedShape, ModelResponse, Model, FilterQuery, Response, ServiceError, CreateAdvancedArgs, CreateOptions, CreateAdvancedOptions, ListArgs, ListAdvancedArgs, ListOptions, ListAdvancedOptions, ReadAdvancedArgs, ReadOptions, ReadAdvancedOptions, UpdateAdvancedArgs, UpdateOptions, UpdateAdvancedOptions, UpsertAdvancedArgs, UpsertOptions, UpsertAdvancedOptions, ModelService } from '@web-ts-toolkit/access-router-client';
1
+ import { Document, Projection, SelectedKeys, ListModelResponse, ResolvedSelectedShape, ModelResponse, Model, FilterQuery, Response, ServiceError, CreateAdvancedArgs, CreateOptions, CreateAdvancedOptions, ModelMutationInput, ListArgs, ListAdvancedArgs, ListOptions, ListAdvancedOptions, ReadAdvancedArgs, ReadOptions, ReadAdvancedOptions, UpdateAdvancedArgs, UpdateOptions, UpdateAdvancedOptions, UpsertAdvancedArgs, UpsertOptions, UpsertAdvancedOptions, ModelService } from '@web-ts-toolkit/access-router-client';
2
2
 
3
3
  interface RequestConfig {
4
4
  signal?: AbortSignal;
@@ -7,12 +7,9 @@ interface RequestConfig {
7
7
  }
8
8
  /**
9
9
  * Optional per-call overrides for imperative `query()` invocations
10
- * (Task ARR-05). The `signal` field is composed with the hook's internal
11
- * controller signal — aborting either source cancels the effective
12
- * request. Manual `query()` paths honor the caller signal even when the
13
- * hook's own internal controller is not strictly required for the
14
- * request (e.g. a one-shot manual read where the caller is the sole
15
- * cancellation source).
10
+ * (Task ARR-H01). The `signal` field is composed with the hook-owned
11
+ * controller signal and the current hook-options `requestConfig.signal`.
12
+ * Aborting any source cancels the effective request.
16
13
  */
17
14
  interface QueryCallOptions {
18
15
  signal?: AbortSignal;
@@ -98,6 +95,7 @@ type ProjectedListModelResponse<T extends Document, TSelect extends Projection>
98
95
  interface UseBaseOptions {
99
96
  requestConfig?: RequestConfig;
100
97
  }
98
+ type SingleMutationInput<TInput extends object> = TInput extends readonly unknown[] ? never : TInput;
101
99
  interface UseReadQueryOptions<T extends Document, TSelect extends Projection = Projection> extends UseBaseOptions {
102
100
  id?: string;
103
101
  advanced?: boolean;
@@ -136,11 +134,8 @@ interface UseReadQueryResult<T extends Document, TSelect extends Projection = Pr
136
134
  /**
137
135
  * Re-run the read for `id` via the unified query lifecycle. Accepts an
138
136
  * optional per-call {@link QueryCallOptions} whose `signal` is composed
139
- * with the hook's internal controller signal — aborting either source
140
- * cancels the request (Task ARR-05 req 4). Per-call `query()` does NOT
141
- * reuse the caller's hook-options `requestConfig.signal`; tests that
142
- * need a caller signal on the manual path must pass it via the options
143
- * argument so the composition boundary is explicit.
137
+ * with the hook-owned controller signal and the current hook-options
138
+ * `requestConfig.signal` — aborting any source cancels the request.
144
139
  */
145
140
  query: (id: string, options?: QueryCallOptions) => Promise<ProjectedModelResponse<T, TSelect>>;
146
141
  refetch: () => Promise<ProjectedModelResponse<T, TSelect>>;
@@ -184,8 +179,8 @@ interface UseListQueryResult<T extends Document, TSelect extends Projection = Pr
184
179
  * Re-run the list for `args` (or the configured `listParams`) via the
185
180
  * unified query lifecycle. Accepts an optional per-call
186
181
  * {@link QueryCallOptions} whose `signal` is composed with the hook's
187
- * internal controller signal — aborting either source cancels the
188
- * request (Task ARR-05 req 4).
182
+ * controller signal and the current hook-options `requestConfig.signal`
183
+ * — aborting any source cancels the request.
189
184
  */
190
185
  query: (args?: ListArgs, options?: QueryCallOptions) => Promise<ProjectedListModelResponse<T, TSelect>>;
191
186
  refetch: () => Promise<ProjectedListModelResponse<T, TSelect>>;
@@ -210,11 +205,11 @@ interface UseCreateMutateOptions<T extends Document, TSelect extends Projection
210
205
  onError?: (error: ServiceError) => void;
211
206
  onSettled?: (result: ProjectedModelResponse<T, TSelect> | null, error: ServiceError | null) => void;
212
207
  }
213
- interface UseCreateMutateResult<T extends Document, TSelect extends Projection = Projection> {
208
+ interface UseCreateMutateResult<T extends Document, TSelect extends Projection = Projection, TCreateInput extends object = ModelMutationInput<T>> {
214
209
  data: ProjectedShape<T, TSelect> | null;
215
210
  isPending: boolean;
216
211
  error: ServiceError | null;
217
- mutate: (data: object) => Promise<ProjectedModelResponse<T, TSelect>>;
212
+ mutate: (data: SingleMutationInput<TCreateInput>) => Promise<ProjectedModelResponse<T, TSelect>>;
218
213
  reset: () => void;
219
214
  }
220
215
  interface UseUpdateMutateOptions<T extends Document, TSelect extends Projection = Projection> extends UseBaseOptions {
@@ -232,11 +227,11 @@ interface UseUpdateMutateOptions<T extends Document, TSelect extends Projection
232
227
  onError?: (error: ServiceError) => void;
233
228
  onSettled?: (result: ProjectedModelResponse<T, TSelect> | null, error: ServiceError | null) => void;
234
229
  }
235
- interface UseUpdateMutateResult<T extends Document, TSelect extends Projection = Projection> {
230
+ interface UseUpdateMutateResult<T extends Document, TSelect extends Projection = Projection, TUpdateInput extends object = ModelMutationInput<T>> {
236
231
  data: ProjectedShape<T, TSelect> | null;
237
232
  isPending: boolean;
238
233
  error: ServiceError | null;
239
- mutate: (id: string, data: object) => Promise<ProjectedModelResponse<T, TSelect>>;
234
+ mutate: (id: string, data: TUpdateInput) => Promise<ProjectedModelResponse<T, TSelect>>;
240
235
  reset: () => void;
241
236
  }
242
237
  interface UseUpsertMutateOptions<T extends Document, TSelect extends Projection = Projection> extends UseBaseOptions {
@@ -254,11 +249,11 @@ interface UseUpsertMutateOptions<T extends Document, TSelect extends Projection
254
249
  onError?: (error: ServiceError) => void;
255
250
  onSettled?: (result: ProjectedModelResponse<T, TSelect> | null, error: ServiceError | null) => void;
256
251
  }
257
- interface UseUpsertMutateResult<T extends Document, TSelect extends Projection = Projection> {
252
+ interface UseUpsertMutateResult<T extends Document, TSelect extends Projection = Projection, TUpsertInput extends object = ModelMutationInput<T>> {
258
253
  data: ProjectedShape<T, TSelect> | null;
259
254
  isPending: boolean;
260
255
  error: ServiceError | null;
261
- mutate: (data: object) => Promise<ProjectedModelResponse<T, TSelect>>;
256
+ mutate: (data: TUpsertInput) => Promise<ProjectedModelResponse<T, TSelect>>;
262
257
  reset: () => void;
263
258
  }
264
259
  interface UseDeleteMutateOptions extends UseBaseOptions {
@@ -317,24 +312,30 @@ interface UseDistinctQueryResult {
317
312
  reset: () => void;
318
313
  }
319
314
 
320
- /**
321
- * Creates query and mutation hooks bound to one `ModelService<T>`.
322
- *
323
- * @example
324
- * const { useList, useCreate } = createModelHooks({ modelService });
325
- */
326
- declare function createModelHooks<T extends Document>(config: {
327
- modelService: ModelService<T>;
328
- }): {
315
+ type ServiceDocument<TService extends ModelService<Document, object, object, object>> = TService extends ModelService<infer TDocument, object, object, object> ? TDocument : never;
316
+ type ServiceCreateInput<TService extends ModelService<Document, object, object, object>> = TService extends ModelService<Document, infer TInput, object, object> ? TInput : never;
317
+ type ServiceUpdateInput<TService extends ModelService<Document, object, object, object>> = TService extends ModelService<Document, object, infer TInput, object> ? TInput : never;
318
+ type ServiceUpsertInput<TService extends ModelService<Document, object, object, object>> = TService extends ModelService<Document, object, object, infer TInput> ? TInput : never;
319
+ type SingleCreateInput<TInput extends object> = TInput extends readonly unknown[] ? never : TInput;
320
+ type CreateModelHooksResult<T extends Document, TCreateInput extends object, TUpdateInput extends object, TUpsertInput extends object> = {
329
321
  useRead: <TSelect extends Projection = Projection>(options?: UseReadQueryOptions<T, TSelect>) => UseReadQueryResult<T, TSelect>;
330
322
  useList: <TSelect extends Projection = Projection>(options?: UseListQueryOptions<T, TSelect>) => UseListQueryResult<T, TSelect>;
331
- useCreate: <TSelect extends Projection = Projection>(options?: UseCreateMutateOptions<T, TSelect>) => UseCreateMutateResult<T, TSelect>;
332
- useUpdate: <TSelect extends Projection = Projection>(options?: UseUpdateMutateOptions<T, TSelect>) => UseUpdateMutateResult<T, TSelect>;
333
- useUpsert: <TSelect extends Projection = Projection>(options?: UseUpsertMutateOptions<T, TSelect>) => UseUpsertMutateResult<T, TSelect>;
323
+ useCreate: <TSelect extends Projection = Projection>(options?: UseCreateMutateOptions<T, TSelect>) => UseCreateMutateResult<T, TSelect, SingleCreateInput<TCreateInput>>;
324
+ useUpdate: <TSelect extends Projection = Projection>(options?: UseUpdateMutateOptions<T, TSelect>) => UseUpdateMutateResult<T, TSelect, TUpdateInput>;
325
+ useUpsert: <TSelect extends Projection = Projection>(options?: UseUpsertMutateOptions<T, TSelect>) => UseUpsertMutateResult<T, TSelect, TUpsertInput>;
334
326
  useDelete: (options?: UseDeleteMutateOptions) => UseDeleteMutateResult;
335
327
  useCount: (options?: UseCountQueryOptions<T>) => UseCountQueryResult;
336
328
  useDistinct: (options: UseDistinctQueryOptions<T>) => UseDistinctQueryResult;
337
329
  };
330
+ /**
331
+ * Creates query and mutation hooks bound to one `ModelService<T>`.
332
+ *
333
+ * @example
334
+ * const { useList, useCreate } = createModelHooks({ modelService });
335
+ */
336
+ declare function createModelHooks<TService extends ModelService<Document, object, object, object>>(config: {
337
+ modelService: TService;
338
+ }): CreateModelHooksResult<ServiceDocument<TService>, ServiceCreateInput<TService>, ServiceUpdateInput<TService>, ServiceUpsertInput<TService>>;
338
339
 
339
340
  /**
340
341
  * Error thrown by {@link requestKeyFor} when it encounters a value it
@@ -367,13 +368,12 @@ declare function createModelHooks<T extends Document>(config: {
367
368
  * a future consumer cannot quietly rely on the current
368
369
  * (unspecified) `toString()` shape.
369
370
  *
370
- * The thrown error is a recoverable programming error: the hook surface
371
- * catches `RequestKeyError` from the dependency-key construction path so
372
- * a user-supplied filter with an unsupported value surfaces as a hook
373
- * `error` (the relevant query's `onError` fires once with the
374
- * `RequestKeyError`-as-`ServiceError` payload) rather than crashing the
375
- * render. The throw is the documented contract; testing covers each
376
- * category directly.
371
+ * The thrown error is a recoverable programming error: query hooks catch
372
+ * `RequestKeyError` while building their structural dependency key,
373
+ * rethrow a plain `Error` with the original `RequestKeyError` in
374
+ * `cause`, and interrupt render before any auto-fetch effect runs. The
375
+ * throw is the documented contract; testing covers each category
376
+ * directly.
377
377
  */
378
378
  declare class RequestKeyError extends Error {
379
379
  constructor(message: string);
@@ -403,6 +403,9 @@ declare class RequestKeyError extends Error {
403
403
  * properties) map to `{<key(sorted)!:<key(value)>!...}` recursively.
404
404
  * The key list is sorted, so two structurally equivalent objects
405
405
  * produce the same string regardless of insertion order.
406
+ * - Traversal is bounded: request keys reject inputs deeper than 64
407
+ * nested array/object levels, inputs that require more than 20,000
408
+ * first-visit nodes, or outputs longer than 200,000 characters.
406
409
  *
407
410
  * Unsupported values — `bigint`, `function`, `symbol`, accessor
408
411
  * properties, cycles, and non-plain built-in objects (`RegExp`,
package/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { Document, Projection, SelectedKeys, ListModelResponse, ResolvedSelectedShape, ModelResponse, Model, FilterQuery, Response, ServiceError, CreateAdvancedArgs, CreateOptions, CreateAdvancedOptions, ListArgs, ListAdvancedArgs, ListOptions, ListAdvancedOptions, ReadAdvancedArgs, ReadOptions, ReadAdvancedOptions, UpdateAdvancedArgs, UpdateOptions, UpdateAdvancedOptions, UpsertAdvancedArgs, UpsertOptions, UpsertAdvancedOptions, ModelService } from '@web-ts-toolkit/access-router-client';
1
+ import { Document, Projection, SelectedKeys, ListModelResponse, ResolvedSelectedShape, ModelResponse, Model, FilterQuery, Response, ServiceError, CreateAdvancedArgs, CreateOptions, CreateAdvancedOptions, ModelMutationInput, ListArgs, ListAdvancedArgs, ListOptions, ListAdvancedOptions, ReadAdvancedArgs, ReadOptions, ReadAdvancedOptions, UpdateAdvancedArgs, UpdateOptions, UpdateAdvancedOptions, UpsertAdvancedArgs, UpsertOptions, UpsertAdvancedOptions, ModelService } from '@web-ts-toolkit/access-router-client';
2
2
 
3
3
  interface RequestConfig {
4
4
  signal?: AbortSignal;
@@ -7,12 +7,9 @@ interface RequestConfig {
7
7
  }
8
8
  /**
9
9
  * Optional per-call overrides for imperative `query()` invocations
10
- * (Task ARR-05). The `signal` field is composed with the hook's internal
11
- * controller signal — aborting either source cancels the effective
12
- * request. Manual `query()` paths honor the caller signal even when the
13
- * hook's own internal controller is not strictly required for the
14
- * request (e.g. a one-shot manual read where the caller is the sole
15
- * cancellation source).
10
+ * (Task ARR-H01). The `signal` field is composed with the hook-owned
11
+ * controller signal and the current hook-options `requestConfig.signal`.
12
+ * Aborting any source cancels the effective request.
16
13
  */
17
14
  interface QueryCallOptions {
18
15
  signal?: AbortSignal;
@@ -98,6 +95,7 @@ type ProjectedListModelResponse<T extends Document, TSelect extends Projection>
98
95
  interface UseBaseOptions {
99
96
  requestConfig?: RequestConfig;
100
97
  }
98
+ type SingleMutationInput<TInput extends object> = TInput extends readonly unknown[] ? never : TInput;
101
99
  interface UseReadQueryOptions<T extends Document, TSelect extends Projection = Projection> extends UseBaseOptions {
102
100
  id?: string;
103
101
  advanced?: boolean;
@@ -136,11 +134,8 @@ interface UseReadQueryResult<T extends Document, TSelect extends Projection = Pr
136
134
  /**
137
135
  * Re-run the read for `id` via the unified query lifecycle. Accepts an
138
136
  * optional per-call {@link QueryCallOptions} whose `signal` is composed
139
- * with the hook's internal controller signal — aborting either source
140
- * cancels the request (Task ARR-05 req 4). Per-call `query()` does NOT
141
- * reuse the caller's hook-options `requestConfig.signal`; tests that
142
- * need a caller signal on the manual path must pass it via the options
143
- * argument so the composition boundary is explicit.
137
+ * with the hook-owned controller signal and the current hook-options
138
+ * `requestConfig.signal` — aborting any source cancels the request.
144
139
  */
145
140
  query: (id: string, options?: QueryCallOptions) => Promise<ProjectedModelResponse<T, TSelect>>;
146
141
  refetch: () => Promise<ProjectedModelResponse<T, TSelect>>;
@@ -184,8 +179,8 @@ interface UseListQueryResult<T extends Document, TSelect extends Projection = Pr
184
179
  * Re-run the list for `args` (or the configured `listParams`) via the
185
180
  * unified query lifecycle. Accepts an optional per-call
186
181
  * {@link QueryCallOptions} whose `signal` is composed with the hook's
187
- * internal controller signal — aborting either source cancels the
188
- * request (Task ARR-05 req 4).
182
+ * controller signal and the current hook-options `requestConfig.signal`
183
+ * — aborting any source cancels the request.
189
184
  */
190
185
  query: (args?: ListArgs, options?: QueryCallOptions) => Promise<ProjectedListModelResponse<T, TSelect>>;
191
186
  refetch: () => Promise<ProjectedListModelResponse<T, TSelect>>;
@@ -210,11 +205,11 @@ interface UseCreateMutateOptions<T extends Document, TSelect extends Projection
210
205
  onError?: (error: ServiceError) => void;
211
206
  onSettled?: (result: ProjectedModelResponse<T, TSelect> | null, error: ServiceError | null) => void;
212
207
  }
213
- interface UseCreateMutateResult<T extends Document, TSelect extends Projection = Projection> {
208
+ interface UseCreateMutateResult<T extends Document, TSelect extends Projection = Projection, TCreateInput extends object = ModelMutationInput<T>> {
214
209
  data: ProjectedShape<T, TSelect> | null;
215
210
  isPending: boolean;
216
211
  error: ServiceError | null;
217
- mutate: (data: object) => Promise<ProjectedModelResponse<T, TSelect>>;
212
+ mutate: (data: SingleMutationInput<TCreateInput>) => Promise<ProjectedModelResponse<T, TSelect>>;
218
213
  reset: () => void;
219
214
  }
220
215
  interface UseUpdateMutateOptions<T extends Document, TSelect extends Projection = Projection> extends UseBaseOptions {
@@ -232,11 +227,11 @@ interface UseUpdateMutateOptions<T extends Document, TSelect extends Projection
232
227
  onError?: (error: ServiceError) => void;
233
228
  onSettled?: (result: ProjectedModelResponse<T, TSelect> | null, error: ServiceError | null) => void;
234
229
  }
235
- interface UseUpdateMutateResult<T extends Document, TSelect extends Projection = Projection> {
230
+ interface UseUpdateMutateResult<T extends Document, TSelect extends Projection = Projection, TUpdateInput extends object = ModelMutationInput<T>> {
236
231
  data: ProjectedShape<T, TSelect> | null;
237
232
  isPending: boolean;
238
233
  error: ServiceError | null;
239
- mutate: (id: string, data: object) => Promise<ProjectedModelResponse<T, TSelect>>;
234
+ mutate: (id: string, data: TUpdateInput) => Promise<ProjectedModelResponse<T, TSelect>>;
240
235
  reset: () => void;
241
236
  }
242
237
  interface UseUpsertMutateOptions<T extends Document, TSelect extends Projection = Projection> extends UseBaseOptions {
@@ -254,11 +249,11 @@ interface UseUpsertMutateOptions<T extends Document, TSelect extends Projection
254
249
  onError?: (error: ServiceError) => void;
255
250
  onSettled?: (result: ProjectedModelResponse<T, TSelect> | null, error: ServiceError | null) => void;
256
251
  }
257
- interface UseUpsertMutateResult<T extends Document, TSelect extends Projection = Projection> {
252
+ interface UseUpsertMutateResult<T extends Document, TSelect extends Projection = Projection, TUpsertInput extends object = ModelMutationInput<T>> {
258
253
  data: ProjectedShape<T, TSelect> | null;
259
254
  isPending: boolean;
260
255
  error: ServiceError | null;
261
- mutate: (data: object) => Promise<ProjectedModelResponse<T, TSelect>>;
256
+ mutate: (data: TUpsertInput) => Promise<ProjectedModelResponse<T, TSelect>>;
262
257
  reset: () => void;
263
258
  }
264
259
  interface UseDeleteMutateOptions extends UseBaseOptions {
@@ -317,24 +312,30 @@ interface UseDistinctQueryResult {
317
312
  reset: () => void;
318
313
  }
319
314
 
320
- /**
321
- * Creates query and mutation hooks bound to one `ModelService<T>`.
322
- *
323
- * @example
324
- * const { useList, useCreate } = createModelHooks({ modelService });
325
- */
326
- declare function createModelHooks<T extends Document>(config: {
327
- modelService: ModelService<T>;
328
- }): {
315
+ type ServiceDocument<TService extends ModelService<Document, object, object, object>> = TService extends ModelService<infer TDocument, object, object, object> ? TDocument : never;
316
+ type ServiceCreateInput<TService extends ModelService<Document, object, object, object>> = TService extends ModelService<Document, infer TInput, object, object> ? TInput : never;
317
+ type ServiceUpdateInput<TService extends ModelService<Document, object, object, object>> = TService extends ModelService<Document, object, infer TInput, object> ? TInput : never;
318
+ type ServiceUpsertInput<TService extends ModelService<Document, object, object, object>> = TService extends ModelService<Document, object, object, infer TInput> ? TInput : never;
319
+ type SingleCreateInput<TInput extends object> = TInput extends readonly unknown[] ? never : TInput;
320
+ type CreateModelHooksResult<T extends Document, TCreateInput extends object, TUpdateInput extends object, TUpsertInput extends object> = {
329
321
  useRead: <TSelect extends Projection = Projection>(options?: UseReadQueryOptions<T, TSelect>) => UseReadQueryResult<T, TSelect>;
330
322
  useList: <TSelect extends Projection = Projection>(options?: UseListQueryOptions<T, TSelect>) => UseListQueryResult<T, TSelect>;
331
- useCreate: <TSelect extends Projection = Projection>(options?: UseCreateMutateOptions<T, TSelect>) => UseCreateMutateResult<T, TSelect>;
332
- useUpdate: <TSelect extends Projection = Projection>(options?: UseUpdateMutateOptions<T, TSelect>) => UseUpdateMutateResult<T, TSelect>;
333
- useUpsert: <TSelect extends Projection = Projection>(options?: UseUpsertMutateOptions<T, TSelect>) => UseUpsertMutateResult<T, TSelect>;
323
+ useCreate: <TSelect extends Projection = Projection>(options?: UseCreateMutateOptions<T, TSelect>) => UseCreateMutateResult<T, TSelect, SingleCreateInput<TCreateInput>>;
324
+ useUpdate: <TSelect extends Projection = Projection>(options?: UseUpdateMutateOptions<T, TSelect>) => UseUpdateMutateResult<T, TSelect, TUpdateInput>;
325
+ useUpsert: <TSelect extends Projection = Projection>(options?: UseUpsertMutateOptions<T, TSelect>) => UseUpsertMutateResult<T, TSelect, TUpsertInput>;
334
326
  useDelete: (options?: UseDeleteMutateOptions) => UseDeleteMutateResult;
335
327
  useCount: (options?: UseCountQueryOptions<T>) => UseCountQueryResult;
336
328
  useDistinct: (options: UseDistinctQueryOptions<T>) => UseDistinctQueryResult;
337
329
  };
330
+ /**
331
+ * Creates query and mutation hooks bound to one `ModelService<T>`.
332
+ *
333
+ * @example
334
+ * const { useList, useCreate } = createModelHooks({ modelService });
335
+ */
336
+ declare function createModelHooks<TService extends ModelService<Document, object, object, object>>(config: {
337
+ modelService: TService;
338
+ }): CreateModelHooksResult<ServiceDocument<TService>, ServiceCreateInput<TService>, ServiceUpdateInput<TService>, ServiceUpsertInput<TService>>;
338
339
 
339
340
  /**
340
341
  * Error thrown by {@link requestKeyFor} when it encounters a value it
@@ -367,13 +368,12 @@ declare function createModelHooks<T extends Document>(config: {
367
368
  * a future consumer cannot quietly rely on the current
368
369
  * (unspecified) `toString()` shape.
369
370
  *
370
- * The thrown error is a recoverable programming error: the hook surface
371
- * catches `RequestKeyError` from the dependency-key construction path so
372
- * a user-supplied filter with an unsupported value surfaces as a hook
373
- * `error` (the relevant query's `onError` fires once with the
374
- * `RequestKeyError`-as-`ServiceError` payload) rather than crashing the
375
- * render. The throw is the documented contract; testing covers each
376
- * category directly.
371
+ * The thrown error is a recoverable programming error: query hooks catch
372
+ * `RequestKeyError` while building their structural dependency key,
373
+ * rethrow a plain `Error` with the original `RequestKeyError` in
374
+ * `cause`, and interrupt render before any auto-fetch effect runs. The
375
+ * throw is the documented contract; testing covers each category
376
+ * directly.
377
377
  */
378
378
  declare class RequestKeyError extends Error {
379
379
  constructor(message: string);
@@ -403,6 +403,9 @@ declare class RequestKeyError extends Error {
403
403
  * properties) map to `{<key(sorted)!:<key(value)>!...}` recursively.
404
404
  * The key list is sorted, so two structurally equivalent objects
405
405
  * produce the same string regardless of insertion order.
406
+ * - Traversal is bounded: request keys reject inputs deeper than 64
407
+ * nested array/object levels, inputs that require more than 20,000
408
+ * first-visit nodes, or outputs longer than 200,000 characters.
406
409
  *
407
410
  * Unsupported values — `bigint`, `function`, `symbol`, accessor
408
411
  * properties, cycles, and non-plain built-in objects (`RegExp`,