@web-ts-toolkit/access-router-client 0.43.0 → 0.44.0

package/README.md

@@ -29,15 +29,17 @@ pnpm add @web-ts-toolkit/access-router-client
 This remediation release tightens several public runtime and TypeScript
 contracts. When upgrading from the previous client contract:
 
-| Area                                 | Before                                                                                                                         | After / required migration                                                                                                                                                                                                                                          |
-| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Subdocuments                         | Results could expose parent-backed `Model<S>` values and `save()`.                                                             | Results are plain objects/arrays. Persist with the parent-scoped `subs(...)` helper's `update`, `create`, `bulkUpdate`, or `delete` methods.                                                                                                                        |
-| Create and list counts               | Subdocument create looked scalar and subdocument lists used `totalCount`; model create was scalar-only.                        | Subdocument create accepts one or many and always returns the post-create array with `count`. Model create preserves input cardinality: object -> `ModelResponse`, array -> `ArrayModelResponse`. Model/data lists retain `totalCount`.                             |
-| Responses                            | Failure `data` and success fields could not be narrowed reliably.                                                              | Branch on `result.success`. Success has non-null `raw`/`data`; failure has `data: null` and the problem payload in `raw`. Model/data `totalCount` defaults to `0` when metadata is unavailable; read subdocument `count` after success.                             |
-| Cache                                | An enabled cache could be unbounded and credentialed requests did not require an explicit identity partition.                  | Cache is still off by default (`cacheTTL: 0`). Enabled caches admit supported GETs only, default to a 100-entry LRU, and require `cachePartition` for credentialed requests. Clear on identity changes and dispose on teardown.                                     |
-| Grouping                             | A lazy request could be replayed or moved between direct and grouped execution; batch error policy could drift by entry.       | Each lazy request can be claimed once. Create a new request to execute again. All group members must share one effective `throwOnError` policy. Non-throwing batches return all entries; throwing batches run all callbacks and then reject with the first failure. |
-| Protocol types                       | Data permission options, object/tuple data sorts, and a count access argument were accepted. Filters were broadly permissive.  | Remove `includePermissions` from data calls, use string data sorts, call `countAdvanced(filter, config?)`, and fix invalid `FilterQuery<T>` values. Use `DottedPathFilter<T>` or `ServerSideCast<T>` only as explicit escape hatches.                               |
-| Paths, config, and model persistence | Dynamic path values were interpolated directly, inputs could be mutated, and projected models could lose persistence identity. | Pass raw path values for one-pass encoding; caller configs stay immutable. ID-based projected reads retain identity, while an existing model with no recoverable identity throws `MissingPersistenceIdentityError`. Use `set()`/`markModified()` for nested edits.  |
+| Area                                 | Before                                                                                                                         | After / required migration                                                                                                                                                                                                                                                                                                                                                                                                               |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Subdocuments                         | Results could expose parent-backed `Model<S>` values and `save()`.                                                             | Results are plain objects/arrays. Persist with the parent-scoped `subs(...)` helper's `update`, `create`, `bulkUpdate`, or `delete` methods.                                                                                                                                                                                                                                                                                             |
+| Create and list counts               | Subdocument create looked scalar and subdocument lists used `totalCount`; model create was scalar-only.                        | Subdocument create accepts one or many and always returns the post-create array with `count`. Model create preserves input cardinality: object -> `ModelResponse`, array -> `ArrayModelResponse`. Model/data lists retain `totalCount`.                                                                                                                                                                                                  |
+| Responses                            | Failure `data` and success fields could not be narrowed reliably.                                                              | Branch on `result.success`. Success has non-null `raw`/`data`; failure has `data: null` and the problem payload in `raw`. Model/data `totalCount` defaults to `0` when metadata is unavailable; read subdocument `count` after success.                                                                                                                                                                                                  |
+| Cache                                | An enabled cache could be unbounded and credentialed requests did not require an explicit identity partition.                  | Cache is still off by default (`cacheTTL: 0`). Enabled caches admit supported GETs only, default to a 100-entry LRU, and require `cachePartition` for credentialed requests. Clear on identity changes and dispose on teardown.                                                                                                                                                                                                          |
+| Grouping                             | A lazy request could be replayed or moved between direct and grouped execution; batch error policy could drift by entry.       | Each lazy request can be claimed once. Create a new request to execute again. All group members must share one effective `throwOnError` policy. Non-throwing batches return all entries; throwing batches run all callbacks and then reject with the first failure.                                                                                                                                                                      |
+| Protocol types                       | Data permission options, object/tuple data sorts, and a count access argument were accepted. Filters were broadly permissive.  | Remove `includePermissions` from data calls, use string data sorts, call `countAdvanced(filter, config?)`, and fix invalid `FilterQuery<T>` values. Use `DottedPathFilter<T>` or `ServerSideCast<T>` only as explicit escape hatches.                                                                                                                                                                                                    |
+| Paths, config, and model persistence | Dynamic path values were interpolated directly, inputs could be mutated, and projected models could lose persistence identity. | Pass raw path values for one-pass encoding; caller configs stay immutable. ID-based projected reads retain identity, while an existing model with no recoverable identity throws `MissingPersistenceIdentityError`. Use `set()`/`markModified()` for nested edits (dot, bracket-index, and quoted-key forms share one dirty root).                                                                                                       |
+| Service defaults and subqueries      | Nested `Date` defaults could serialize as `{}` and accepted `sq` defaults were ignored without per-call `sq`.                  | Service defaults accept null, string, boolean, finite numbers, valid `Date` values (detached per request), plain objects, and arrays; functions, symbols, bigints, non-finite numbers, invalid `Date` values, non-plain instances, and cycles throw `UnsupportedServiceDefaultValueError`. Adapter/service/per-call `sq` precedence applies on `list`, `listAdvanced`, `read`, `readAdvanced`, and `readAdvancedFilter` (per-call wins). |
+| Distinct result types                | `distinct`/`distinctAdvanced` were typed `Response<string[]>`, so string methods compiled on numeric/boolean server values.    | Both variants return `Response<unknown[]>` with no server-value stringification. Narrow elements (for example `typeof v === 'string'`) before calling string methods.                                                                                                                                                                                                                                                                    |
 
 Grouped entry `headers` are now `{}` because the root protocol has no
 per-operation headers. Structured grouped failure fields remain in `raw`.
