@web-ts-toolkit/access-router-client 0.38.0 → 0.40.0

package/README.md

@@ -98,12 +98,16 @@ consumer needs:
   defaults to `'__mutation'`; `rootRouterPath` defaults to `'root'`.
 - **Cache & authentication policy:** credentialed requests are **never**
   cached unless `cachePartition` returns a stable, non-secret identity token.
+  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
   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: 0` (the default) disables the
-  cache entirely, while enabled caches retain at most 100 entries by default.
+  serializers always bypass caching. `cacheTTL` is measured in milliseconds;
+  `cacheTTL: 0` (the default) disables the cache entirely, while enabled caches
+  retain at most 100 entries by default.
   `clearCache()` drops every cached entry; `disposeCache()`
   drops entries and releases cache timers (call on adapter teardown so timers
   do not keep a Node process alive).
@@ -139,6 +143,15 @@ consumer needs:
 - **Model create cardinality:** `create(...)` and `createAdvanced(...)` accept
   either one object or an array. Scalar input returns `ModelResponse<T>`;
   array input returns `ArrayModelResponse<T>`, including for a one-item array.
+- **Mutation input types:** model create/update/upsert payloads default to
+  `ModelMutationInput<T>` (`Partial<T>`), so object literals are checked for
+  known field names and scalar types without pretending the server can infer
+  required create fields. Pass `createModelService<T, TCreateInput,
+TUpdateInput, TUpsertInput>(...)` when request schemas differ from the
+  response model. Subdocument create/update helpers use
+  `SubDocumentMutationInput<S>` (`Partial<S>` for object subdocuments) by
+  default and can be customized through `subs<S, K, TCreateInput,
+TUpdateInput>(...)`.
 - **Nested model edits:** `Model<T>` tracks modified top-level paths and
   reconciles writes against the last loaded/saved snapshot. Direct mutation
   of nested objects/arrays (`obj.arr.push(...)`, `obj.sub.field = x`) is
@@ -146,12 +159,18 @@ consumer needs:
   or `markModified('topLevelField')` after a direct mutation (forces dirty
   without reconciling). Reverting a value to its snapshot clears the dirty
   flag. `save()` persists only tracked modified top-level fields; if `_id`
-  exists it calls `update(...)`, otherwise it calls `create(...)`.
+  exists it calls `update(...)`, otherwise it calls `create(...)`. Multiple
+  overlapping `save()` calls on the same wrapper are serialized in call order.
+  Document fields named like model methods (`save`, `reset`, `set`, `get`,
+  `assign`, `toJSON`, etc.) are reserved for the wrapper API on direct
+  property access; use `get(...)`, `set(...)`, `assign(...)`, or `toObject()`
+  for those data fields. The exported `ModelData<T>` helper reflects that
+  reserved-name contract in response and `Model.create(...)` types.
 - **Supported runtimes:** Node 22+ and modern evergreen browsers (see
   [Supported Runtimes](#supported-runtimes) and
   [Browser And Node Support](#browser-and-node-support) above).
 
-## Main Exports
+## Primary Exports
 
 The package is named-export-only (no default export). Import every public
 symbol from the package root:
@@ -174,9 +193,9 @@ import {
   // Thrown instead of creating a duplicate when an existing projected model
   // has no recoverable persistence identity.
   MissingPersistenceIdentityError,
-  // Lazy-promise wrapper with non-enumerable metadata and a single
-  // shared execution. Used internally by service methods; exported so
-  // consumers can build compatible lazy promises for custom batches.
+  // Low-level lazy-promise wrapper with a single shared execution. Service
+  // methods add private adapter metadata required by `adapter.group(...)`;
+  // consumer-created wrappers execute directly and are not groupable.
   wrapLazyPromise,
   // Normalized response-count / pagination header names.
   CustomHeaders,
@@ -202,6 +221,7 @@ import type {
   ModelResponse,
   ArrayModelResponse,
   ListModelResponse,
+  ModelData,
   DataResponse,
   ArrayDataResponse,
   ListDataResponse,
@@ -213,6 +233,8 @@ import type {
   DataDefaults,
   // Filter, projection, populate, sort, and request-meta primitives.
   FilterQuery,
+  ModelMutationInput,
+  SubDocumentMutationInput,
   DottedPathFilter,
   ServerSideCast,
   Projection,
@@ -247,6 +269,7 @@ type StablePublicTypes = [
   ModelResponse<Document>,
   ArrayModelResponse<Document>,
   ListModelResponse<Document>,
+  ModelData<Document>,
   DataResponse<unknown>,
   ArrayDataResponse<unknown>,
   ListDataResponse<unknown>,
@@ -255,6 +278,8 @@ type StablePublicTypes = [
   Defaults,
   DataDefaults,
   FilterQuery<Document>,
+  ModelMutationInput<Document>,
+  SubDocumentMutationInput<{ label: string }>,
   DottedPathFilter<Document>,
   ServerSideCast<Document>,
   Projection,
@@ -265,9 +290,9 @@ type StablePublicTypes = [
 void (null as unknown as StablePublicTypes);
 ```
 
