@web-ts-toolkit/access-router-react 0.32.0 → 0.34.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.d.mts CHANGED
@@ -1,17 +1,121 @@
1
- import { Document, FilterQuery, Response, ServiceError, Projection, CreateAdvancedArgs, CreateOptions, CreateAdvancedOptions, ModelResponse, Model, ListArgs, ListAdvancedArgs, ListOptions, ListAdvancedOptions, ListModelResponse, 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, 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;
5
5
  headers?: Record<string, string>;
6
6
  [key: string]: unknown;
7
7
  }
8
+ /**
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).
16
+ */
17
+ interface QueryCallOptions {
18
+ signal?: AbortSignal;
19
+ }
20
+ /**
21
+ * Narrowed success-wrapper data shape returned by the projection-aware
22
+ * React hooks (Task ARR-09). Reuses the client's exported
23
+ * {@link SelectedKeys} utility (no divergent React approximation) to
24
+ * decide whether the consumer supplied a *literal* projection
25
+ * (`readonly ['name'] as const`, `'name'`, or `{ name: 1 }`). When no
26
+ * literal projection was supplied — i.e. `TSelect` is the default
27
+ * broad `Projection` sentinel, for which `SelectedKeys<T, TSelect>` is
28
+ * `never` — the full model shape `Model<T> & T` is preserved so
29
+ * ergonomic read/list defaults (no `select` or `advanced === false`)
30
+ * keep full-model typing. When a literal `select` was supplied, the
31
+ * shape collapses to `Model<T, ResolvedSelectedShape<T, TSelect, never>>`
32
+ * intersected with the computed selected shape: every key the
33
+ * consumer asked for stays definitely-present, every other model key
34
+ * becomes `T[keyof T] | undefined` via the client's
35
+ * `Pick<T, SelectedKeys<T, TSelect>> & Partial<T>` definition. A
36
+ * consumer that selects only `['name']` will see `data.status` typed
37
+ * as `string | undefined` (so `data.status.toUpperCase()` requires a
38
+ * guard or non-null assertion), eliminating the historical "consumer
39
+ * accesses a server-omitted field as definitely present" defect.
40
+ *
41
+ * The shape is shared by query-hook `data`, mutation-hook `data`,
42
+ * `onSuccess(result)`/`onSettled(result, …)` callbacks, manual
43
+ * `query()`/`refetch()` response payloads, and mutation `mutate()`
44
+ * return promises so projection narrowing threads uniformly across
45
+ * every result surface — the package no longer erases the projection
46
+ * generic and casts through `unknown` to a full `T`.
47
+ *
48
+ * `TSelect` defaults to the broad `Projection` sentinel so a consumer
49
+ * that calls `useRead({ id: '1' })` (no `select` — the default) keeps
50
+ * the historical full-model shape. A consumer that supplies a literal
51
+ * projection supplies a literal `TSelect` (TypeScript infers it from
52
+ * the `select?: TSelect` field on the hook options) and the narrow
53
+ * shape is computed automatically.
54
+ *
55
+ * Note: this is a *static* narrowing — the runtime promise is whatever
56
+ * the server returns. When `advanced === false`, `select` is NOT
57
+ * forwarded to the server (the basic `read`/`list`/`create`/etc. do
58
+ * not accept a `select` argument) so the server returns a full model
59
+ * and the client response is a full `T`. The type still has the
60
+ * provided `TSelect` (if any) applied; supplying a literal `select`
61
+ * without `advanced: true` produces a tighter type than the wire
62
+ * payload really justifies. The package treats this as a documented
63
+ * consumer contract — narrow types only when the consumer opted into
64
+ * a literal projection and accepts responsibility for forwarding it
65
+ * down a path that honors it (the `advanced` paths).
66
+ */
67
+ type ProjectedShape<T extends Document, TSelect extends Projection> = [SelectedKeys<T, TSelect>] extends [never] ? Model<T> & T : Model<T, ResolvedSelectedShape<T, TSelect, never>> & ResolvedSelectedShape<T, TSelect, never>;
68
+ /**
69
+ * Array variant of {@link ProjectedShape} used by `useList` — the
70
+ * projection-narrowed single-element shape lifts to an array of the
71
+ * same wrapped shape, matching the client's `ArrayModelResponse` /
72
+ * `ListModelResponse` data payload type.
73
+ */
74
+ type ProjectedShapeArray<T extends Document, TSelect extends Projection> = [SelectedKeys<T, TSelect>] extends [
75
+ never
76
+ ] ? (Model<T> & T)[] : (Model<T, ResolvedSelectedShape<T, TSelect, never>> & ResolvedSelectedShape<T, TSelect, never>)[];
77
+ /**
78
+ * Response alias that picks the client's `ModelResponse<T, S>` (single
79
+ * model) when the consumer supplied a literal `select`, otherwise
80
+ * `ModelResponse<T>` (full-T) for the ergonomically default case. Used
81
+ * by read/create/update/upsert React hooks' `query()`/`refetch()`/
82
+ * `mutate()` return promises and `onSuccess`/`onSettled` callbacks.
83
+ */
84
+ type ProjectedModelResponse<T extends Document, TSelect extends Projection> = [
85
+ SelectedKeys<T, TSelect>
86
+ ] extends [never] ? ModelResponse<T> : ModelResponse<T, ResolvedSelectedShape<T, TSelect, never>>;
87
+ /**
88
+ * Response alias for `useList` — full-T `ListModelResponse<T>` when no
89
+ * projection was supplied, or the narrowed `ListModelResponse<T, S>`
90
+ * otherwise. Threads the projection generic through `query()`/
91
+ * `refetch()` and the `onSuccess`/`onSettled` callbacks so a consumer
92
+ * selecting `['name'] as const` sees the same narrowed element shape
93
+ * on the callback result type as on `data`.
94
+ */
95
+ type ProjectedListModelResponse<T extends Document, TSelect extends Projection> = [
96
+ SelectedKeys<T, TSelect>
97
+ ] extends [never] ? ListModelResponse<T> : ListModelResponse<T, ResolvedSelectedShape<T, TSelect, never>>;
8
98
  interface UseBaseOptions {
9
99
  requestConfig?: RequestConfig;
10
100
  }
