@web-ts-toolkit/access-router-react 0.43.0 → 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 CHANGED
@@ -64,7 +64,8 @@ function OrganizationList() {
64
64
 
65
65
  return (
66
66
  <div>
67
- <button disabled={isPending} onClick={() => mutate({ name: 'Northwind Labs' })}>
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
- 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;
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, 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';
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). Reuses the client's exported
20
- * {@link SelectedKeys} utility (no divergent React approximation) to
21
- * decide whether the consumer supplied a *literal* projection
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 literal `select` was supplied, the
28
- * shape collapses to `Model<T, ResolvedSelectedShape<T, TSelect, never>>`
29
- * intersected with the computed selected shape: every key the
30
- * consumer asked for stays definitely-present, every other model key
31
- * becomes `T[keyof T] | undefined` via the client's
32
- * `Pick<T, SelectedKeys<T, TSelect>> & Partial<T>` definition. A
33
- * consumer that selects only `['name']` will see `data.status` typed
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 literal
48
- * projection supplies a literal `TSelect` (TypeScript infers it from
49
- * the `select?: TSelect` field on the hook options) and the narrow
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 literal `select`
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 literal projection and accepts responsibility for forwarding it
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> = [SelectedKeys<T, TSelect>] extends [never] ? Model<T> & T : Model<T, ResolvedSelectedShape<T, TSelect, never>> & ResolvedSelectedShape<T, TSelect, never>;
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> = [SelectedKeys<T, TSelect>] extends [
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 literal `select`, otherwise
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
- * - Arrays map to `[<key(e1)>,<key(e2)>,...]` recursively.
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, 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';
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). Reuses the client's exported
20
- * {@link SelectedKeys} utility (no divergent React approximation) to
21
- * decide whether the consumer supplied a *literal* projection
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 literal `select` was supplied, the
28
- * shape collapses to `Model<T, ResolvedSelectedShape<T, TSelect, never>>`
29
- * intersected with the computed selected shape: every key the
30
- * consumer asked for stays definitely-present, every other model key
31
- * becomes `T[keyof T] | undefined` via the client's
32
- * `Pick<T, SelectedKeys<T, TSelect>> & Partial<T>` definition. A
33
- * consumer that selects only `['name']` will see `data.status` typed
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 literal
48
- * projection supplies a literal `TSelect` (TypeScript infers it from
49
- * the `select?: TSelect` field on the hook options) and the narrow
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 literal `select`
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 literal projection and accepts responsibility for forwarding it
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> = [SelectedKeys<T, TSelect>] extends [never] ? Model<T> & T : Model<T, ResolvedSelectedShape<T, TSelect, never>> & ResolvedSelectedShape<T, TSelect, never>;
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> = [SelectedKeys<T, TSelect>] extends [
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 literal `select`, otherwise
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
- * - Arrays map to `[<key(e1)>,<key(e2)>,...]` recursively.
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