@web-ts-toolkit/access-router-react 0.42.2 → 0.44.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 +18 -9
- package/index.d.mts +106 -35
- package/index.d.ts +106 -35
- package/index.js +276 -63
- package/index.mjs +276 -63
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -64,7 +64,8 @@ function OrganizationList() {
|
|
|
64
64
|
|
|
65
65
|
return (
|
|
66
66
|
<div>
|
|
67
|
-
|
|
67
|
+
{/* Hook error state (createError) still surfaces the failure; the catch only avoids an unhandled rejection. */}
|
|
68
|
+
<button disabled={isPending} onClick={() => void mutate({ name: 'Northwind Labs' }).catch(() => undefined)}>
|
|
68
69
|
Create
|
|
69
70
|
</button>
|
|
70
71
|
{createError && <p role="alert">Create failed: {createError.message}</p>}
|
|
@@ -279,17 +280,23 @@ function Save() {
|
|
|
279
280
|
const { mutate, isPending } = useUpdate({ advanced: true, select: ['name'] as const });
|
|
280
281
|
|
|
281
282
|
const saveTwice = async () => {
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
283
|
+
try {
|
|
284
|
+
const [firstResult, secondResult] = await Promise.all([
|
|
285
|
+
mutate('org_1', { name: 'A' }),
|
|
286
|
+
mutate('org_1', { name: 'B' }),
|
|
287
|
+
]);
|
|
288
|
+
// Promise.all preserves invocation order. Hook state still follows the latest invocation.
|
|
289
|
+
console.log(firstResult.data?.name, secondResult.data?.name);
|
|
290
|
+
return secondResult.data;
|
|
291
|
+
} catch (error) {
|
|
292
|
+
// Hook error state still surfaces the failure; handling here avoids an unhandled rejection.
|
|
293
|
+
console.error('Save failed', error);
|
|
294
|
+
return undefined;
|
|
295
|
+
}
|
|
289
296
|
};
|
|
290
297
|
|
|
291
298
|
return (
|
|
292
|
-
<button disabled={isPending} onClick={saveTwice}>
|
|
299
|
+
<button disabled={isPending} onClick={() => void saveTwice().catch(() => undefined)}>
|
|
293
300
|
Save twice
|
|
294
301
|
</button>
|
|
295
302
|
);
|
|
@@ -324,6 +331,8 @@ select: { name: 1, age: -1 }, // projection-shaped object
|
|
|
324
331
|
|
|
325
332
|
The narrowing is applied uniformly to `data`, `onSuccess(result)`/`onSettled(result, …)` callbacks, manual `query()`/`refetch()` response payloads, and mutation `mutate()` return promises — via the public `ProjectedShape`, `ProjectedShapeArray`, `ProjectedModelResponse`, and `ProjectedListModelResponse` helpers, which reuse the client's `SelectedKeys` utility.
|
|
326
333
|
|
|
334
|
+
Only an omitted `select` keeps the full required model. A supplied-but-indeterminable `select` (a broad `string`/`string[]` variable or an exclusion-only object such as `{ status: -1 }`) marks every field optional, and a union `select` (e.g. `readonly ['name'] | readonly ['status']`) keeps each alternative's own required/optional contract instead of merging keys — required access to an omitted or uncertain field fails to compile.
|
|
335
|
+
|
|
327
336
|
A literal `select` requires `advanced: true` to actually reach the server's narrowing code path; the basic `read`/`list`/`create`/etc. APIs do not forward `select`. The type still narrows when you supply a literal `select` without `advanced`, but the wire payload is unchanged — you opt into the narrowed type and accept responsibility for forwarding it down the advanced path.
|
|
328
337
|
|
|
329
338
|
## Dependency-Key Policy
|
package/index.d.mts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { Document, Projection,
|
|
1
|
+
import { Document, Projection, 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;
|
|
@@ -14,23 +14,51 @@ interface RequestConfig {
|
|
|
14
14
|
interface QueryCallOptions {
|
|
15
15
|
signal?: AbortSignal;
|
|
16
16
|
}
|
|
17
|
+
/**
|
|
18
|
+
* True exactly when the consumer did NOT supply a projection — i.e.
|
|
19
|
+
* `TSelect` is still the broad `Projection` default sentinel
|
|
20
|
+
* (`UseReadQueryOptions<T>` with no `select`). Because `TSelect` is
|
|
21
|
+
* constrained to `extends Projection`, `[Projection] extends [TSelect]`
|
|
22
|
+
* holds only for `TSelect = Projection` itself: every narrower
|
|
23
|
+
* supplied selection (a literal tuple/string/object, a broad `string`
|
|
24
|
+
* or `string[]` variable, an exclusion-only object, or a union of
|
|
25
|
+
* alternatives) fails the check and takes the conservative path below.
|
|
26
|
+
* This distinguishes "selection really absent" (safe full-model
|
|
27
|
+
* inference) from "selection supplied but indeterminable" (must NOT
|
|
28
|
+
* fall back to the full model).
|
|
29
|
+
*/
|
|
30
|
+
type IsAbsentProjection<TSelect extends Projection> = [Projection] extends [TSelect] ? true : false;
|
|
31
|
+
/**
|
|
32
|
+
* Conservative narrowed element shape for ONE supplied (non-absent)
|
|
33
|
+
* selection branch. Reuses the client's
|
|
34
|
+
* `ResolvedSelectedShape<T, S, never>` (= `SelectedShape<T, S>` =
|
|
35
|
+
* `Pick<T, SelectedKeys<T, S>> & Partial<T>`): every determinable
|
|
36
|
+
* selected key stays definitely-present, every other model key is
|
|
37
|
+
* `T[key] | undefined`. When the supplied selection is indeterminable
|
|
38
|
+
* — broad `string` / `string[]`, exclusion-only `{ status: -1 }`, or
|
|
39
|
+
* any other shape for which `SelectedKeys<T, S>` is `never` — the
|
|
40
|
+
* resolved shape is `Partial<T>`, so ALL fields become optional rather
|
|
41
|
+
* than falling back to the full required model. No casts and no
|
|
42
|
+
* blanket full-model fallback are used on this path.
|
|
43
|
+
*/
|
|
44
|
+
type NarrowedDataShape<T extends Document, S extends Projection> = Model<T, ResolvedSelectedShape<T, S, never>> & ResolvedSelectedShape<T, S, never>;
|
|
17
45
|
/**
|
|
18
46
|
* Narrowed success-wrapper data shape returned by the projection-aware
|
|
19
|
-
* React hooks (Task ARR-09
|
|
20
|
-
*
|
|
21
|
-
*
|
|
22
|
-
* (`readonly ['name'] as const`, `'name'`, or `{ name: 1 }`). When no
|
|
23
|
-
* literal projection was supplied — i.e. `TSelect` is the default
|
|
24
|
-
* broad `Projection` sentinel, for which `SelectedKeys<T, TSelect>` is
|
|
25
|
-
* `never` — the full model shape `Model<T> & T` is preserved so
|
|
47
|
+
* React hooks (Task ARR-09, conservative-union semantics by ARR-B03).
|
|
48
|
+
* When no projection was supplied (`TSelect` is the broad `Projection`
|
|
49
|
+
* default) the full model shape `Model<T> & T` is preserved so
|
|
26
50
|
* ergonomic read/list defaults (no `select` or `advanced === false`)
|
|
27
|
-
* keep full-model typing. When a
|
|
28
|
-
*
|
|
29
|
-
*
|
|
30
|
-
*
|
|
31
|
-
*
|
|
32
|
-
* `
|
|
33
|
-
*
|
|
51
|
+
* keep full-model typing. When a selection WAS supplied, the shape
|
|
52
|
+
* distributes over a union `TSelect` (`S extends unknown ? ...`) so
|
|
53
|
+
* each alternative keeps its own required/optional contract instead of
|
|
54
|
+
* merging keys into one overly-required shape: a consumer selecting
|
|
55
|
+
* `readonly ['name'] | readonly ['status']` sees
|
|
56
|
+
* `Shape<['name']> | Shape<['status']>`, and required access to either
|
|
57
|
+
* field alone fails to compile. Supplied-but-indeterminable selections
|
|
58
|
+
* (broad `string`, `string[]`, exclusion-only objects) resolve to
|
|
59
|
+
* `Model<T, Partial<T>> & Partial<T>` — every field optional.
|
|
60
|
+
*
|
|
61
|
+
* A consumer that selects only `['name']` will see `data.status` typed
|
|
34
62
|
* as `string | undefined` (so `data.status.toUpperCase()` requires a
|
|
35
63
|
* guard or non-null assertion), eliminating the historical "consumer
|
|
36
64
|
* accesses a server-omitted field as definitely present" defect.
|
|
@@ -44,9 +72,9 @@ interface QueryCallOptions {
|
|
|
44
72
|
*
|
|
45
73
|
* `TSelect` defaults to the broad `Projection` sentinel so a consumer
|
|
46
74
|
* that calls `useRead({ id: '1' })` (no `select` — the default) keeps
|
|
47
|
-
* the historical full-model shape. A consumer that supplies a
|
|
48
|
-
* projection supplies a
|
|
49
|
-
*
|
|
75
|
+
* the historical full-model shape. A consumer that supplies a
|
|
76
|
+
* projection supplies a `TSelect` (TypeScript infers it from the
|
|
77
|
+
* `select?: TSelect` field on the hook options) and the narrow
|
|
50
78
|
* shape is computed automatically.
|
|
51
79
|
*
|
|
52
80
|
* Note: this is a *static* narrowing — the runtime promise is whatever
|
|
@@ -54,44 +82,51 @@ interface QueryCallOptions {
|
|
|
54
82
|
* forwarded to the server (the basic `read`/`list`/`create`/etc. do
|
|
55
83
|
* not accept a `select` argument) so the server returns a full model
|
|
56
84
|
* and the client response is a full `T`. The type still has the
|
|
57
|
-
* provided `TSelect` (if any) applied; supplying a
|
|
85
|
+
* provided `TSelect` (if any) applied; supplying a `select`
|
|
58
86
|
* without `advanced: true` produces a tighter type than the wire
|
|
59
87
|
* payload really justifies. The package treats this as a documented
|
|
60
88
|
* consumer contract — narrow types only when the consumer opted into
|
|
61
|
-
* a
|
|
89
|
+
* a projection and accepts responsibility for forwarding it
|
|
62
90
|
* down a path that honors it (the `advanced` paths).
|
|
91
|
+
*
|
|
92
|
+
* Declaration tightening (ARR-B03): dynamic, exclusion-only, and union
|
|
93
|
+
* selections no longer resolve to the full required model. Consumers
|
|
94
|
+
* relying on the old fallback must narrow with guards or supply a
|
|
95
|
+
* literal projection.
|
|
63
96
|
*/
|
|
64
|
-
type ProjectedShape<T extends Document, TSelect extends Projection> =
|
|
97
|
+
type ProjectedShape<T extends Document, TSelect extends Projection> = IsAbsentProjection<TSelect> extends true ? Model<T> & T : [TSelect] extends [never] ? NarrowedDataShape<T, TSelect> : TSelect extends unknown ? NarrowedDataShape<T, TSelect> : never;
|
|
65
98
|
/**
|
|
66
99
|
* Array variant of {@link ProjectedShape} used by `useList` — the
|
|
67
100
|
* projection-narrowed single-element shape lifts to an array of the
|
|
68
101
|
* same wrapped shape, matching the client's `ArrayModelResponse` /
|
|
69
|
-
* `ListModelResponse` data payload type.
|
|
102
|
+
* `ListModelResponse` data payload type. Absent selection keeps
|
|
103
|
+
* `(Model<T> & T)[]`; supplied selections (including unions, which
|
|
104
|
+
* distribute to a union of arrays) use the same conservative
|
|
105
|
+
* per-branch element shape as {@link ProjectedShape}.
|
|
70
106
|
*/
|
|
71
|
-
type ProjectedShapeArray<T extends Document, TSelect extends Projection> = [
|
|
72
|
-
never
|
|
73
|
-
] ? (Model<T> & T)[] : (Model<T, ResolvedSelectedShape<T, TSelect, never>> & ResolvedSelectedShape<T, TSelect, never>)[];
|
|
107
|
+
type ProjectedShapeArray<T extends Document, TSelect extends Projection> = IsAbsentProjection<TSelect> extends true ? (Model<T> & T)[] : [TSelect] extends [never] ? NarrowedDataShape<T, TSelect>[] : TSelect extends unknown ? NarrowedDataShape<T, TSelect>[] : never;
|
|
74
108
|
/**
|
|
75
109
|
* Response alias that picks the client's `ModelResponse<T, S>` (single
|
|
76
|
-
* model) when the consumer supplied a
|
|
110
|
+
* model) when the consumer supplied a `select`, otherwise
|
|
77
111
|
* `ModelResponse<T>` (full-T) for the ergonomically default case. Used
|
|
78
112
|
* by read/create/update/upsert React hooks' `query()`/`refetch()`/
|
|
79
113
|
* `mutate()` return promises and `onSuccess`/`onSettled` callbacks.
|
|
114
|
+
* Supplied selections distribute over unions and fall back to
|
|
115
|
+
* `ModelResponse<T, Partial<T>>` (all fields optional) when the fields
|
|
116
|
+
* cannot be determined — never to the full required model.
|
|
80
117
|
*/
|
|
81
|
-
type ProjectedModelResponse<T extends Document, TSelect extends Projection> = [
|
|
82
|
-
SelectedKeys<T, TSelect>
|
|
83
|
-
] extends [never] ? ModelResponse<T> : ModelResponse<T, ResolvedSelectedShape<T, TSelect, never>>;
|
|
118
|
+
type ProjectedModelResponse<T extends Document, TSelect extends Projection> = IsAbsentProjection<TSelect> extends true ? ModelResponse<T> : [TSelect] extends [never] ? ModelResponse<T, ResolvedSelectedShape<T, TSelect, never>> : TSelect extends unknown ? ModelResponse<T, ResolvedSelectedShape<T, TSelect, never>> : never;
|
|
84
119
|
/**
|
|
85
120
|
* Response alias for `useList` — full-T `ListModelResponse<T>` when no
|
|
86
121
|
* projection was supplied, or the narrowed `ListModelResponse<T, S>`
|
|
87
122
|
* otherwise. Threads the projection generic through `query()`/
|
|
88
123
|
* `refetch()` and the `onSuccess`/`onSettled` callbacks so a consumer
|
|
89
124
|
* selecting `['name'] as const` sees the same narrowed element shape
|
|
90
|
-
* on the callback result type as on `data`.
|
|
125
|
+
* on the callback result type as on `data`. Union selections
|
|
126
|
+
* distribute to a union of list responses; indeterminable selections
|
|
127
|
+
* resolve to `ListModelResponse<T, Partial<T>>`.
|
|
91
128
|
*/
|
|
92
|
-
type ProjectedListModelResponse<T extends Document, TSelect extends Projection> = [
|
|
93
|
-
SelectedKeys<T, TSelect>
|
|
94
|
-
] extends [never] ? ListModelResponse<T> : ListModelResponse<T, ResolvedSelectedShape<T, TSelect, never>>;
|
|
129
|
+
type ProjectedListModelResponse<T extends Document, TSelect extends Projection> = IsAbsentProjection<TSelect> extends true ? ListModelResponse<T> : [TSelect] extends [never] ? ListModelResponse<T, ResolvedSelectedShape<T, TSelect, never>> : TSelect extends unknown ? ListModelResponse<T, ResolvedSelectedShape<T, TSelect, never>> : never;
|
|
95
130
|
interface UseBaseOptions {
|
|
96
131
|
requestConfig?: RequestConfig;
|
|
97
132
|
}
|
|
@@ -397,8 +432,16 @@ declare class RequestKeyError extends Error {
|
|
|
397
432
|
* sentinels.
|
|
398
433
|
* - `Date` maps to `d:<getTime()>` — two dates compare equal iff
|
|
399
434
|
* they represent the same instant, and a Date never collides with
|
|
400
|
-
* an ISO-string filter because of the `d:` prefix.
|
|
401
|
-
*
|
|
435
|
+
* an ISO-string filter because of the `d:` prefix. The instant is
|
|
436
|
+
* read via the intrinsic `Date.prototype.getTime` captured at module
|
|
437
|
+
* load, never via caller-overridable `value.getTime()` lookup.
|
|
438
|
+
* - Arrays map to `[<key(e1)>,<key(e2)>,...]` recursively. Element
|
|
439
|
+
* descriptors (own, then inherited for holes) are inspected before
|
|
440
|
+
* any read, so own/inherited accessors throw before a getter fires.
|
|
441
|
+
* True holes with no prototype value serialize as `undefined`,
|
|
442
|
+
* preserving normal sparse-array behavior; an inherited accessor at
|
|
443
|
+
* a hole is a deliberate tightening (previously it would execute).
|
|
444
|
+
* Inherited data values at holes read through by descriptor value.
|
|
402
445
|
* - Plain objects (no `null` prototype + only enumerable own data
|
|
403
446
|
* properties) map to `{<key(sorted)!:<key(value)>!...}` recursively.
|
|
404
447
|
* The key list is sorted, so two structurally equivalent objects
|
|
@@ -406,6 +449,18 @@ declare class RequestKeyError extends Error {
|
|
|
406
449
|
* - Traversal is bounded: request keys reject inputs deeper than 64
|
|
407
450
|
* nested array/object levels, inputs that require more than 20,000
|
|
408
451
|
* first-visit nodes, or outputs longer than 200,000 characters.
|
|
452
|
+
* Numeric budgets are unchanged (ARR-B06 retains them).
|
|
453
|
+
* - Per-call memoization reuses repeated references without retaining
|
|
454
|
+
* caller objects across calls. Cached subtrees store their intrinsic
|
|
455
|
+
* height and revalidate `depth + height` on hits (ARR-B06), so a
|
|
456
|
+
* subtree first seen shallowly cannot be reused deeper past the
|
|
457
|
+
* depth limit; shared and copied over-depth structures both throw
|
|
458
|
+
* independent of visitation order.
|
|
459
|
+
* - Obviously oversized strings/property names are preflighted on raw
|
|
460
|
+
* length before `JSON.stringify` (escaping only grows the encoded
|
|
461
|
+
* form), and excessive object/array width is preflighted on counts
|
|
462
|
+
* (plus a lower-bound output check) before sorting/iteration
|
|
463
|
+
* (ARR-B06). Oversized diagnostics are truncated by length.
|
|
409
464
|
*
|
|
410
465
|
* Unsupported values — `bigint`, `function`, `symbol`, accessor
|
|
411
466
|
* properties, cycles, and non-plain built-in objects (`RegExp`,
|
|
@@ -413,6 +468,22 @@ declare class RequestKeyError extends Error {
|
|
|
413
468
|
*
|
|
414
469
|
* Never invokes a getter: an accessor property detected via
|
|
415
470
|
* `Object.getOwnPropertyDescriptor` is rejected before any access.
|
|
471
|
+
* The same descriptor-first policy covers array indices (including
|
|
472
|
+
* inherited accessors at sparse holes) and top-level request-config
|
|
473
|
+
* properties via `requestConfigKeyInput` (whose `signal` key is skipped
|
|
474
|
+
* by name before any read). Date instants use the captured intrinsic.
|
|
475
|
+
*
|
|
476
|
+
* Proxy boundary: the reflective operations above
|
|
477
|
+
* (`getOwnPropertyDescriptor`, `getPrototypeOf`, `Object.keys`,
|
|
478
|
+
* `getOwnPropertySymbols`) can trigger proxy traps. Safe introspection
|
|
479
|
+
* of arbitrary proxies is not promised; pass plain wire data.
|
|
480
|
+
*
|
|
481
|
+
* Residual limits (ARR-B06, honest bounds): the budgets bound accepted
|
|
482
|
+
* output and first-visit traversal, not all temporary work. Enumerating
|
|
483
|
+
* `Object.keys` / descriptors over a caller object is inherently
|
|
484
|
+
* input-sized, and escaping may expand strings up to ~6x per character
|
|
485
|
+
* before the post-encoding output check fires. No absolute CPU/memory
|
|
486
|
+
* bound for arbitrary caller objects is claimed.
|
|
416
487
|
*/
|
|
417
488
|
declare function requestKeyFor(value: unknown): string;
|
|
418
489
|
|
package/index.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { Document, Projection,
|
|
1
|
+
import { Document, Projection, 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;
|
|
@@ -14,23 +14,51 @@ interface RequestConfig {
|
|
|
14
14
|
interface QueryCallOptions {
|
|
15
15
|
signal?: AbortSignal;
|
|
16
16
|
}
|
|
17
|
+
/**
|
|
18
|
+
* True exactly when the consumer did NOT supply a projection — i.e.
|
|
19
|
+
* `TSelect` is still the broad `Projection` default sentinel
|
|
20
|
+
* (`UseReadQueryOptions<T>` with no `select`). Because `TSelect` is
|
|
21
|
+
* constrained to `extends Projection`, `[Projection] extends [TSelect]`
|
|
22
|
+
* holds only for `TSelect = Projection` itself: every narrower
|
|
23
|
+
* supplied selection (a literal tuple/string/object, a broad `string`
|
|
24
|
+
* or `string[]` variable, an exclusion-only object, or a union of
|
|
25
|
+
* alternatives) fails the check and takes the conservative path below.
|
|
26
|
+
* This distinguishes "selection really absent" (safe full-model
|
|
27
|
+
* inference) from "selection supplied but indeterminable" (must NOT
|
|
28
|
+
* fall back to the full model).
|
|
29
|
+
*/
|
|
30
|
+
type IsAbsentProjection<TSelect extends Projection> = [Projection] extends [TSelect] ? true : false;
|
|
31
|
+
/**
|
|
32
|
+
* Conservative narrowed element shape for ONE supplied (non-absent)
|
|
33
|
+
* selection branch. Reuses the client's
|
|
34
|
+
* `ResolvedSelectedShape<T, S, never>` (= `SelectedShape<T, S>` =
|
|
35
|
+
* `Pick<T, SelectedKeys<T, S>> & Partial<T>`): every determinable
|
|
36
|
+
* selected key stays definitely-present, every other model key is
|
|
37
|
+
* `T[key] | undefined`. When the supplied selection is indeterminable
|
|
38
|
+
* — broad `string` / `string[]`, exclusion-only `{ status: -1 }`, or
|
|
39
|
+
* any other shape for which `SelectedKeys<T, S>` is `never` — the
|
|
40
|
+
* resolved shape is `Partial<T>`, so ALL fields become optional rather
|
|
41
|
+
* than falling back to the full required model. No casts and no
|
|
42
|
+
* blanket full-model fallback are used on this path.
|
|
43
|
+
*/
|
|
44
|
+
type NarrowedDataShape<T extends Document, S extends Projection> = Model<T, ResolvedSelectedShape<T, S, never>> & ResolvedSelectedShape<T, S, never>;
|
|
17
45
|
/**
|
|
18
46
|
* Narrowed success-wrapper data shape returned by the projection-aware
|
|
19
|
-
* React hooks (Task ARR-09
|
|
20
|
-
*
|
|
21
|
-
*
|
|
22
|
-
* (`readonly ['name'] as const`, `'name'`, or `{ name: 1 }`). When no
|
|
23
|
-
* literal projection was supplied — i.e. `TSelect` is the default
|
|
24
|
-
* broad `Projection` sentinel, for which `SelectedKeys<T, TSelect>` is
|
|
25
|
-
* `never` — the full model shape `Model<T> & T` is preserved so
|
|
47
|
+
* React hooks (Task ARR-09, conservative-union semantics by ARR-B03).
|
|
48
|
+
* When no projection was supplied (`TSelect` is the broad `Projection`
|
|
49
|
+
* default) the full model shape `Model<T> & T` is preserved so
|
|
26
50
|
* ergonomic read/list defaults (no `select` or `advanced === false`)
|
|
27
|
-
* keep full-model typing. When a
|
|
28
|
-
*
|
|
29
|
-
*
|
|
30
|
-
*
|
|
31
|
-
*
|
|
32
|
-
* `
|
|
33
|
-
*
|
|
51
|
+
* keep full-model typing. When a selection WAS supplied, the shape
|
|
52
|
+
* distributes over a union `TSelect` (`S extends unknown ? ...`) so
|
|
53
|
+
* each alternative keeps its own required/optional contract instead of
|
|
54
|
+
* merging keys into one overly-required shape: a consumer selecting
|
|
55
|
+
* `readonly ['name'] | readonly ['status']` sees
|
|
56
|
+
* `Shape<['name']> | Shape<['status']>`, and required access to either
|
|
57
|
+
* field alone fails to compile. Supplied-but-indeterminable selections
|
|
58
|
+
* (broad `string`, `string[]`, exclusion-only objects) resolve to
|
|
59
|
+
* `Model<T, Partial<T>> & Partial<T>` — every field optional.
|
|
60
|
+
*
|
|
61
|
+
* A consumer that selects only `['name']` will see `data.status` typed
|
|
34
62
|
* as `string | undefined` (so `data.status.toUpperCase()` requires a
|
|
35
63
|
* guard or non-null assertion), eliminating the historical "consumer
|
|
36
64
|
* accesses a server-omitted field as definitely present" defect.
|
|
@@ -44,9 +72,9 @@ interface QueryCallOptions {
|
|
|
44
72
|
*
|
|
45
73
|
* `TSelect` defaults to the broad `Projection` sentinel so a consumer
|
|
46
74
|
* that calls `useRead({ id: '1' })` (no `select` — the default) keeps
|
|
47
|
-
* the historical full-model shape. A consumer that supplies a
|
|
48
|
-
* projection supplies a
|
|
49
|
-
*
|
|
75
|
+
* the historical full-model shape. A consumer that supplies a
|
|
76
|
+
* projection supplies a `TSelect` (TypeScript infers it from the
|
|
77
|
+
* `select?: TSelect` field on the hook options) and the narrow
|
|
50
78
|
* shape is computed automatically.
|
|
51
79
|
*
|
|
52
80
|
* Note: this is a *static* narrowing — the runtime promise is whatever
|
|
@@ -54,44 +82,51 @@ interface QueryCallOptions {
|
|
|
54
82
|
* forwarded to the server (the basic `read`/`list`/`create`/etc. do
|
|
55
83
|
* not accept a `select` argument) so the server returns a full model
|
|
56
84
|
* and the client response is a full `T`. The type still has the
|
|
57
|
-
* provided `TSelect` (if any) applied; supplying a
|
|
85
|
+
* provided `TSelect` (if any) applied; supplying a `select`
|
|
58
86
|
* without `advanced: true` produces a tighter type than the wire
|
|
59
87
|
* payload really justifies. The package treats this as a documented
|
|
60
88
|
* consumer contract — narrow types only when the consumer opted into
|
|
61
|
-
* a
|
|
89
|
+
* a projection and accepts responsibility for forwarding it
|
|
62
90
|
* down a path that honors it (the `advanced` paths).
|
|
91
|
+
*
|
|
92
|
+
* Declaration tightening (ARR-B03): dynamic, exclusion-only, and union
|
|
93
|
+
* selections no longer resolve to the full required model. Consumers
|
|
94
|
+
* relying on the old fallback must narrow with guards or supply a
|
|
95
|
+
* literal projection.
|
|
63
96
|
*/
|
|
64
|
-
type ProjectedShape<T extends Document, TSelect extends Projection> =
|
|
97
|
+
type ProjectedShape<T extends Document, TSelect extends Projection> = IsAbsentProjection<TSelect> extends true ? Model<T> & T : [TSelect] extends [never] ? NarrowedDataShape<T, TSelect> : TSelect extends unknown ? NarrowedDataShape<T, TSelect> : never;
|
|
65
98
|
/**
|
|
66
99
|
* Array variant of {@link ProjectedShape} used by `useList` — the
|
|
67
100
|
* projection-narrowed single-element shape lifts to an array of the
|
|
68
101
|
* same wrapped shape, matching the client's `ArrayModelResponse` /
|
|
69
|
-
* `ListModelResponse` data payload type.
|
|
102
|
+
* `ListModelResponse` data payload type. Absent selection keeps
|
|
103
|
+
* `(Model<T> & T)[]`; supplied selections (including unions, which
|
|
104
|
+
* distribute to a union of arrays) use the same conservative
|
|
105
|
+
* per-branch element shape as {@link ProjectedShape}.
|
|
70
106
|
*/
|
|
71
|
-
type ProjectedShapeArray<T extends Document, TSelect extends Projection> = [
|
|
72
|
-
never
|
|
73
|
-
] ? (Model<T> & T)[] : (Model<T, ResolvedSelectedShape<T, TSelect, never>> & ResolvedSelectedShape<T, TSelect, never>)[];
|
|
107
|
+
type ProjectedShapeArray<T extends Document, TSelect extends Projection> = IsAbsentProjection<TSelect> extends true ? (Model<T> & T)[] : [TSelect] extends [never] ? NarrowedDataShape<T, TSelect>[] : TSelect extends unknown ? NarrowedDataShape<T, TSelect>[] : never;
|
|
74
108
|
/**
|
|
75
109
|
* Response alias that picks the client's `ModelResponse<T, S>` (single
|
|
76
|
-
* model) when the consumer supplied a
|
|
110
|
+
* model) when the consumer supplied a `select`, otherwise
|
|
77
111
|
* `ModelResponse<T>` (full-T) for the ergonomically default case. Used
|
|
78
112
|
* by read/create/update/upsert React hooks' `query()`/`refetch()`/
|
|
79
113
|
* `mutate()` return promises and `onSuccess`/`onSettled` callbacks.
|
|
114
|
+
* Supplied selections distribute over unions and fall back to
|
|
115
|
+
* `ModelResponse<T, Partial<T>>` (all fields optional) when the fields
|
|
116
|
+
* cannot be determined — never to the full required model.
|
|
80
117
|
*/
|
|
81
|
-
type ProjectedModelResponse<T extends Document, TSelect extends Projection> = [
|
|
82
|
-
SelectedKeys<T, TSelect>
|
|
83
|
-
] extends [never] ? ModelResponse<T> : ModelResponse<T, ResolvedSelectedShape<T, TSelect, never>>;
|
|
118
|
+
type ProjectedModelResponse<T extends Document, TSelect extends Projection> = IsAbsentProjection<TSelect> extends true ? ModelResponse<T> : [TSelect] extends [never] ? ModelResponse<T, ResolvedSelectedShape<T, TSelect, never>> : TSelect extends unknown ? ModelResponse<T, ResolvedSelectedShape<T, TSelect, never>> : never;
|
|
84
119
|
/**
|
|
85
120
|
* Response alias for `useList` — full-T `ListModelResponse<T>` when no
|
|
86
121
|
* projection was supplied, or the narrowed `ListModelResponse<T, S>`
|
|
87
122
|
* otherwise. Threads the projection generic through `query()`/
|
|
88
123
|
* `refetch()` and the `onSuccess`/`onSettled` callbacks so a consumer
|
|
89
124
|
* selecting `['name'] as const` sees the same narrowed element shape
|
|
90
|
-
* on the callback result type as on `data`.
|
|
125
|
+
* on the callback result type as on `data`. Union selections
|
|
126
|
+
* distribute to a union of list responses; indeterminable selections
|
|
127
|
+
* resolve to `ListModelResponse<T, Partial<T>>`.
|
|
91
128
|
*/
|
|
92
|
-
type ProjectedListModelResponse<T extends Document, TSelect extends Projection> = [
|
|
93
|
-
SelectedKeys<T, TSelect>
|
|
94
|
-
] extends [never] ? ListModelResponse<T> : ListModelResponse<T, ResolvedSelectedShape<T, TSelect, never>>;
|
|
129
|
+
type ProjectedListModelResponse<T extends Document, TSelect extends Projection> = IsAbsentProjection<TSelect> extends true ? ListModelResponse<T> : [TSelect] extends [never] ? ListModelResponse<T, ResolvedSelectedShape<T, TSelect, never>> : TSelect extends unknown ? ListModelResponse<T, ResolvedSelectedShape<T, TSelect, never>> : never;
|
|
95
130
|
interface UseBaseOptions {
|
|
96
131
|
requestConfig?: RequestConfig;
|
|
97
132
|
}
|
|
@@ -397,8 +432,16 @@ declare class RequestKeyError extends Error {
|
|
|
397
432
|
* sentinels.
|
|
398
433
|
* - `Date` maps to `d:<getTime()>` — two dates compare equal iff
|
|
399
434
|
* they represent the same instant, and a Date never collides with
|
|
400
|
-
* an ISO-string filter because of the `d:` prefix.
|
|
401
|
-
*
|
|
435
|
+
* an ISO-string filter because of the `d:` prefix. The instant is
|
|
436
|
+
* read via the intrinsic `Date.prototype.getTime` captured at module
|
|
437
|
+
* load, never via caller-overridable `value.getTime()` lookup.
|
|
438
|
+
* - Arrays map to `[<key(e1)>,<key(e2)>,...]` recursively. Element
|
|
439
|
+
* descriptors (own, then inherited for holes) are inspected before
|
|
440
|
+
* any read, so own/inherited accessors throw before a getter fires.
|
|
441
|
+
* True holes with no prototype value serialize as `undefined`,
|
|
442
|
+
* preserving normal sparse-array behavior; an inherited accessor at
|
|
443
|
+
* a hole is a deliberate tightening (previously it would execute).
|
|
444
|
+
* Inherited data values at holes read through by descriptor value.
|
|
402
445
|
* - Plain objects (no `null` prototype + only enumerable own data
|
|
403
446
|
* properties) map to `{<key(sorted)!:<key(value)>!...}` recursively.
|
|
404
447
|
* The key list is sorted, so two structurally equivalent objects
|
|
@@ -406,6 +449,18 @@ declare class RequestKeyError extends Error {
|
|
|
406
449
|
* - Traversal is bounded: request keys reject inputs deeper than 64
|
|
407
450
|
* nested array/object levels, inputs that require more than 20,000
|
|
408
451
|
* first-visit nodes, or outputs longer than 200,000 characters.
|
|
452
|
+
* Numeric budgets are unchanged (ARR-B06 retains them).
|
|
453
|
+
* - Per-call memoization reuses repeated references without retaining
|
|
454
|
+
* caller objects across calls. Cached subtrees store their intrinsic
|
|
455
|
+
* height and revalidate `depth + height` on hits (ARR-B06), so a
|
|
456
|
+
* subtree first seen shallowly cannot be reused deeper past the
|
|
457
|
+
* depth limit; shared and copied over-depth structures both throw
|
|
458
|
+
* independent of visitation order.
|
|
459
|
+
* - Obviously oversized strings/property names are preflighted on raw
|
|
460
|
+
* length before `JSON.stringify` (escaping only grows the encoded
|
|
461
|
+
* form), and excessive object/array width is preflighted on counts
|
|
462
|
+
* (plus a lower-bound output check) before sorting/iteration
|
|
463
|
+
* (ARR-B06). Oversized diagnostics are truncated by length.
|
|
409
464
|
*
|
|
410
465
|
* Unsupported values — `bigint`, `function`, `symbol`, accessor
|
|
411
466
|
* properties, cycles, and non-plain built-in objects (`RegExp`,
|
|
@@ -413,6 +468,22 @@ declare class RequestKeyError extends Error {
|
|
|
413
468
|
*
|
|
414
469
|
* Never invokes a getter: an accessor property detected via
|
|
415
470
|
* `Object.getOwnPropertyDescriptor` is rejected before any access.
|
|
471
|
+
* The same descriptor-first policy covers array indices (including
|
|
472
|
+
* inherited accessors at sparse holes) and top-level request-config
|
|
473
|
+
* properties via `requestConfigKeyInput` (whose `signal` key is skipped
|
|
474
|
+
* by name before any read). Date instants use the captured intrinsic.
|
|
475
|
+
*
|
|
476
|
+
* Proxy boundary: the reflective operations above
|
|
477
|
+
* (`getOwnPropertyDescriptor`, `getPrototypeOf`, `Object.keys`,
|
|
478
|
+
* `getOwnPropertySymbols`) can trigger proxy traps. Safe introspection
|
|
479
|
+
* of arbitrary proxies is not promised; pass plain wire data.
|
|
480
|
+
*
|
|
481
|
+
* Residual limits (ARR-B06, honest bounds): the budgets bound accepted
|
|
482
|
+
* output and first-visit traversal, not all temporary work. Enumerating
|
|
483
|
+
* `Object.keys` / descriptors over a caller object is inherently
|
|
484
|
+
* input-sized, and escaping may expand strings up to ~6x per character
|
|
485
|
+
* before the post-encoding output check fires. No absolute CPU/memory
|
|
486
|
+
* bound for arbitrary caller objects is claimed.
|
|
416
487
|
*/
|
|
417
488
|
declare function requestKeyFor(value: unknown): string;
|
|
418
489
|
|