11
- interface UseReadQueryOptions<T extends Document> extends UseBaseOptions {
101
+ interface UseReadQueryOptions<T extends Document, TSelect extends Projection = Projection> extends UseBaseOptions {
12
102
  id?: string;
13
103
  advanced?: boolean;
14
- select?: Projection;
104
+ /**
105
+ * Server-side field projection (Task ARR-09). Supply a *literal*
106
+ * tuple (`['name', 'status'] as const`), a literal string
107
+ * (`'name'`), or a `{ name: 1; age: -1 }` object to create a
108
+ * type-level narrowing of {@link UseReadQueryResult.data},
109
+ * callback result types, and the manual `query()`/`refetch()`
110
+ * response payloads. A literal `select` narrows every
111
+ * projection-aware result so omitted properties become
112
+ * `T[keyof T] | undefined` rather than definitely-present; this is
113
+ * the static reflection of the server actually dropping those
114
+ * fields from the response when `advanced === true`. Requires
115
+ * `advanced: true` for the projection to take effect at the request
116
+ * layer (the basic `read` API does not forward `select`).
117
+ */
118
+ select?: TSelect;
15
119
  populate?: ReadAdvancedArgs['populate'];
16
120
  sort?: ReadAdvancedArgs['sort'];
17
121
  include?: ReadAdvancedArgs['include'];
@@ -20,25 +124,43 @@ interface UseReadQueryOptions<T extends Document> extends UseBaseOptions {
20
124
  advancedOptions?: ReadAdvancedOptions;
21
125
  enabled?: boolean;
22
126
  initialData?: (Model<T> & T) | null;
23
- onSuccess?: (result: ModelResponse<T>) => void;
127
+ onSuccess?: (result: ProjectedModelResponse<T, TSelect>) => void;
24
128
  onError?: (error: ServiceError) => void;
25
- onSettled?: (result: ModelResponse<T> | null, error: ServiceError | null) => void;
129
+ onSettled?: (result: ProjectedModelResponse<T, TSelect> | null, error: ServiceError | null) => void;
26
130
  }
27
- interface UseReadQueryResult<T extends Document> {
28
- data: (Model<T> & T) | null;
131
+ interface UseReadQueryResult<T extends Document, TSelect extends Projection = Projection> {
132
+ data: ProjectedShape<T, TSelect> | null;
29
133
  isLoading: boolean;
30
134
  isFetching: boolean;
31
135
  error: ServiceError | null;
32
- query: (id: string) => Promise<ModelResponse<T>>;
33
- refetch: () => void;
136
+ /**
137
+ * Re-run the read for `id` via the unified query lifecycle. Accepts an
138
+ * 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.
144
+ */
145
+ query: (id: string, options?: QueryCallOptions) => Promise<ProjectedModelResponse<T, TSelect>>;
146
+ refetch: () => Promise<ProjectedModelResponse<T, TSelect>>;
34
147
  reset: () => void;
35
148
  }
36
- interface UseListQueryOptions<T extends Document> extends UseBaseOptions {
149
+ interface UseListQueryOptions<T extends Document, TSelect extends Projection = Projection> extends UseBaseOptions {
37
150
  listParams?: ListArgs;
38
151
  filter?: FilterQuery<T>;
39
152
  advanced?: boolean;
40
153
  sort?: ListAdvancedArgs['sort'];
41
- select?: Projection;
154
+ /**
155
+ * Server-side field projection (Task ARR-09). Supply a *literal*
156
+ * tuple (`['name', 'status'] as const`), a literal string
157
+ * (`'name'`), or a `{ name: 1 }` object to narrow the list element
158
+ * shape on {@link UseListQueryResult.data}, the `onSuccess`/`onSettled`
159
+ * callback result payloads, and the manual `query()`/`refetch()`
160
+ * response payloads. Requires `advanced: true` for the basic
161
+ * `list` API does not forward `select`.
162
+ */
163
+ select?: TSelect;
42
164
  populate?: ListAdvancedArgs['populate'];
43
165
  include?: ListAdvancedArgs['include'];
44
166
  tasks?: ListAdvancedArgs['tasks'];
@@ -47,73 +169,96 @@ interface UseListQueryOptions<T extends Document> extends UseBaseOptions {
47
169
  enabled?: boolean;
48
170
  keepPreviousData?: boolean;
49
171
  initialData?: (Model<T> & T)[];
50
- onSuccess?: (result: ListModelResponse<T>) => void;
172
+ onSuccess?: (result: ProjectedListModelResponse<T, TSelect>) => void;
51
173
  onError?: (error: ServiceError) => void;
52
- onSettled?: (result: ListModelResponse<T> | null, error: ServiceError | null) => void;
174
+ onSettled?: (result: ProjectedListModelResponse<T, TSelect> | null, error: ServiceError | null) => void;
53
175
  }
54
- interface UseListQueryResult<T extends Document> {
55
- data: (Model<T> & T)[];
56
- previousData: (Model<T> & T)[] | undefined;
176
+ interface UseListQueryResult<T extends Document, TSelect extends Projection = Projection> {
177
+ data: ProjectedShapeArray<T, TSelect>;
178
+ previousData: ProjectedShapeArray<T, TSelect> | undefined;
57
179
  totalCount: number;
58
180
  isLoading: boolean;
59
181
  isFetching: boolean;
60
182
  error: ServiceError | null;
61
- query: (args?: ListArgs) => Promise<ListModelResponse<T>>;
62
- refetch: () => void;
183
+ /**
184
+ * Re-run the list for `args` (or the configured `listParams`) via the
185
+ * unified query lifecycle. Accepts an optional per-call
186
+ * {@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).
189
+ */
190
+ query: (args?: ListArgs, options?: QueryCallOptions) => Promise<ProjectedListModelResponse<T, TSelect>>;
191
+ refetch: () => Promise<ProjectedListModelResponse<T, TSelect>>;
63
192
  reset: () => void;
64
193
  }
65
- interface UseCreateMutateOptions<T extends Document> extends UseBaseOptions {
194
+ interface UseCreateMutateOptions<T extends Document, TSelect extends Projection = Projection> extends UseBaseOptions {
66
195
  advanced?: boolean;
67
- select?: Projection;
196
+ /**
197
+ * Server-side field projection (Task ARR-09). Supply a literal
198
+ * tuple/string/object projection to narrow the create response
199
+ * `data` shape on {@link UseCreateMutateResult.data}, the
200
+ * `onSuccess`/`onSettled` callback result payloads, and the
201
+ * `mutate()` return promise. Requires `advanced: true` for the
202
+ * basic `create` API does not forward `select`.
203
+ */
204
+ select?: TSelect;
68
205
  populate?: CreateAdvancedArgs['populate'];
69
206
  tasks?: CreateAdvancedArgs['tasks'];
70
207
  basicOptions?: CreateOptions;
71
208
  advancedOptions?: CreateAdvancedOptions;
72
- onSuccess?: (result: ModelResponse<T>) => void;
209
+ onSuccess?: (result: ProjectedModelResponse<T, TSelect>) => void;
73
210
  onError?: (error: ServiceError) => void;
74
- onSettled?: (result: ModelResponse<T> | null, error: ServiceError | null) => void;
211
+ onSettled?: (result: ProjectedModelResponse<T, TSelect> | null, error: ServiceError | null) => void;
75
212
  }
76
- interface UseCreateMutateResult<T extends Document> {
77
- data: (Model<T> & T) | null;
213
+ interface UseCreateMutateResult<T extends Document, TSelect extends Projection = Projection> {
214
+ data: ProjectedShape<T, TSelect> | null;
78
215
  isPending: boolean;
79
216
  error: ServiceError | null;
80
- mutate: (data: object) => Promise<ModelResponse<T>>;
217
+ mutate: (data: object) => Promise<ProjectedModelResponse<T, TSelect>>;
81
218
  reset: () => void;
82
219
  }
83
- interface UseUpdateMutateOptions<T extends Document> extends UseBaseOptions {
220
+ interface UseUpdateMutateOptions<T extends Document, TSelect extends Projection = Projection> extends UseBaseOptions {
84
221
  advanced?: boolean;
85
- select?: Projection;
222
+ /**
223
+ * Server-side field projection (Task ARR-09). See
224
+ * {@link UseCreateMutateOptions.select}.
225
+ */
226
+ select?: TSelect;
86
227
  populate?: UpdateAdvancedArgs['populate'];
87
228
  tasks?: UpdateAdvancedArgs['tasks'];
88
229
  basicOptions?: UpdateOptions;
89
230
  advancedOptions?: UpdateAdvancedOptions;
90
- onSuccess?: (result: ModelResponse<T>) => void;
231
+ onSuccess?: (result: ProjectedModelResponse<T, TSelect>) => void;
91
232
  onError?: (error: ServiceError) => void;
92
- onSettled?: (result: ModelResponse<T> | null, error: ServiceError | null) => void;
233
+ onSettled?: (result: ProjectedModelResponse<T, TSelect> | null, error: ServiceError | null) => void;
93
234
  }
94
- interface UseUpdateMutateResult<T extends Document> {
95
- data: (Model<T> & T) | null;
235
+ interface UseUpdateMutateResult<T extends Document, TSelect extends Projection = Projection> {
236
+ data: ProjectedShape<T, TSelect> | null;
96
237
  isPending: boolean;
97
238
  error: ServiceError | null;
98
- mutate: (id: string, data: object) => Promise<ModelResponse<T>>;
239
+ mutate: (id: string, data: object) => Promise<ProjectedModelResponse<T, TSelect>>;
99
240
  reset: () => void;
100
241
  }
101
- interface UseUpsertMutateOptions<T extends Document> extends UseBaseOptions {
242
+ interface UseUpsertMutateOptions<T extends Document, TSelect extends Projection = Projection> extends UseBaseOptions {
102
243
  advanced?: boolean;
103
- select?: Projection;
244
+ /**
245
+ * Server-side field projection (Task ARR-09). See
246
+ * {@link UseCreateMutateOptions.select}.
247
+ */
248
+ select?: TSelect;
104
249
  populate?: UpsertAdvancedArgs['populate'];
105
250
  tasks?: UpsertAdvancedArgs['tasks'];
106
251
  basicOptions?: UpsertOptions;
107
252
  advancedOptions?: UpsertAdvancedOptions;
108
- onSuccess?: (result: ModelResponse<T>) => void;
253
+ onSuccess?: (result: ProjectedModelResponse<T, TSelect>) => void;
109
254
  onError?: (error: ServiceError) => void;
110
- onSettled?: (result: ModelResponse<T> | null, error: ServiceError | null) => void;
255
+ onSettled?: (result: ProjectedModelResponse<T, TSelect> | null, error: ServiceError | null) => void;
111
256
  }
112
- interface UseUpsertMutateResult<T extends Document> {
113
- data: (Model<T> & T) | null;
257
+ interface UseUpsertMutateResult<T extends Document, TSelect extends Projection = Projection> {
258
+ data: ProjectedShape<T, TSelect> | null;
114
259
  isPending: boolean;
115
260
  error: ServiceError | null;
116
- mutate: (data: object) => Promise<ModelResponse<T>>;
261
+ mutate: (data: object) => Promise<ProjectedModelResponse<T, TSelect>>;
117
262
  reset: () => void;
118
263
  }
119
264
  interface UseDeleteMutateOptions extends UseBaseOptions {
@@ -138,9 +283,15 @@ interface UseCountQueryOptions<T extends Document> extends UseBaseOptions {
138
283
  interface UseCountQueryResult {
139
284
  data: number | null;
140
285
  isLoading: boolean;
286
+ isFetching: boolean;
141
287
  error: ServiceError | null;
142
- query: () => Promise<Response<number>>;
143
- refetch: () => void;
288
+ /**
289
+ * Re-run the count via the unified query lifecycle. Accepts an optional
290
+ * per-call {@link QueryCallOptions} whose `signal` is composed with the
291
+ * hook's internal controller signal (Task ARR-05 req 4).
292
+ */
293
+ query: (options?: QueryCallOptions) => Promise<Response<number>>;
294
+ refetch: () => Promise<Response<number>>;
144
295
  reset: () => void;
145
296
  }
146
297
  interface UseDistinctQueryOptions<T extends Document> extends UseBaseOptions {
@@ -154,9 +305,15 @@ interface UseDistinctQueryOptions<T extends Document> extends UseBaseOptions {
154
305
  interface UseDistinctQueryResult {
155
306
  data: string[] | null;
156
307
  isLoading: boolean;
308
+ isFetching: boolean;
157
309
  error: ServiceError | null;
158
- query: () => Promise<Response<string[]>>;
159
- refetch: () => void;
310
+ /**
311
+ * Re-run the distinct query via the unified query lifecycle. Accepts an
312
+ * optional per-call {@link QueryCallOptions} whose `signal` is composed
313
+ * with the hook's internal controller signal (Task ARR-05 req 4).
314
+ */
315
+ query: (options?: QueryCallOptions) => Promise<Response<string[]>>;
316
+ refetch: () => Promise<Response<string[]>>;
160
317
  reset: () => void;
161
318
  }
162
319
 
@@ -169,14 +326,91 @@ interface UseDistinctQueryResult {
169
326
  declare function createModelHooks<T extends Document>(config: {
170
327
  modelService: ModelService<T>;
171
328
  }): {
172
- useRead: (options?: UseReadQueryOptions<T>) => UseReadQueryResult<T>;
173
- useList: (options?: UseListQueryOptions<T>) => UseListQueryResult<T>;
174
- useCreate: (options?: UseCreateMutateOptions<T>) => UseCreateMutateResult<T>;
175
- useUpdate: (options?: UseUpdateMutateOptions<T>) => UseUpdateMutateResult<T>;
176
- useUpsert: (options?: UseUpsertMutateOptions<T>) => UseUpsertMutateResult<T>;
329
+ useRead: <TSelect extends Projection = Projection>(options?: UseReadQueryOptions<T, TSelect>) => UseReadQueryResult<T, TSelect>;
330
+ 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>;
177
334
  useDelete: (options?: UseDeleteMutateOptions) => UseDeleteMutateResult;
178
335
  useCount: (options?: UseCountQueryOptions<T>) => UseCountQueryResult;
179
336
  useDistinct: (options: UseDistinctQueryOptions<T>) => UseDistinctQueryResult;
180
337
  };
181
338
 
182
- export { type UseBaseOptions, type UseCountQueryOptions, type UseCountQueryResult, type UseCreateMutateOptions, type UseCreateMutateResult, type UseDeleteMutateOptions, type UseDeleteMutateResult, type UseDistinctQueryOptions, type UseDistinctQueryResult, type UseListQueryOptions, type UseListQueryResult, type UseReadQueryOptions, type UseReadQueryResult, type UseUpdateMutateOptions, type UseUpdateMutateResult, type UseUpsertMutateOptions, type UseUpsertMutateResult, createModelHooks };
339
+ /**
340
+ * Error thrown by {@link requestKeyFor} when it encounters a value it
341
+ * cannot represent deterministically in a React effect-deps key
342
+ * (Task ARR-06).
343
+ *
344
+ * The categories are:
345
+ *
346
+ * - **`bigint`**: `JSON.stringify` throws "Do not know how to serialize
347
+ * a BigInt", and silently converting to a number would silently lose
348
+ * precision; a filter built around BigInt is not a supported request
349
+ * input.
350
+ * - **`function`**: callback identity changes every render, and a
351
+ * function key is never structural. If a constructor or plugin
352
+ * needs to influence a request, it must do so via a primitive or
353
+ * plain object key.
354
+ * - **`symbol`**: symbols are silently dropped by `JSON.stringify` and
355
+ * would collide across distinct symbols; an explicit error keeps the
356
+ * request key sound.
357
+ * - **Cycles**: an object/array that references itself (directly or
358
+ * indirectly) would recurse infinitely without an explicit guard;
359
+ * this is treated as a programming error for key construction.
360
+ * - **Accessor properties**: a getter on an enumerable own property
361
+ * would be invoked accidentally when computing the key (a side
362
+ * effect in the dependency-array path) and silently collide with a
363
+ * plain-data property of the same name. Accessors are rejected
364
+ * before any getter fires.
365
+ * - **Unsupported built-in instances** (`RegExp`, `Map`, `Set`,
366
+ * `URL`, etc.): not part of the request-input contract; reject so
367
+ * a future consumer cannot quietly rely on the current
368
+ * (unspecified) `toString()` shape.
369
+ *
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.
377
+ */
378
+ declare class RequestKeyError extends Error {
379
+ constructor(message: string);
380
+ }
381
+ /**
382
+ * Construct the canonical React effect-dep key for a request-affecting
383
+ * input (Task ARR-06).
384
+ *
385
+ * The result is deterministic for any structurally comparable plain-data
386
+ * value and follows these rules (see {@link RequestKeyError} for the
387
+ * rejected categories):
388
+ *
389
+ * - `null`/`undefined` map to `n:` and `u:` sentinels (distinct).
390
+ * - Booleans map to `b:true` / `b:false`.
391
+ * - Numbers map to `n:<number>` using `String()`; `+0` and `-0` map
392
+ * to `n:0` and `n:-0` respectively (kept distinct because
393
+ * `Object.is(0, -0)` is false and a filter where a sign matters
394
+ * must round-trip), and `NaN` maps to `n:NaN`.
395
+ * - Strings map to `s:<JSON.stringify(value)>` so embedded colons,
396
+ * quotes, and other characters cannot collide with the prefix
397
+ * sentinels.
398
+ * - `Date` maps to `d:<getTime()>` — two dates compare equal iff
399
+ * they represent the same instant, and a Date never collides with
400
+ * an ISO-string filter because of the `d:` prefix.
401
+ * - Arrays map to `[<key(e1)>,<key(e2)>,...]` recursively.
402
+ * - Plain objects (no `null` prototype + only enumerable own data
403
+ * properties) map to `{<key(sorted)!:<key(value)>!...}` recursively.
404
+ * The key list is sorted, so two structurally equivalent objects
405
+ * produce the same string regardless of insertion order.
406
+ *
407
+ * Unsupported values — `bigint`, `function`, `symbol`, accessor
408
+ * properties, cycles, and non-plain built-in objects (`RegExp`,
409
+ * `Map`, `Set`, `URL`, etc.) — throw {@link RequestKeyError}.
410
+ *
411
+ * Never invokes a getter: an accessor property detected via
412
+ * `Object.getOwnPropertyDescriptor` is rejected before any access.
413
+ */
414
+ declare function requestKeyFor(value: unknown): string;
415
+
416
+ export { type ProjectedListModelResponse, type ProjectedModelResponse, type ProjectedShape, type ProjectedShapeArray, type QueryCallOptions, type RequestConfig, RequestKeyError, type UseBaseOptions, type UseCountQueryOptions, type UseCountQueryResult, type UseCreateMutateOptions, type UseCreateMutateResult, type UseDeleteMutateOptions, type UseDeleteMutateResult, type UseDistinctQueryOptions, type UseDistinctQueryResult, type UseListQueryOptions, type UseListQueryResult, type UseReadQueryOptions, type UseReadQueryResult, type UseUpdateMutateOptions, type UseUpdateMutateResult, type UseUpsertMutateOptions, type UseUpsertMutateResult, createModelHooks, requestKeyFor };