-Only the names above are part of the stable public surface. The package
-ships a runtime export contract test (`access-router-client.exports.unit.test.ts`)
-that fails on accidental additions or removals, so implementation internals
+The names above are the primary public imports most consumers need. The full
+root export inventory is locked by `access-router-client.exports.unit.test.ts`
+and mirrored in `llms.txt`, so implementation internals
 such as `useCacheInterceptors`, `cloneConfigWithCacheBypass`,
 `finalizeRootEntry`, `applyGroupCallbacks`, `makeRequest`, `createWrapHelper`,
 `ADAPTER_ID_KEY`, `STARTED_KEY`, `CACHE_HEADER`, `CachePolicy`, and `RootEntry`
@@ -278,29 +303,27 @@ through the returned adapter's `clearCache()` and `disposeCache()` methods.
 ## Browser And Node Support
 
 - **Bundle target:** `es2022` (see `tsup.config.ts`). The single shared target
-  runs in Node 22+ and all evergreen browsers without transpilation; the
-  source imports no Node built-ins.
+  runs in Node 22+ and the documented evergreen browser floor without
+  transpilation; the source imports no Node built-ins.
 - **Runtime metadata:** `engines.node: ">=22"` (npm/pnpm warn or refuse on
-  older Node) and `browserslist: ["supports es2022-module"]` (bundler tools
-  narrow to the same matrix). Unsupported environments fail clearly via
-  engine warnings rather than appearing accidentally supported.
+  older Node) and `browserslist: ["chrome >= 94", "edge >= 94", "firefox >= 93", "safari >= 16"]`.
+  `pnpm exec browserslist` resolves this package config without error.
 - **Authentication contract:** `withCredentials: true` is the adapter
