@web-ts-toolkit/access-router-react 0.38.0 → 0.40.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +29 -13
- package/index.d.mts +42 -39
- package/index.d.ts +42 -39
- package/index.js +213 -167
- package/index.mjs +213 -167
- 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
|
|
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
|
|
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 [
|
|
275
|
-
|
|
276
|
-
|
|
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. `
|
|
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.
|
|
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-
|
|
11
|
-
* controller signal
|
|
12
|
-
*
|
|
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
|
|
140
|
-
*
|
|
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
|
-
*
|
|
188
|
-
*
|
|
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:
|
|
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:
|
|
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:
|
|
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
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
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:
|
|
371
|
-
*
|
|
372
|
-
* a
|
|
373
|
-
* `
|
|
374
|
-
*
|
|
375
|
-
*
|
|
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-
|
|
11
|
-
* controller signal
|
|
12
|
-
*
|
|
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
|
|
140
|
-
*
|
|
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
|
-
*
|
|
188
|
-
*
|
|
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:
|
|
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:
|
|
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:
|
|
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
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
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:
|
|
371
|
-
*
|
|
372
|
-
* a
|
|
373
|
-
* `
|
|
374
|
-
*
|
|
375
|
-
*
|
|
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`,
|