@@ -101,8 +103,9 @@ consumer needs:
   Browser cookie credentials, explicit `Authorization`/proxy authorization
   headers, API-key style headers, and Node `Cookie` headers supplied on the
   request config are all treated as credentialed.
-  Sensitive headers (`authorization`, `cookie`, `set-cookie`,
-  `proxy-authorization`, `www-authenticate`) are excluded from cache keys
+  Sensitive headers (`authorization`, `cookie`, `proxy-authorization`,
+  `x-api-key`, `x-auth-token`, `x-access-token`, `set-cookie`,
+  `www-authenticate`) are excluded from cache keys
   regardless of the partition token. Only GET requests with supported JSON or
   text response semantics are cached; mutations and custom transforms or
   serializers always bypass caching. `cacheTTL` is measured in milliseconds;

package/index.d.mts

@@ -289,8 +289,21 @@ declare class ModelService<T extends Document, TCreateInput extends object = Mod
     upsertAdvanced<TData extends Partial<T> | never = never, TSelect extends Projection = Projection>(data: TUpsertInput, args?: UpsertAdvancedArgs<TSelect>, options?: UpsertAdvancedOptions, axiosRequestConfig?: RequestConfig$1): ModelRequest<ModelResponse<T, ResolvedSelectedShape<T, TSelect, TData>>>;
     delete(identifier: string, axiosRequestConfig?: RequestConfig$1): ModelPromiseMeta & LazyRequest<Response<string>>;
     new<TData extends Partial<T> = T>(axiosRequestConfig?: RequestConfig$1): ModelPromiseMeta & LazyRequest<ModelResponse<T, TData>>;
-    distinct(field: string, axiosRequestConfig?: RequestConfig$1): ModelPromiseMeta & LazyRequest<Response<string[]>>;
-    distinctAdvanced(field: string, conditions: FilterQuery<T>, axiosRequestConfig?: RequestConfig$1): ModelPromiseMeta & LazyRequest<Response<string[]>>;
+    /**
+     * BND-11: distinct values are `unknown[]`, not `string[]`. The sibling
+     * server returns raw distinct values without string conversion, so numeric
+     * and boolean values arrive as-is. Source-compat: callers that assumed
+     * `string[]` must narrow first (e.g. `typeof v === 'string'` or a type
+     * guard) before calling string methods; see the BND-11 task record for
+     * migration. No server values are stringified to satisfy the old type.
+     */
+    distinct(field: string, axiosRequestConfig?: RequestConfig$1): ModelPromiseMeta & LazyRequest<Response<unknown[]>>;
+    /**
+     * BND-11: filtered distinct variant. Same `unknown[]` contract as
+     * {@link distinct}: narrow elements before assuming strings. No
+     * stringification is applied; dynamic field names are accepted as `string`.
+     */
+    distinctAdvanced(field: string, conditions: FilterQuery<T>, axiosRequestConfig?: RequestConfig$1): ModelPromiseMeta & LazyRequest<Response<unknown[]>>;
     count(axiosRequestConfig?: RequestConfig$1): ModelPromiseMeta & LazyRequest<Response<number>>;
     countAdvanced(filter: FilterQuery<T>, axiosRequestConfig?: RequestConfig$1): ModelPromiseMeta & LazyRequest<Response<number>>;
     read<TData extends Partial<T> = T>(identifier: string, options?: ReadOptions, axiosRequestConfig?: RequestConfig$1): ModelPromiseMeta & LazyRequest<ModelResponse<T, TData>>;
