@web-ts-toolkit/access-router-react 0.47.1 → 0.49.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
@@ -85,6 +85,7 @@ function OrganizationList() {
85
85
  return (
86
86
  <div>
87
87
  {/* Hook error state (createError) still surfaces the failure; the catch only avoids an unhandled rejection. */}
88
+
88
89
  <button disabled={isPending} onClick={() => void mutate({ name: 'Northwind Labs' }).catch(() => undefined)}>
89
90
  Create
90
91
  </button>
@@ -353,7 +354,7 @@ The narrowing is applied uniformly to `data`, `onSuccess(result)`/`onSettled(res
353
354
 
354
355
  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.
355
356
 
356
- 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.
357
+ On the `read`/`list`/`update` hooks a literal `select` reaches the server on both paths — as a `?select=` query value on the basic path and as body `select` with `advanced: true` — so the narrowed type matches the wire payload there. The basic `create`/`upsert` APIs accept no `select` argument, so a literal `select` on those two hooks still requires `advanced: true` to actually reach the server's narrowing code path; the type still narrows without `advanced`, but the wire payload is unchanged — you opt into the narrowed type and accept responsibility for forwarding it down the advanced path.
357
358
 
358
359
  ## Dependency-Key Policy
359
360
 
package/index.d.mts CHANGED
@@ -78,16 +78,18 @@ type NarrowedDataShape<T extends Document, S extends Projection> = Model<T, Reso
78
78
  * shape is computed automatically.
79
79
  *
80
80
  * Note: this is a *static* narrowing — the runtime promise is whatever
81
- * the server returns. When `advanced === false`, `select` is NOT
82
- * forwarded to the server (the basic `read`/`list`/`create`/etc. do
83
- * not accept a `select` argument) so the server returns a full model
84
- * and the client response is a full `T`. The type still has the
85
- * provided `TSelect` (if any) applied; supplying a `select`
86
- * without `advanced: true` produces a tighter type than the wire
87
- * payload really justifies. The package treats this as a documented
88
- * consumer contract — narrow types only when the consumer opted into
89
- * a projection and accepts responsibility for forwarding it
90
- * down a path that honors it (the `advanced` paths).
81
+ * the server returns. `select` is forwarded to the server on the
82
+ * `read`/`list`/`update` paths — as a `?select=` query value on the
83
+ * basic paths and as body `select` on the `advanced` paths — so the
84
+ * narrowed type matches the wire payload there. The basic
85
+ * `create`/`upsert` APIs accept no `select` argument (the server
86
+ * exposes no such parameter on the plain routes), so supplying a
87
+ * `select` without `advanced: true` on those two hooks produces a
88
+ * tighter type than the wire payload really justifies. The package
89
+ * treats this as a documented consumer contract — narrow types only
90
+ * when the consumer opted into a projection and accepts
91
+ * responsibility for forwarding it down a path that honors it (the
92
+ * `advanced` paths for create/upsert).
91
93
  *
92
94
  * Declaration tightening (ARR-B03): dynamic, exclusion-only, and union
93
95
  * selections no longer resolve to the full required model. Consumers
@@ -144,9 +146,9 @@ interface UseReadQueryOptions<T extends Document, TSelect extends Projection = P
144
146
  * projection-aware result so omitted properties become
145
147
  * `T[keyof T] | undefined` rather than definitely-present; this is
146
148
  * the static reflection of the server actually dropping those
147
- * fields from the response when `advanced === true`. Requires
148
- * `advanced: true` for the projection to take effect at the request
149
- * layer (the basic `read` API does not forward `select`).
149
+ * fields from the response. The projection is forwarded on both
150
+ * paths — as a `?select=` query value on the basic path and as
151
+ * body `select` when `advanced === true`.
150
152
  */
151
153
  select?: TSelect;
152
154
  populate?: ReadAdvancedArgs['populate'];
@@ -180,6 +182,13 @@ interface UseListQueryOptions<T extends Document, TSelect extends Projection = P
180
182
  listParams?: ListArgs;
181
183
  filter?: FilterQuery<T>;
182
184
  advanced?: boolean;
185
+ /**
186
+ * List ordering. Accepts the general `Sort` string/object/tuple forms;
187
+ * forwarded on both paths — as a `?sort=` query value on the basic
188
+ * path and as body `sort` when `advanced === true`. An explicit
189
+ * `sort` inside `listParams` (or manual `query()` args) wins when
190
+ * both are supplied, mirroring the advanced-path merge.
191
+ */
183
192
  sort?: ListAdvancedArgs['sort'];
184
193
  /**
185
194
  * Server-side field projection (Task ARR-09). Supply a *literal*
@@ -187,8 +196,11 @@ interface UseListQueryOptions<T extends Document, TSelect extends Projection = P
187
196
  * (`'name'`), or a `{ name: 1 }` object to narrow the list element
188
197
  * shape on {@link UseListQueryResult.data}, the `onSuccess`/`onSettled`
189
198
  * callback result payloads, and the manual `query()`/`refetch()`
190
- * response payloads. Requires `advanced: true` for the basic
191
- * `list` API does not forward `select`.
199
+ * response payloads. The projection is forwarded on both paths —
200
+ * as a `?select=` query value on the basic path and as body
201
+ * `select` when `advanced === true`. An explicit `select` inside
202
+ * `listParams` (or manual `query()` args) wins when both are
203
+ * supplied, mirroring the advanced-path merge.
192
204
  */
193
205
  select?: TSelect;
194
206
  populate?: ListAdvancedArgs['populate'];
@@ -250,8 +262,13 @@ interface UseCreateMutateResult<T extends Document, TSelect extends Projection =
250
262
  interface UseUpdateMutateOptions<T extends Document, TSelect extends Projection = Projection> extends UseBaseOptions {
251
263
  advanced?: boolean;
252
264
  /**
253
- * Server-side field projection (Task ARR-09). See
254
- * {@link UseCreateMutateOptions.select}.
265
+ * Server-side field projection (Task ARR-09). Supply a literal
266
+ * tuple/string/object projection to narrow the update response
267
+ * `data` shape on {@link UseUpdateMutateResult.data}, the
268
+ * `onSuccess`/`onSettled` callback result payloads, and the
269
+ * `mutate()` return promise. The projection is forwarded on both
270
+ * paths — as a `?select=` query value on the basic path and as
271
+ * body `select` when `advanced === true`.
255
272
  */
256
273
  select?: TSelect;
257
274
  populate?: UpdateAdvancedArgs['populate'];
package/index.d.ts CHANGED
@@ -78,16 +78,18 @@ type NarrowedDataShape<T extends Document, S extends Projection> = Model<T, Reso
78
78
  * shape is computed automatically.
79
79
  *
80
80
  * Note: this is a *static* narrowing — the runtime promise is whatever
81
- * the server returns. When `advanced === false`, `select` is NOT
82
- * forwarded to the server (the basic `read`/`list`/`create`/etc. do
83
- * not accept a `select` argument) so the server returns a full model
84
- * and the client response is a full `T`. The type still has the
85
- * provided `TSelect` (if any) applied; supplying a `select`
86
- * without `advanced: true` produces a tighter type than the wire
87
- * payload really justifies. The package treats this as a documented
88
- * consumer contract — narrow types only when the consumer opted into
89
- * a projection and accepts responsibility for forwarding it
90
- * down a path that honors it (the `advanced` paths).
81
+ * the server returns. `select` is forwarded to the server on the
82
+ * `read`/`list`/`update` paths — as a `?select=` query value on the
83
+ * basic paths and as body `select` on the `advanced` paths — so the
84
+ * narrowed type matches the wire payload there. The basic
85
+ * `create`/`upsert` APIs accept no `select` argument (the server
86
+ * exposes no such parameter on the plain routes), so supplying a
87
+ * `select` without `advanced: true` on those two hooks produces a
88
+ * tighter type than the wire payload really justifies. The package
89
+ * treats this as a documented consumer contract — narrow types only
90
+ * when the consumer opted into a projection and accepts
91
+ * responsibility for forwarding it down a path that honors it (the
92
+ * `advanced` paths for create/upsert).
91
93
  *
92
94
  * Declaration tightening (ARR-B03): dynamic, exclusion-only, and union
93
95
  * selections no longer resolve to the full required model. Consumers
@@ -144,9 +146,9 @@ interface UseReadQueryOptions<T extends Document, TSelect extends Projection = P
144
146
  * projection-aware result so omitted properties become
145
147
  * `T[keyof T] | undefined` rather than definitely-present; this is
146
148
  * the static reflection of the server actually dropping those
147
- * fields from the response when `advanced === true`. Requires
148
- * `advanced: true` for the projection to take effect at the request
149
- * layer (the basic `read` API does not forward `select`).
149
+ * fields from the response. The projection is forwarded on both
150
+ * paths — as a `?select=` query value on the basic path and as
151
+ * body `select` when `advanced === true`.
150
152
  */
151
153
  select?: TSelect;
152
154
  populate?: ReadAdvancedArgs['populate'];
@@ -180,6 +182,13 @@ interface UseListQueryOptions<T extends Document, TSelect extends Projection = P
180
182
  listParams?: ListArgs;
181
183
  filter?: FilterQuery<T>;
182
184
  advanced?: boolean;
185
+ /**
186
+ * List ordering. Accepts the general `Sort` string/object/tuple forms;
187
+ * forwarded on both paths — as a `?sort=` query value on the basic
188
+ * path and as body `sort` when `advanced === true`. An explicit
189
+ * `sort` inside `listParams` (or manual `query()` args) wins when
190
+ * both are supplied, mirroring the advanced-path merge.
191
+ */
183
192
  sort?: ListAdvancedArgs['sort'];
184
193
  /**
185
194
  * Server-side field projection (Task ARR-09). Supply a *literal*
@@ -187,8 +196,11 @@ interface UseListQueryOptions<T extends Document, TSelect extends Projection = P
187
196
  * (`'name'`), or a `{ name: 1 }` object to narrow the list element
188
197
  * shape on {@link UseListQueryResult.data}, the `onSuccess`/`onSettled`
189
198
  * callback result payloads, and the manual `query()`/`refetch()`
190
- * response payloads. Requires `advanced: true` for the basic
191
- * `list` API does not forward `select`.
199
+ * response payloads. The projection is forwarded on both paths —
200
+ * as a `?select=` query value on the basic path and as body
201
+ * `select` when `advanced === true`. An explicit `select` inside
202
+ * `listParams` (or manual `query()` args) wins when both are
203
+ * supplied, mirroring the advanced-path merge.
192
204
  */
193
205
  select?: TSelect;
194
206
  populate?: ListAdvancedArgs['populate'];
@@ -250,8 +262,13 @@ interface UseCreateMutateResult<T extends Document, TSelect extends Projection =
250
262
  interface UseUpdateMutateOptions<T extends Document, TSelect extends Projection = Projection> extends UseBaseOptions {
251
263
  advanced?: boolean;
252
264
  /**
253
- * Server-side field projection (Task ARR-09). See
254
- * {@link UseCreateMutateOptions.select}.
265
+ * Server-side field projection (Task ARR-09). Supply a literal
266
+ * tuple/string/object projection to narrow the update response
267
+ * `data` shape on {@link UseUpdateMutateResult.data}, the
268
+ * `onSuccess`/`onSettled` callback result payloads, and the
269
+ * `mutate()` return promise. The projection is forwarded on both
270
+ * paths — as a `?select=` query value on the basic path and as
271
+ * body `select` when `advanced === true`.
255
272
  */
256
273
  select?: TSelect;
257
274
  populate?: UpdateAdvancedArgs['populate'];
package/index.js CHANGED
@@ -771,7 +771,7 @@ function createModelHooks(config) {
771
771
  assertSuccess(raw2);
772
772
  return raw2;
773
773
  }
774
- const raw = await modelService.read(targetId, basicOptions, forwardedConfig).exec();
774
+ const raw = await modelService.read(targetId, { select }, basicOptions, forwardedConfig).exec();
775
775
  assertSuccess(raw);
776
776
  return raw;
777
777
  },
@@ -907,7 +907,7 @@ function createModelHooks(config) {
907
907
  assertSuccess(raw2);
908
908
  return raw2;
909
909
  }
910
- const raw = await modelService.list(effectiveArgs, basicOptions, forwardedConfig).exec();
910
+ const raw = await modelService.list({ sort, select, ...effectiveArgs }, basicOptions, forwardedConfig).exec();
911
911
  assertSuccess(raw);
912
912
  return raw;
913
913
  },
@@ -1066,7 +1066,7 @@ function createModelHooks(config) {
1066
1066
  requestConfig
1067
1067
  ).exec();
1068
1068
  } else {
1069
- res = await modelService.update(updateId, updateData, basicOptions, requestConfig).exec();
1069
+ res = await modelService.update(updateId, updateData, { select }, basicOptions, requestConfig).exec();
1070
1070
  }
1071
1071
  assertSuccess(res);
1072
1072
  return res;
package/index.mjs CHANGED
@@ -743,7 +743,7 @@ function createModelHooks(config) {
743
743
  assertSuccess(raw2);
744
744
  return raw2;
745
745
  }
746
- const raw = await modelService.read(targetId, basicOptions, forwardedConfig).exec();
746
+ const raw = await modelService.read(targetId, { select }, basicOptions, forwardedConfig).exec();
747
747
  assertSuccess(raw);
748
748
  return raw;
749
749
  },
@@ -879,7 +879,7 @@ function createModelHooks(config) {
879
879
  assertSuccess(raw2);
880
880
  return raw2;
881
881
  }
882
- const raw = await modelService.list(effectiveArgs, basicOptions, forwardedConfig).exec();
882
+ const raw = await modelService.list({ sort, select, ...effectiveArgs }, basicOptions, forwardedConfig).exec();
883
883
  assertSuccess(raw);
884
884
  return raw;
885
885
  },
@@ -1038,7 +1038,7 @@ function createModelHooks(config) {
1038
1038
  requestConfig
1039
1039
  ).exec();
1040
1040
  } else {
1041
- res = await modelService.update(updateId, updateData, basicOptions, requestConfig).exec();
1041
+ res = await modelService.update(updateId, updateData, { select }, basicOptions, requestConfig).exec();
1042
1042
  }
1043
1043
  assertSuccess(res);
1044
1044
  return res;
package/package.json CHANGED
@@ -2,7 +2,7 @@
2
2
  "name": "@web-ts-toolkit/access-router-react",
3
3
  "description": "React hooks for @web-ts-toolkit/access-router-client model services",
4
4
  "homepage": "https://web-ts-toolkit.pages.dev/docs/packages/access-router-react",
5
- "version": "0.47.1",
5
+ "version": "0.49.0",
6
6
  "keywords": [
7
7
  "react",
8
8
  "hooks",
@@ -31,7 +31,7 @@
31
31
  "node": ">=22"
32
32
  },
33
33
  "peerDependencies": {
34
- "@web-ts-toolkit/access-router-client": "0.47.1",
34
+ "@web-ts-toolkit/access-router-client": "0.49.0",
35
35
  "react": "^18.0.0 || ^19.0.0"
36
36
  },
37
37
  "files": [