@web-ts-toolkit/access-router-react 0.32.0 → 0.33.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +297 -16
- package/index.d.mts +283 -49
- package/index.d.ts +283 -49
- package/index.js +645 -188
- package/index.mjs +643 -188
- package/package.json +9 -4
package/index.d.mts
CHANGED
|
@@ -1,17 +1,121 @@
|
|
|
1
|
-
import { Document, FilterQuery, Response, ServiceError,
|
|
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
|
-
|
|
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:
|
|
127
|
+
onSuccess?: (result: ProjectedModelResponse<T, TSelect>) => void;
|
|
24
128
|
onError?: (error: ServiceError) => void;
|
|
25
|
-
onSettled?: (result:
|
|
129
|
+
onSettled?: (result: ProjectedModelResponse<T, TSelect> | null, error: ServiceError | null) => void;
|
|
26
130
|
}
|
|
27
|
-
interface UseReadQueryResult<T extends Document> {
|
|
28
|
-
data:
|
|
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
|
-
|
|
33
|
-
|
|
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
|
-
|
|
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:
|
|
172
|
+
onSuccess?: (result: ProjectedListModelResponse<T, TSelect>) => void;
|
|
51
173
|
onError?: (error: ServiceError) => void;
|
|
52
|
-
onSettled?: (result:
|
|
174
|
+
onSettled?: (result: ProjectedListModelResponse<T, TSelect> | null, error: ServiceError | null) => void;
|
|
53
175
|
}
|
|
54
|
-
interface UseListQueryResult<T extends Document> {
|
|
55
|
-
data:
|
|
56
|
-
previousData:
|
|
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
|
-
|
|
62
|
-
|
|
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
|
-
|
|
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:
|
|
209
|
+
onSuccess?: (result: ProjectedModelResponse<T, TSelect>) => void;
|
|
73
210
|
onError?: (error: ServiceError) => void;
|
|
74
|
-
onSettled?: (result:
|
|
211
|
+
onSettled?: (result: ProjectedModelResponse<T, TSelect> | null, error: ServiceError | null) => void;
|
|
75
212
|
}
|
|
76
|
-
interface UseCreateMutateResult<T extends Document> {
|
|
77
|
-
data:
|
|
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<
|
|
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
|
-
|
|
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:
|
|
231
|
+
onSuccess?: (result: ProjectedModelResponse<T, TSelect>) => void;
|
|
91
232
|
onError?: (error: ServiceError) => void;
|
|
92
|
-
onSettled?: (result:
|
|
233
|
+
onSettled?: (result: ProjectedModelResponse<T, TSelect> | null, error: ServiceError | null) => void;
|
|
93
234
|
}
|
|
94
|
-
interface UseUpdateMutateResult<T extends Document> {
|
|
95
|
-
data:
|
|
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<
|
|
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
|
-
|
|
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:
|
|
253
|
+
onSuccess?: (result: ProjectedModelResponse<T, TSelect>) => void;
|
|
109
254
|
onError?: (error: ServiceError) => void;
|
|
110
|
-
onSettled?: (result:
|
|
255
|
+
onSettled?: (result: ProjectedModelResponse<T, TSelect> | null, error: ServiceError | null) => void;
|
|
111
256
|
}
|
|
112
|
-
interface UseUpsertMutateResult<T extends Document> {
|
|
113
|
-
data:
|
|
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<
|
|
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
|
-
|
|
143
|
-
|
|
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
|
-
|
|
159
|
-
|
|
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
|
-
|
|
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 };
|