@@ -494,15 +507,11 @@ declare class Model<T extends Document, TData extends Partial<T> = T> {
     private trackModified;
     private normalizePath;
     /**
-     * Removes `path` from the dirty set when its current top-level value deeply
-     * equals the snapshot baseline. Used uniformly by `set()`, `assign()`,
-     * public property setters (via the proxy), and `markModified()` so all
-     * entry points share the same tracking rule.
-     *
-     * Note: `_id` is intentionally never reconciled away here — it is excluded
-     * from `initializeDirtyState` and managed explicitly during `save()`
-     * reconciliation.
+     * Removes `path` from the dirty set when its current value deeply equals
+     * the snapshot baseline. Invariant: unsaved drafts never reconcile clean
+     * (snapshot is unpersisted); `_id` is never reconciled here.
      */
+    private isUnsavedDraft;
     private reconcilePath;
 }
 /**

package/index.d.ts

@@ -289,8 +289,21 @@ declare class ModelService<T extends Document, TCreateInput extends object = Mod
     upsertAdvanced<TData extends Partial<T> | never = never, TSelect extends Projection = Projection>(data: TUpsertInput, args?: UpsertAdvancedArgs<TSelect>, options?: UpsertAdvancedOptions, axiosRequestConfig?: RequestConfig$1): ModelRequest<ModelResponse<T, ResolvedSelectedShape<T, TSelect, TData>>>;
     delete(identifier: string, axiosRequestConfig?: RequestConfig$1): ModelPromiseMeta & LazyRequest<Response<string>>;
     new<TData extends Partial<T> = T>(axiosRequestConfig?: RequestConfig$1): ModelPromiseMeta & LazyRequest<ModelResponse<T, TData>>;
-    distinct(field: string, axiosRequestConfig?: RequestConfig$1): ModelPromiseMeta & LazyRequest<Response<string[]>>;
-    distinctAdvanced(field: string, conditions: FilterQuery<T>, axiosRequestConfig?: RequestConfig$1): ModelPromiseMeta & LazyRequest<Response<string[]>>;
+    /**
+     * BND-11: distinct values are `unknown[]`, not `string[]`. The sibling
+     * server returns raw distinct values without string conversion, so numeric
+     * and boolean values arrive as-is. Source-compat: callers that assumed
+     * `string[]` must narrow first (e.g. `typeof v === 'string'` or a type
+     * guard) before calling string methods; see the BND-11 task record for
+     * migration. No server values are stringified to satisfy the old type.
+     */
+    distinct(field: string, axiosRequestConfig?: RequestConfig$1): ModelPromiseMeta & LazyRequest<Response<unknown[]>>;
+    /**
+     * BND-11: filtered distinct variant. Same `unknown[]` contract as
+     * {@link distinct}: narrow elements before assuming strings. No
+     * stringification is applied; dynamic field names are accepted as `string`.
+     */
+    distinctAdvanced(field: string, conditions: FilterQuery<T>, axiosRequestConfig?: RequestConfig$1): ModelPromiseMeta & LazyRequest<Response<unknown[]>>;
     count(axiosRequestConfig?: RequestConfig$1): ModelPromiseMeta & LazyRequest<Response<number>>;
     countAdvanced(filter: FilterQuery<T>, axiosRequestConfig?: RequestConfig$1): ModelPromiseMeta & LazyRequest<Response<number>>;
     read<TData extends Partial<T> = T>(identifier: string, options?: ReadOptions, axiosRequestConfig?: RequestConfig$1): ModelPromiseMeta & LazyRequest<ModelResponse<T, TData>>;
@@ -494,15 +507,11 @@ declare class Model<T extends Document, TData extends Partial<T> = T> {
     private trackModified;
     private normalizePath;
     /**
-     * Removes `path` from the dirty set when its current top-level value deeply
-     * equals the snapshot baseline. Used uniformly by `set()`, `assign()`,
-     * public property setters (via the proxy), and `markModified()` so all
-     * entry points share the same tracking rule.
-     *
-     * Note: `_id` is intentionally never reconciled away here — it is excluded
-     * from `initializeDirtyState` and managed explicitly during `save()`
-     * reconciliation.
+     * Removes `path` from the dirty set when its current value deeply equals
+     * the snapshot baseline. Invariant: unsaved drafts never reconcile clean
+     * (snapshot is unpersisted); `_id` is never reconciled here.
      */
+    private isUnsavedDraft;
     private reconcilePath;
 }
 /**