-  default, so the browser runtime transmits cookies + the `Authorization`
-  header and the cache partitions credentialed requests via the
-  `cachePartition` option (see [Cache Controls](#cache-controls)). In Node,
-  `withCredentials` is honored by Axios's HTTP adapter the same way for
-  `Cookie` headers you set manually; credentialed caching still requires an
-  explicit `cachePartition` token so one identity cannot receive another's
-  cached response.
+  default, so browser requests may include cookies when CORS and cookie policy
+  allow them. `Authorization`, proxy authorization, API-key style headers, and
+  Node `Cookie` headers are explicit Axios config values; `withCredentials`
+  does not create them. Credentialed caching still requires an explicit
+  `cachePartition` token so one identity cannot receive another's cached
+  response.
 - **Cache timers:** the in-memory cache uses `setTimeout`/`clearTimeout`
   (available in both runtimes). The optional Node `unref()` guard is
   feature-detected and is a no-op in browsers, so `clearCache()` and
   `disposeCache()` are safe to call in either runtime.
 - **Smoke test:** `pnpm --filter @web-ts-toolkit/access-router-client
 test:browser-smoke` (powered by Vite + jsdom) imports the _built_
-  `dist/index.mjs` under a browser environment and exercises the public
-  runtime surface. It fails if a Node built-in leaks into the bundle or the
-  bundle emits syntax the declared `browserslist` floor cannot run. This
+  `dist/index.mjs` under a browser-like environment and exercises the public
+  runtime surface. It is a smoke check for Node built-in leaks and basic ESM
+  browser bundling, not a real-browser engine/version compatibility gate. This
   smoke test also runs as part of the default `pnpm test` for the package.
 
 ## Documentation

package/index.d.mts

@@ -207,7 +207,7 @@ declare class Service {
     private _wrap;
     private _throwOnError;
     constructor(axios: AxiosInstance, basePath: string, throwOnError?: boolean);
-    protected handleSuccess(res: AxiosResponse<unknown, unknown>, extra?: {}): Response<unknown>;
+    protected handleSuccess<T extends Response<unknown, unknown> = Response<unknown>>(res: AxiosResponse<unknown, unknown>, extra?: {}): T;
     protected handleError<T extends Response<unknown, unknown>>(error: unknown): Extract<T, FailureResult>;
     /** Resolves per-call policy against the already-resolved service/adapter default. */
     resolveThrowOnError(override?: boolean): boolean;
@@ -271,7 +271,8 @@ interface Props$1 {
  * const userService = adapter.createModelService<User>({ modelName: 'User', basePath: 'users' });
  * const user = await userService.read('user-id-1');
  */
-declare class ModelService<T extends Document> extends Service {
+type InferredSubDocument<T, K extends keyof T, S> = [S] extends [never] ? NonNullable<T[K]> extends readonly (infer TItem)[] ? TItem : never : S;
+declare class ModelService<T extends Document, TCreateInput extends object = ModelMutationInput<T>, TUpdateInput extends object = ModelMutationInput<T>, TUpsertInput extends object = ModelMutationInput<T>> extends Service {
     private _modelName;
     private _queryPath;
     private _mutationPath;
@@ -280,12 +281,12 @@ declare class ModelService<T extends Document> extends Service {
     constructor({ axios, modelName, basePath, queryPath, mutationPath, onSuccess, onFailure, throwOnError }: Props$1, defaults?: Defaults);
     list<TData extends Partial<T> = T>(args?: ListArgs, options?: ListOptions, axiosRequestConfig?: RequestConfig$1): ModelPromiseMeta & LazyRequest<ListModelResponse<T, TData>>;
     listAdvanced<TData extends Partial<T> | never = never, TSelect extends Projection = Projection>(filter: FilterQuery<T>, args?: ListAdvancedArgs<TSelect>, options?: ListAdvancedOptions, axiosRequestConfig?: RequestConfig$1): ModelRequest<ListModelResponse<T, ResolvedSelectedShape<T, TSelect, TData>>>;
-    create<TData extends Partial<T> = T>(data: object[], options?: CreateOptions, axiosRequestConfig?: RequestConfig$1): ModelRequest<ArrayModelResponse<T, TData>>;
-    create<TData extends Partial<T> = T>(data: object, options?: CreateOptions, axiosRequestConfig?: RequestConfig$1): ModelRequest<ModelResponse<T, TData>>;
-    createAdvanced<TData extends Partial<T> | never = never, TSelect extends Projection = Projection>(data: object[], args?: CreateAdvancedArgs<TSelect>, options?: CreateAdvancedOptions, axiosRequestConfig?: RequestConfig$1): ModelRequest<ArrayModelResponse<T, ResolvedSelectedShape<T, TSelect, TData>>>;
-    createAdvanced<TData extends Partial<T> | never = never, TSelect extends Projection = Projection>(data: object, args?: CreateAdvancedArgs<TSelect>, options?: CreateAdvancedOptions, axiosRequestConfig?: RequestConfig$1): ModelRequest<ModelResponse<T, ResolvedSelectedShape<T, TSelect, TData>>>;
-    upsert<TData extends Partial<T> = T>(data: object, options?: UpsertOptions, axiosRequestConfig?: RequestConfig$1): ModelPromiseMeta & LazyRequest<ModelResponse<T, TData>>;
-    upsertAdvanced<TData extends Partial<T> | never = never, TSelect extends Projection = Projection>(data: object, args?: UpsertAdvancedArgs<TSelect>, options?: UpsertAdvancedOptions, axiosRequestConfig?: RequestConfig$1): ModelRequest<ModelResponse<T, ResolvedSelectedShape<T, TSelect, TData>>>;
+    create<TData extends Partial<T> = T>(data: TCreateInput[], options?: CreateOptions, axiosRequestConfig?: RequestConfig$1): ModelRequest<ArrayModelResponse<T, TData>>;
+    create<TData extends Partial<T> = T>(data: TCreateInput, options?: CreateOptions, axiosRequestConfig?: RequestConfig$1): ModelRequest<ModelResponse<T, TData>>;
+    createAdvanced<TData extends Partial<T> | never = never, TSelect extends Projection = Projection>(data: TCreateInput[], args?: CreateAdvancedArgs<TSelect>, options?: CreateAdvancedOptions, axiosRequestConfig?: RequestConfig$1): ModelRequest<ArrayModelResponse<T, ResolvedSelectedShape<T, TSelect, TData>>>;
+    createAdvanced<TData extends Partial<T> | never = never, TSelect extends Projection = Projection>(data: TCreateInput, args?: CreateAdvancedArgs<TSelect>, options?: CreateAdvancedOptions, axiosRequestConfig?: RequestConfig$1): ModelRequest<ModelResponse<T, ResolvedSelectedShape<T, TSelect, TData>>>;
+    upsert<TData extends Partial<T> = T>(data: TUpsertInput, options?: UpsertOptions, axiosRequestConfig?: RequestConfig$1): ModelPromiseMeta & LazyRequest<ModelResponse<T, TData>>;
+    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[]>>;
@@ -295,36 +296,36 @@ declare class ModelService<T extends Document> extends Service {
     read<TData extends Partial<T> = T>(identifier: string, options?: ReadOptions, axiosRequestConfig?: RequestConfig$1): ModelPromiseMeta & LazyRequest<ModelResponse<T, TData>>;
     readAdvanced<TData extends Partial<T> | never = never, TSelect extends Projection = Projection>(identifier: string, args?: ReadAdvancedArgs<TSelect>, options?: ReadAdvancedOptions, axiosRequestConfig?: RequestConfig$1): ModelRequest<ModelResponse<T, ResolvedSelectedShape<T, TSelect, TData>>>;
     readAdvancedFilter<TData extends Partial<T> | never = never, TSelect extends Projection = Projection>(filter: FilterQuery<T>, args?: ReadAdvancedArgs<TSelect>, options?: ReadAdvancedOptions, axiosRequestConfig?: RequestConfig$1): ModelRequest<ModelResponse<T, ResolvedSelectedShape<T, TSelect, TData>>>;
-    update<TData extends Partial<T> = T>(identifier: string, data: object, options?: UpdateOptions, axiosRequestConfig?: RequestConfig$1): ModelPromiseMeta & LazyRequest<ModelResponse<T, TData>>;
-    updateAdvanced<TData extends Partial<T> | never = never, TSelect extends Projection = Projection>(identifier: string, data: object, args?: UpdateAdvancedArgs<TSelect>, options?: UpdateAdvancedOptions, axiosRequestConfig?: RequestConfig$1): ModelRequest<ModelResponse<T, ResolvedSelectedShape<T, TSelect, TData>>>;
+    update<TData extends Partial<T> = T>(identifier: string, data: TUpdateInput, options?: UpdateOptions, axiosRequestConfig?: RequestConfig$1): ModelPromiseMeta & LazyRequest<ModelResponse<T, TData>>;
+    updateAdvanced<TData extends Partial<T> | never = never, TSelect extends Projection = Projection>(identifier: string, data: TUpdateInput, args?: UpdateAdvancedArgs<TSelect>, options?: UpdateAdvancedOptions, axiosRequestConfig?: RequestConfig$1): ModelRequest<ModelResponse<T, ResolvedSelectedShape<T, TSelect, TData>>>;
     id(id: string): {
-        subs: <S = never, K extends keyof T = keyof T>(field: K) => {
+        subs: <S = never, K extends keyof T = keyof T, TSubCreateInput = SubDocumentMutationInput<InferredSubDocument<T, K, S>>, TSubUpdateInput = SubDocumentMutationInput<InferredSubDocument<T, K, S>>>(field: K) => {
             list: (axiosRequestConfig?: AxiosRequestConfig<any, any> & {
                 throwOnError?: boolean;
-            }) => ModelPromiseMeta & LazyRequest<SubDocumentListResponse<[S] extends [never] ? NonNullable<T[K]> extends readonly (infer TItem)[] ? TItem : never : S>>;
-            listAdvanced: <TData extends Partial<[S] extends [never] ? NonNullable<T[K]> extends readonly (infer TItem)[] ? TItem : never : S> = never, TSelect extends readonly string[] = readonly string[]>(filter?: FilterQuery<[S] extends [never] ? NonNullable<T[K]> extends readonly (infer TItem)[] ? TItem : never : S>, args?: {
+            }) => ModelPromiseMeta & LazyRequest<SubDocumentListResponse<InferredSubDocument<T, K, S>>>;
+            listAdvanced: <TData extends Partial<InferredSubDocument<T, K, S>> = never, TSelect extends readonly string[] = readonly string[]>(filter?: FilterQuery<InferredSubDocument<T, K, S>>, args?: {
                 select?: TSelect;
             }, axiosRequestConfig?: AxiosRequestConfig<any, any> & {
                 throwOnError?: boolean;
-            }) => ModelPromiseMeta & LazyRequest<SubDocumentListResponse<[S] extends [never] ? NonNullable<T[K]> extends readonly (infer TItem)[] ? TItem : never : S, ResolvedSelectedShape<[S] extends [never] ? NonNullable<T[K]> extends readonly (infer TItem)[] ? TItem : never : S, TSelect, TData>>>;
+            }) => ModelPromiseMeta & LazyRequest<SubDocumentListResponse<InferredSubDocument<T, K, S>, ResolvedSelectedShape<InferredSubDocument<T, K, S>, TSelect, TData>>>;
             read: (subId: string, axiosRequestConfig?: AxiosRequestConfig<any, any> & {
                 throwOnError?: boolean;
-            }) => ModelPromiseMeta & LazyRequest<SubDocumentResponse<[S] extends [never] ? NonNullable<T[K]> extends readonly (infer TItem)[] ? TItem : never : S>>;
-            readAdvanced: <TData extends Partial<[S] extends [never] ? NonNullable<T[K]> extends readonly (infer TItem)[] ? TItem : never : S> = never, TSelect_1 extends readonly string[] = readonly string[]>(subId: string, args?: {
+            }) => ModelPromiseMeta & LazyRequest<SubDocumentResponse<InferredSubDocument<T, K, S>>>;
+            readAdvanced: <TData extends Partial<InferredSubDocument<T, K, S>> = never, TSelect_1 extends readonly string[] = readonly string[]>(subId: string, args?: {
                 select?: TSelect_1;
                 populate?: unknown;
             }, axiosRequestConfig?: AxiosRequestConfig<any, any> & {
                 throwOnError?: boolean;
-            }) => ModelPromiseMeta & LazyRequest<SubDocumentResponse<[S] extends [never] ? NonNullable<T[K]> extends readonly (infer TItem)[] ? TItem : never : S, ResolvedSelectedShape<[S] extends [never] ? NonNullable<T[K]> extends readonly (infer TItem)[] ? TItem : never : S, TSelect_1, TData>>>;
-            update: (subId: string, data: object, axiosRequestConfig?: AxiosRequestConfig<any, any> & {
+            }) => ModelPromiseMeta & LazyRequest<SubDocumentResponse<InferredSubDocument<T, K, S>, ResolvedSelectedShape<InferredSubDocument<T, K, S>, TSelect_1, TData>>>;
+            update: (subId: string, data: TSubUpdateInput, axiosRequestConfig?: AxiosRequestConfig<any, any> & {
                 throwOnError?: boolean;
-            }) => ModelPromiseMeta & LazyRequest<SubDocumentResponse<[S] extends [never] ? NonNullable<T[K]> extends readonly (infer TItem)[] ? TItem : never : S>>;
-            bulkUpdate: (data: object[], axiosRequestConfig?: AxiosRequestConfig<any, any> & {
+            }) => ModelPromiseMeta & LazyRequest<SubDocumentResponse<InferredSubDocument<T, K, S>>>;
+            bulkUpdate: (data: TSubUpdateInput[], axiosRequestConfig?: AxiosRequestConfig<any, any> & {
                 throwOnError?: boolean;
-            }) => ModelPromiseMeta & LazyRequest<SubDocumentListResponse<[S] extends [never] ? NonNullable<T[K]> extends readonly (infer TItem)[] ? TItem : never : S>>;
-            create: (data: object | object[], axiosRequestConfig?: AxiosRequestConfig<any, any> & {
+            }) => ModelPromiseMeta & LazyRequest<SubDocumentListResponse<InferredSubDocument<T, K, S>>>;
+            create: (data: TSubCreateInput | TSubCreateInput[], axiosRequestConfig?: AxiosRequestConfig<any, any> & {
                 throwOnError?: boolean;
-            }) => ModelPromiseMeta & LazyRequest<SubDocumentListResponse<[S] extends [never] ? NonNullable<T[K]> extends readonly (infer TItem)[] ? TItem : never : S>>;
+            }) => ModelPromiseMeta & LazyRequest<SubDocumentListResponse<InferredSubDocument<T, K, S>>>;
             delete: (subId: string, axiosRequestConfig?: AxiosRequestConfig<any, any> & {
                 throwOnError?: boolean;
             }) => ModelPromiseMeta & LazyRequest<Response<string>>;
@@ -380,16 +381,19 @@ declare class MissingPersistenceIdentityError extends Error {
 /**
  * A dirty-tracking wrapper around a model document. Constructed via
  * {@link ModelService.create}, {@link ModelService.read},
- * {@link ModelService.findOne}, or the list methods that return
+ * {@link ModelService.readAdvanced}, or the list methods that return
  * `Model<T>[]`. Property access through the wrapper directly reads/writes
  * the underlying data; `save()` persists only the paths flagged dirty
  * since the last save and merges the server response per the documented
  * concurrency contract.
  *
- * `Model.create<T>(data, service)` is typed as `Model<T, TData> & TData` so
- * callers can read/write fields directly on the wrapper (`user.role =
- * 'owner'`) while still calling `save()`/`reset()`/`isDirty(...)`. The
- * returned wrapper is a fresh snapshot of the post-operation local state;
+ * `Model.create<T>(data, service)` is typed as `Model<T, TData> &
+ * ModelData<T, TData>` so callers can read/write ordinary fields directly on
+ * the wrapper (`user.role = 'owner'`) while still calling
+ * `save()`/`reset()`/`isDirty(...)`. Fields whose names collide with public
+ * model methods or properties are reserved for the wrapper API and remain
+ * reachable through `get(...)`, `set(...)`, `assign(...)`, and `toObject()`.
+ * The returned wrapper is a fresh snapshot of the post-operation local state;
  * mutating it does not affect sibling wrappers created from the same
  * underlying document.
  *
@@ -411,32 +415,37 @@ declare class Model<T extends Document, TData extends Partial<T> = T> {
     private _snapshot;
     private readonly _service;
     private modifiedPaths;
+    private _saveQueue;
     private _persistenceId;
     private readonly _fromExisting;
     constructor(data: TData, adapter: ModelService<T>, persistenceId?: string, fromExisting?: boolean);
-    static create<T extends Document, TData extends Partial<T> = T>(data: TData, adapter: ModelService<T>, persistenceId?: string, fromExisting?: boolean): Model<T, TData> & TData;
+    static create<T extends Document, TData extends Partial<T> = T>(data: TData, adapter: ModelService<T>, persistenceId?: string, fromExisting?: boolean): Model<T, TData> & ModelData<T, TData>;
     /**
      * Persists the currently dirty paths to the server, then merges the
      * server's response back into local state.
      *
      * Concurrency contract:
      *
-     * 1. Submitted paths and their values are snapshotted before the request
+     * 1. Multiple `save()` calls on the same wrapper are serialized in call
+     *    order. A later save snapshots its dirty paths only after the previous
+     *    save has finished reconciling, so overlapping callers cannot submit
+     *    the same stale dirty set concurrently.
+     * 2. Submitted paths and their values are snapshotted before the request
      *    starts, so an in-flight response cannot wipe edits that were made
      *    while the request was pending.
-     * 2. On success, a submitted path is cleared from `modifiedPaths` only if
+     * 3. On success, a submitted path is cleared from `modifiedPaths` only if
      *    its current local value still equals the submitted value — i.e. the
      *    user has not concurrently re-edited it to a different value.
-     * 3. Server-returned values overwrite local values for paths the user did
+     * 4. Server-returned values overwrite local values for paths the user did
      *    NOT concurrently re-modify during the in-flight save; for paths the
      *    user did concurrently re-modify, the local value is preserved and
      *    the dirty flag is retained so the concurrent edit is resubmitted on
      *    the next `save()`. (Deterministic conflict rule: the newer local
      *    edit wins for the same path; the server value becomes its reset
      *    baseline without replacing the newer local value.)
-     * 4. On failure, no dirty state is cleared and no local value is
+     * 5. On failure, no dirty state is cleared and no local value is
      *    overwritten; the caller can retry `save()` with the same set.
-     * 5. The return value echoes `{ ...result, data }` where `data` is a
+     * 6. The return value echoes `{ ...result, data }` where `data` is a
      *    refreshed `Model` snapshot of the post-save local state (or `null`
      *    on failure), matching `ModelResponse<T, TData>`.
      *
@@ -452,6 +461,7 @@ declare class Model<T extends Document, TData extends Partial<T> = T> {
      * of POSTing a new document.
      */
     save(reqConfig?: AxiosRequestConfig): Promise<ModelResponse<T, TData>>;
+    private saveNow;
     isDirty(path?: keyof TData | string): boolean;
     /**
      * Marks a path dirty and skips snapshot reconciliation. This is the
@@ -495,6 +505,16 @@ declare class Model<T extends Document, TData extends Partial<T> = T> {
      */
     private reconcilePath;
 }
+/**
+ * Directly exposed data fields for a `Model` wrapper.
+ *
+ * Runtime property forwarding reserves public `Model` member names such as
+ * `save`, `reset`, `set`, `get`, `assign`, `toObject`, and `toJSON` for the
+ * wrapper API. Documents may still contain those field names, but callers must
+ * access them via `get(...)`, `set(...)`, `assign(...)`, or `toObject()` rather
+ * than ordinary direct property access.
+ */
+type ModelData<T extends Document, TData extends Partial<T> = T> = Omit<TData, keyof Model<T, TData>>;
 
 type AnyArray<T> = T[] | ReadonlyArray<T>;
 type Unpacked<T> = T extends (infer U)[] ? U : T extends ReadonlyArray<infer U> ? U : T;
@@ -512,7 +532,8 @@ type Unpacked<T> = T extends (infer U)[] ? U : T extends ReadonlyArray<infer U>
  * (dynamic dotted paths and explicit server-side casting).
  */
 type ApplyBasicQueryCasting<T> = T | T[] | (T extends AnyArray<unknown> ? Unpacked<T> : never) | (T extends string ? RegExp : never);
-type Condition<T> = ApplyBasicQueryCasting<T> | QuerySelector<ApplyBasicQueryCasting<T>> | LazyRequest<unknown>;
+type QueryOperatorOperand<T> = T extends AnyArray<unknown> ? Unpacked<T> : T;
+type Condition<T> = ApplyBasicQueryCasting<T> | QuerySelector<T> | LazyRequest<unknown>;
 type _FilterQuery<T> = {
     [P in keyof T]?: Condition<T[P]>;
 } & RootQuerySelector<T>;
@@ -536,15 +557,15 @@ type RootQuerySelector<T> = {
     $comment?: string;
 };
 type QuerySelector<T> = {
-    $eq?: T;
-    $gt?: T;
-    $gte?: T;
-    $in?: [T] extends AnyArray<unknown> ? Unpacked<T>[] : T[];
-    $lt?: T;
-    $lte?: T;
-    $ne?: T;
-    $nin?: [T] extends AnyArray<unknown> ? Unpacked<T>[] : T[];
-    $not?: T extends string ? QuerySelector<T> | RegExp : QuerySelector<T>;
+    $eq?: ApplyBasicQueryCasting<T>;
+    $gt?: QueryOperatorOperand<T>;
+    $gte?: QueryOperatorOperand<T>;
+    $in?: QueryOperatorOperand<T>[];
+    $lt?: QueryOperatorOperand<T>;
+    $lte?: QueryOperatorOperand<T>;
+    $ne?: ApplyBasicQueryCasting<T>;
+    $nin?: QueryOperatorOperand<T>[];
+    $not?: QueryOperatorOperand<T> extends string ? QuerySelector<T> | RegExp : QuerySelector<T>;
     /**
      * When `true`, `$exists` matches the documents that contain the field,
      * including documents where the field value is null.
@@ -553,9 +574,9 @@ type QuerySelector<T> = {
     $type?: string | number;
     $expr?: unknown;
     $jsonSchema?: unknown;
-    $mod?: T extends number ? [number, number] : never;
-    $regex?: T extends string ? RegExp | string : never;
-    $options?: T extends string ? string : never;
+    $mod?: QueryOperatorOperand<T> extends number ? [number, number] : never;
+    $regex?: QueryOperatorOperand<T> extends string ? RegExp | string : never;
+    $options?: QueryOperatorOperand<T> extends string ? string : never;
 };
 /**
  * Escape hatch for dynamic dotted paths and explicit server-side casting.
@@ -648,6 +669,19 @@ interface Populate {
 interface Document {
     _id?: string;
 }
+/**
+ * Default request payload type for model mutations.
+ *
+ * The sibling access-router runtime accepts generic records and does not know
+ * a consumer application's required create/update schema. The client therefore
+ * defaults mutation inputs to `Partial<T>` so known fields are checked without
+ * claiming compile-time requiredness. Consumers with distinct request schemas
+ * can pass explicit `ModelService<T, TCreateInput, TUpdateInput, TUpsertInput>`
+ * or `createModelService<T, ...>(...)` generics.
+ */
+type ModelMutationInput<T extends Document> = Partial<T>;
+/** Default request payload type for subdocument create/update helpers. */
+type SubDocumentMutationInput<T> = T extends object ? Partial<T> : T;
 /**
  * Successful response. `raw` and `data` are non-null and `success` is
  * narrowed to `true` so `if (result.success)` exposes the documented
@@ -689,8 +723,8 @@ interface FailureResult<TError = unknown> {
  * type unless a caller explicitly chooses that error type.
  */
 type Response<T1, T2 = T1, TError = unknown> = SuccessResult<T1, T2> | FailureResult<TError>;
-type ModelResponse<T extends Document, TData extends Partial<T> = T> = Response<TData, Model<T, TData> & TData>;
-type ArrayModelResponse<T extends Document, TData extends Partial<T> = T> = Response<TData[], (Model<T, TData> & TData)[]>;
+type ModelResponse<T extends Document, TData extends Partial<T> = T> = Response<TData, Model<T, TData> & ModelData<T, TData>>;
+type ArrayModelResponse<T extends Document, TData extends Partial<T> = T> = Response<TData[], (Model<T, TData> & ModelData<T, TData>)[]>;
 /**
  * `ListModelResponse` always carries `totalCount` on both branches. The field
  * defaults to `0` at runtime on failure or when the server did not emit count
@@ -828,11 +862,12 @@ type CachePartitioner = (config: InternalAxiosRequestConfig) => string | undefin
  *
  * Cache controls (only in effect when `cacheTTL > 0`):
  *
- * - `cacheTTL` — seconds a cached GET response is reused before revalidation.
+ * - `cacheTTL` — milliseconds a cached GET response is reused before revalidation.
  * - `cachePartition` — required to cache credentialed requests safely (see
- *   {@link CachePartitioner}); credentialed requests without a stable,
- *   non-secret partition token bypass the cache so one identity cannot
- *   receive a response created under another.
+ *   {@link CachePartitioner}); requests using browser cookies,
+ *   `withCredentials`, or explicit auth headers without a stable, non-secret
+ *   partition token bypass the cache so one identity cannot receive a
+ *   response created under another.
  * - `cacheCapacity` — bounds the number of cached entries; defaults to 100 and
  *   evicts the LRU entry when the limit is exceeded.
  *
@@ -847,11 +882,11 @@ interface AdapterOptions {
     throwOnError?: boolean;
     cacheTTL?: number;
     /**
-     * Partition strategy for credentialed cache entries. When the adapter is
-     * credentialed (which is the default), caching is only enabled for requests
-     * whose `cachePartition` returns a stable, non-secret identity token. Requests
-     * without a partition key bypass the cache so that one identity can never
-     * receive a response created under another identity.
+     * Partition strategy for credentialed cache entries. When a request uses
+     * browser cookies, `withCredentials`, or explicit auth headers, caching is
+     * only enabled when `cachePartition` returns a stable, non-secret identity
+     * token. Requests without a partition key bypass the cache so that one
+     * identity can never receive a response created under another identity.
      *
      * The returned value must be a stable, non-secret token (for example a user
      * id or tenant id). Never return raw cookies, authorization values, or other
@@ -935,7 +970,7 @@ declare function createAdapter(axiosConfig?: AxiosRequestConfig, adapterOptions?
     axios: axios.AxiosInstance;
     clearCache: () => void;
     disposeCache: () => void;
-    createModelService: <T extends Document>({ modelName, basePath, queryPath, mutationPath, onSuccess, onFailure, throwOnError, }: ModelServiceOptions, defaults?: Defaults) => ModelService<T>;
+    createModelService: <T extends Document, TCreateInput extends object = Partial<T>, TUpdateInput extends object = Partial<T>, TUpsertInput extends object = Partial<T>>({ modelName, basePath, queryPath, mutationPath, onSuccess, onFailure, throwOnError, }: ModelServiceOptions, defaults?: Defaults) => ModelService<T, TCreateInput, TUpdateInput, TUpsertInput>;
     createDataService: <T>({ dataName, basePath, queryPath, onSuccess, onFailure, throwOnError }: DataServiceOptions, defaults?: DataDefaults) => DataService<T>;
     wrapGet: <T = unknown>(url: string, defaultConfig?: AxiosRequestConfig) => (options?: WrapOptions, requestConfig?: AxiosRequestConfig) => Promise<axios.AxiosResponse<T, any, {}, any>>;
     wrapPost: <T = unknown>(url: string, defaultConfig?: AxiosRequestConfig) => (data?: unknown, options?: WrapOptions, requestConfig?: AxiosRequestConfig) => Promise<axios.AxiosResponse<T, any, {}, any>>;
@@ -964,4 +999,4 @@ declare function removeItemById<T extends {
     _id: string;
 }>(items: T[], targetItem: T): T[];
 
-export { type AdapterOptions, type AdditionalReqConfig, type ArrayDataResponse, type ArrayModelResponse, type CacheController, type CachePartitioner, type CreateAdvancedArgs, type CreateAdvancedOptions, type CreateOptions, CustomHeaders, type DataDefaults, type DataListAdvancedArgs, type DataListAdvancedOptions, type DataListArgs, type DataListOptions, type DataPromiseMeta, type DataReadAdvancedArgs, type DataReadAdvancedOptions, type DataReadOptions, type DataRequest, type DataResponse, DataService, type DataServiceOptions, type Defaults, type Document, type DottedPathFilter, type FailureResult, type FilterQuery, type Include, type KeyValueProjection, type LazyRequest, type ListAdvancedArgs, type ListAdvancedOptions, type ListArgs, type ListDataResponse, type ListModelResponse, type ListOptions, MissingPersistenceIdentityError, Model, type ModelPromiseMeta, type ModelRequest, type ModelResponse, ModelService, type ModelServiceOptions, type Populate, type PopulateAccess, type Projection, type ReadAdvancedArgs, type ReadAdvancedOptions, type ReadOptions, type ResolvedSelectedShape, type Response, type ResponseCallback, type ResultError, type RootDataQueryMeta, type RootModelQueryMeta, type RootQueryMeta, type SelectedKeys, type SelectedShape, type ServerSideCast, Service, ServiceError, type Sort, type SortOrder, type SubDocumentListResponse, type SubDocumentResponse, type SubQueryOptions, type SuccessResult, type Task, type UpdateAdvancedArgs, type UpdateAdvancedOptions, type UpdateOptions, type UpsertAdvancedArgs, type UpsertAdvancedOptions, type UpsertOptions, type WrapOptions, createAdapter, removeItemById, replaceItemById, wrapLazyPromise };
+export { type AdapterOptions, type AdditionalReqConfig, type ArrayDataResponse, type ArrayModelResponse, type CacheController, type CachePartitioner, type CreateAdvancedArgs, type CreateAdvancedOptions, type CreateOptions, CustomHeaders, type DataDefaults, type DataListAdvancedArgs, type DataListAdvancedOptions, type DataListArgs, type DataListOptions, type DataPromiseMeta, type DataReadAdvancedArgs, type DataReadAdvancedOptions, type DataReadOptions, type DataRequest, type DataResponse, DataService, type DataServiceOptions, type Defaults, type Document, type DottedPathFilter, type FailureResult, type FilterQuery, type Include, type KeyValueProjection, type LazyRequest, type ListAdvancedArgs, type ListAdvancedOptions, type ListArgs, type ListDataResponse, type ListModelResponse, type ListOptions, MissingPersistenceIdentityError, Model, type ModelData, type ModelMutationInput, type ModelPromiseMeta, type ModelRequest, type ModelResponse, ModelService, type ModelServiceOptions, type Populate, type PopulateAccess, type Projection, type ReadAdvancedArgs, type ReadAdvancedOptions, type ReadOptions, type ResolvedSelectedShape, type Response, type ResponseCallback, type ResultError, type RootDataQueryMeta, type RootModelQueryMeta, type RootQueryMeta, type SelectedKeys, type SelectedShape, type ServerSideCast, Service, ServiceError, type Sort, type SortOrder, type SubDocumentListResponse, type SubDocumentMutationInput, type SubDocumentResponse, type SubQueryOptions, type SuccessResult, type Task, type UpdateAdvancedArgs, type UpdateAdvancedOptions, type UpdateOptions, type UpsertAdvancedArgs, type UpsertAdvancedOptions, type UpsertOptions, type WrapOptions, createAdapter, removeItemById, replaceItemById, wrapLazyPromise };