@lossless.org/client 1.6.0 → 1.8.0

package/ts/nosqldb/classes.doc.ts

@@ -25,6 +25,7 @@ import {
 import { SmartdataDbWatcher } from './classes.watcher.js';
 import { SmartdataLuceneAdapter } from './classes.lucene.adapter.js';
 import { executeAtomicDelete, executeAtomicDeleteMany } from './classes.atomicdelete.js';
+import { requireOperationSignal } from './classes.operationdeadline.js';
 import {
   executeAtomicFindOneAndReplace, executeAtomicFindOneAndUpdate,
 } from './classes.atomicfindoneandupdate.js';
@@ -664,7 +665,14 @@ export interface ISmartdataOffsetPageOptions<T> {
   projection?: TSmartdataProjection<T>;
   hint?: string;
   maxTimeMS?: number;
-  /** Defaults to 5000ms; maximum 120000ms. Covers the cursor's entire lifetime. */
+  /**
+   * Defaults to 5000ms; maximum 120000ms. Covers the cursor up to its last
+   * reply. A page larger than the first batch that stalls in its `getMore`
+   * settles within about twice the deadline: the driver's `killCursors` runs
+   * on a fresh deadline of the same length before the error surfaces.
+   * Inside a transaction with its own deadline that deadline replaces the
+   * default, and an explicit value is refused.
+   */
   timeoutMS?: number;
   signal?: AbortSignal;
   session?: TSmartdataOrdinarySession;
@@ -673,6 +681,8 @@ export interface ISmartdataOffsetPageOptions<T> {
 export interface ISmartdataFindOneOptions<T> {
   projection?: TSmartdataProjection<T>;
   maxTimeMS?: number;
+  /** Client-side deadline for the call's database work (1..120000 ms), including model initialization, server selection and pool waits. */
+  timeoutMS?: number;
   session?: TSmartdataOrdinarySession;
 }
 
@@ -765,7 +775,12 @@ export interface ISmartdataGroupedTotalsOptions<T> {
    */
   limit: number;
   maxTimeMS?: number;
-  /** Client-side deadline for the complete aggregation cursor lifetime. */
+  /**
+   * Client-side deadline for the aggregation cursor up to its last reply. More
+   * groups than the first batch holds need a `getMore`; when that times out the
+   * driver's `killCursors` runs on a fresh deadline of the same length, so a
+   * stalled database settles the call within about twice the deadline.
+   */
   timeoutMS?: number;
   signal?: AbortSignal;
   session?: TSmartdataOrdinarySession;
@@ -943,6 +958,8 @@ export type TSmartdataAtomicFilter<T> =
 export interface ISmartdataAtomicUpdateOptions {
   upsert?: boolean;
   session?: TSmartdataOrdinarySession;
+  /** Client-side deadline for the call's database work (1..120000 ms), including model initialization, server selection and pool waits. */
+  timeoutMS?: number;
 }
 
 export interface ISmartdataAtomicUpdateResult {
@@ -969,6 +986,8 @@ export interface ISmartdataAtomicFindOneAndUpdateOptions<
    */
   sort?: TSmartdataSort<TModel>;
   session?: TSmartdataOrdinarySession;
+  /** Client-side deadline for the call's database work (1..120000 ms), including model initialization, server selection and pool waits. */
+  timeoutMS?: number;
 }
 
 export type TSmartdataAtomicFindOneAndUpdateResult<
@@ -989,6 +1008,8 @@ export interface ISmartdataAtomicFindOneAndReplaceOptions {
    */
   returnDocument?: TSmartdataAtomicReturnDocument;
   session?: TSmartdataOrdinarySession;
+  /** Client-side deadline for the call's database work (1..120000 ms), including model initialization, server selection and pool waits. */
+  timeoutMS?: number;
 }
 
 export interface ISmartdataAtomicDeleteOptions {
@@ -997,6 +1018,14 @@ export interface ISmartdataAtomicDeleteOptions {
   timeoutMS?: number;
 }
 
+export interface ISmartdataAtomicDeleteManyOptions extends ISmartdataAtomicDeleteOptions {
+  /**
+   * Cancels the call. An abort before the delete is sent deletes nothing; an
+   * abort in flight closes the connection and leaves the outcome unknown.
+   */
+  signal?: AbortSignal;
+}
+
 export interface ISmartdataInsertManyIfAbsentOptions<T> {
   /** A declared, non-serialized @unI identity field. */
   identityField: TSmartdataDocumentPath<T>;
@@ -1017,6 +1046,8 @@ export interface ISmartdataAtomicDeleteResult {
 
 export interface ISmartdataAtomicUpdateManyOptions {
   session?: TSmartdataOrdinarySession;
+  /** Client-side deadline for the call's database work (1..120000 ms), including model initialization, server selection and pool waits. */
+  timeoutMS?: number;
 }
 
 export interface ISmartdataAtomicUpdateManyResult {
@@ -1062,6 +1093,8 @@ export interface ISmartdataSaveIfOptions {
   session?: TSmartdataOrdinarySession;
   /** Defaults to `'ignore'`. */
   absentDeclaredFields?: TSmartdataAbsentDeclaredFields;
+  /** Client-side deadline for the write (1..120000 ms); `beforeSave()` and `afterSave()` run outside it. */
+  timeoutMS?: number;
 }
 
 export interface ISmartdataSaveIfResult {
@@ -1076,6 +1109,7 @@ const normalizeSaveIfOptions = (
 ): {
   session?: TSmartdataOrdinarySession;
   absentDeclaredFields: TSmartdataAbsentDeclaredFields;
+  timeoutMS?: number;
 } => {
   if (optionsArg === undefined) {
     return { absentDeclaredFields: 'ignore' };
@@ -1091,7 +1125,7 @@ const normalizeSaveIfOptions = (
       'Fenced save options must be an inert plain object.',
     );
   }
-  const allowedKeys = new Set(['session', 'absentDeclaredFields']);
+  const allowedKeys = new Set(['session', 'absentDeclaredFields', 'timeoutMS']);
   for (const key of Reflect.ownKeys(optionsArg)) {
     if (typeof key !== 'string' || !allowedKeys.has(key)) {
       throw new SmartdataPersistenceError(
@@ -1124,9 +1158,15 @@ const normalizeSaveIfOptions = (
   const session = Object.getOwnPropertyDescriptor(optionsArg, 'session')?.value as
     | TSmartdataOrdinarySession
     | undefined;
+  const timeoutMS = requireBoundedInteger(
+    Object.getOwnPropertyDescriptor(optionsArg, 'timeoutMS')?.value,
+    'Fenced save timeoutMS',
+    120_000,
+  );
   return {
     ...(session !== undefined ? { session } : {}),
     absentDeclaredFields: absentDeclaredFields ?? 'ignore',
+    ...(timeoutMS !== undefined ? { timeoutMS } : {}),
   };
 };
 
@@ -1139,6 +1179,7 @@ const normalizeAtomicFindOneAndUpdateOptions = <
   upsert: boolean;
   sort?: unknown;
   session?: TSmartdataOrdinarySession;
+  timeoutMS?: number;
 } => {
   if (
     typeof optionsArg !== 'object'
@@ -1151,7 +1192,7 @@ const normalizeAtomicFindOneAndUpdateOptions = <
       'Atomic find-one-and-update options must be an inert plain object.',
     );
   }
-  const allowedKeys = new Set(['returnDocument', 'upsert', 'sort', 'session']);
+  const allowedKeys = new Set(['returnDocument', 'upsert', 'sort', 'session', 'timeoutMS']);
   const keys = Reflect.ownKeys(optionsArg);
   for (const key of keys) {
     if (typeof key !== 'string' || !allowedKeys.has(key)) {
@@ -1195,6 +1236,11 @@ const normalizeAtomicFindOneAndUpdateOptions = <
   }
   const sortDescriptor = Object.getOwnPropertyDescriptor(optionsArg, 'sort');
   const sessionDescriptor = Object.getOwnPropertyDescriptor(optionsArg, 'session');
+  const timeoutMS = requireBoundedInteger(
+    Object.getOwnPropertyDescriptor(optionsArg, 'timeoutMS')?.value,
+    'Atomic find-one-and-update timeoutMS',
+    120_000,
+  );
   return {
     returnDocument: returnDocumentDescriptor.value as TReturnDocument,
     upsert: upsertDescriptor?.value === true,
@@ -1204,6 +1250,7 @@ const normalizeAtomicFindOneAndUpdateOptions = <
     ...(sessionDescriptor?.value !== undefined
       ? { session: sessionDescriptor.value as TSmartdataOrdinarySession }
       : {}),
+    ...(timeoutMS !== undefined ? { timeoutMS } : {}),
   };
 };
 
@@ -1212,6 +1259,7 @@ const normalizeAtomicFindOneAndReplaceOptions = (
 ): {
   returnDocument: TSmartdataAtomicReturnDocument;
   session?: TSmartdataOrdinarySession;
+  timeoutMS?: number;
 } => {
   if (optionsArg === undefined) {
     return { returnDocument: 'after' };
@@ -1227,7 +1275,7 @@ const normalizeAtomicFindOneAndReplaceOptions = (
       'Atomic find-one-and-replace options must be an inert plain object.',
     );
   }
-  const allowedKeys = new Set(['returnDocument', 'session']);
+  const allowedKeys = new Set(['returnDocument', 'session', 'timeoutMS']);
   for (const key of Reflect.ownKeys(optionsArg)) {
     if (typeof key !== 'string' || !allowedKeys.has(key)) {
       throw new SmartdataPersistenceError(
@@ -1258,9 +1306,15 @@ const normalizeAtomicFindOneAndReplaceOptions = (
   const session = Object.getOwnPropertyDescriptor(optionsArg, 'session')?.value as
     | TSmartdataOrdinarySession
     | undefined;
+  const timeoutMS = requireBoundedInteger(
+    Object.getOwnPropertyDescriptor(optionsArg, 'timeoutMS')?.value,
+    'Atomic find-one-and-replace timeoutMS',
+    120_000,
+  );
   return {
     returnDocument: returnDocument ?? 'after',
     ...(session !== undefined ? { session } : {}),
+    ...(timeoutMS !== undefined ? { timeoutMS } : {}),
   };
 };
 
@@ -1281,7 +1335,7 @@ const normalizeAtomicExpressionUpdateOptions = (
       'Atomic update options used with $expr must be an inert ordinary object.',
     );
   }
-  const allowedKeys = new Set(['upsert', 'session']);
+  const allowedKeys = new Set(['upsert', 'session', 'timeoutMS']);
   const normalized: ISmartdataAtomicUpdateOptions = {};
   for (const key of Reflect.ownKeys(optionsArg)) {
     if (typeof key !== 'string' || !allowedKeys.has(key)) {
@@ -1314,6 +1368,10 @@ const normalizeAtomicExpressionUpdateOptions = (
       if (descriptor.value !== undefined) {
         normalized.upsert = descriptor.value;
       }
+    } else if (key === 'timeoutMS') {
+      if (descriptor.value !== undefined) {
+        normalized.timeoutMS = descriptor.value as number;
+      }
     } else if (descriptor.value !== undefined) {
       normalized.session = descriptor.value as TSmartdataOrdinarySession;
     }
@@ -3947,7 +4005,11 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
   public static async insert<T extends SmartDataDbDoc<any, any>>(
     this: plugins.tsclass.typeFest.Class<T>,
     documentArg: T,
-    opts?: { session?: TSmartdataOrdinarySession },
+    opts?: {
+      session?: TSmartdataOrdinarySession;
+      /** Client-side deadline for the call's database work (1..120000 ms), including model initialization, server selection and pool waits. */
+      timeoutMS?: number;
+    },
   ): Promise<plugins.mongodb.InsertOneResult<{ _id: TSmartdataPrimaryId<T> }>> {
     if ((this as any)[exactPersistencePolicySymbol]) {
       throw new SmartdataPersistenceError(
@@ -3967,6 +4029,7 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
         'Model insert requires a newly constructed document.',
       );
     }
+    const timeoutMS = requireBoundedInteger(opts?.timeoutMS, 'Model insert timeoutMS', 120_000);
     assertUsableIdentityValues(
       documentArg as unknown as Record<string, unknown>,
       (this.prototype as { uniqueIndexes?: string[] }).uniqueIndexes || [],
@@ -3980,7 +4043,10 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
       documentArg._updatedAt = now;
     }
     const collection: SmartdataCollection<T> = (this as any).collection;
-    const result = await collection.insert(documentArg as any, opts);
+    const result = await collection.insert(documentArg as any, {
+      session: opts?.session,
+      timeoutMS,
+    });
     if (!isOrdinarySessionInTransaction(opts?.session)) {
       documentArg.creationStatus = 'db';
     }
@@ -3998,7 +4064,12 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
   public static async insertMany<T extends SmartDataDbDoc<any, any>>(
     this: plugins.tsclass.typeFest.Class<T>,
     documentsArg: T[],
-    opts?: { session?: TSmartdataOrdinarySession; ordered?: boolean },
+    opts?: {
+      session?: TSmartdataOrdinarySession;
+      ordered?: boolean;
+      /** Client-side deadline for the call's database work (1..120000 ms), including model initialization, server selection and pool waits. */
+      timeoutMS?: number;
+    },
   ): Promise<plugins.mongodb.InsertManyResult<{ _id: TSmartdataPrimaryId<T> }>> {
     if ((this as any)[exactPersistencePolicySymbol]) {
       throw new SmartdataPersistenceError(
@@ -4021,6 +4092,7 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
         'Model insertMany ordered must be a boolean.',
       );
     }
+    const timeoutMS = requireBoundedInteger(opts?.timeoutMS, 'Model insertMany timeoutMS', 120_000);
     const seenDocuments = new Set<T>();
     for (const documentArg of documentsArg) {
       if (!(documentArg instanceof this)) {
@@ -4073,7 +4145,11 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
       }
     };
     try {
-      const result = await collection.insertMany(documentsArg as any, opts);
+      const result = await collection.insertMany(documentsArg as any, {
+        session: opts?.session,
+        ordered: opts?.ordered,
+        timeoutMS,
+      });
       markInsertedDocuments(
         result.insertedIds as unknown as Record<number, unknown>,
       );
@@ -4193,6 +4269,11 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
     const normalizedOptions = '$expr' in normalizedFilter
       ? normalizeAtomicExpressionUpdateOptions(opts)
       : opts;
+    const timeoutMS = requireBoundedInteger(
+      normalizedOptions?.timeoutMS,
+      'Atomic update timeoutMS',
+      120_000,
+    );
     if (normalizedOptions?.upsert === true && '$expr' in normalizedFilter) {
       throw new SmartdataPersistenceError(
         'invalid_argument',
@@ -4242,7 +4323,11 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
       collection,
       mapIdentityFilterToDocumentId(normalizedFilter, identityDocumentIdField),
       normalizedUpdate,
-      normalizedOptions,
+      {
+        upsert: normalizedOptions?.upsert,
+        session: normalizedOptions?.session,
+        timeoutMS,
+      },
     );
     return {
       acknowledged: result.acknowledged,
@@ -4346,6 +4431,7 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
         upsert: normalizedOptions.upsert,
         ...(normalizedSort ? { sort: normalizedSort as Record<string, 1 | -1> } : {}),
         ...(normalizedOptions.session ? { session: normalizedOptions.session } : {}),
+        timeoutMS: normalizedOptions.timeoutMS,
       },
     );
     if (result.document === null) {
@@ -4473,6 +4559,7 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
       {
         returnDocument: normalizedOptions.returnDocument,
         ...(normalizedOptions.session ? { session: normalizedOptions.session } : {}),
+        timeoutMS: normalizedOptions.timeoutMS,
       },
     );
     if (result.status === 'not_matched') {
@@ -4550,7 +4637,7 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
   public static async atomicDeleteMany<T>(
     this: plugins.tsclass.typeFest.Class<T>,
     filterArg: TSmartdataAtomicFilter<T>,
-    opts?: ISmartdataAtomicDeleteOptions,
+    opts?: ISmartdataAtomicDeleteManyOptions,
   ): Promise<ISmartdataAtomicDeleteResult> {
     if ((this as any)[exactPersistencePolicySymbol]) {
       throw new SmartdataPersistenceError(
@@ -4582,7 +4669,11 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
         normalizedFilter,
         (this as any).getIdentityDocumentIdField() as string | undefined,
       ),
-      { session: opts?.session, timeoutMS: requireBoundedInteger(opts?.timeoutMS, 'Atomic delete-many timeoutMS', 120_000) },
+      {
+        session: opts?.session,
+        timeoutMS: requireBoundedInteger(opts?.timeoutMS, 'Atomic delete-many timeoutMS', 120_000),
+        signal: requireOperationSignal(opts?.signal, 'Atomic delete-many signal'),
+      },
     );
     return {
       acknowledged: result.acknowledged,
@@ -4622,6 +4713,7 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
         'Atomic update-many does not support $setOnInsert.',
       );
     }
+    const timeoutMS = requireBoundedInteger(opts?.timeoutMS, 'Atomic update-many timeoutMS', 120_000);
     const declaredRoots = (this as any).getDeclaredPersistedRoots() as Set<string>;
     const declaredAtomicPaths = (this as any).getDeclaredAtomicPaths() as Set<string>;
     const uniqueRoots = (this as any).getDeclaredUniqueRoots() as Set<string>;
@@ -4660,7 +4752,7 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
         (this as any).getIdentityDocumentIdField() as string | undefined,
       ),
       normalizedUpdate,
-      opts,
+      { session: opts?.session, timeoutMS },
     );
     return {
       acknowledged: result.acknowledged,
@@ -5096,12 +5188,23 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
   public static async getInstances<T>(
     this: plugins.tsclass.typeFest.Class<T>,
     filterArg: MongoFilter<T>,
-    opts?: { session?: TSmartdataOrdinarySession }
+    opts?: {
+      session?: TSmartdataOrdinarySession;
+      /**
+       * Client-side deadline for the read (1..120000 ms), from model
+       * initialization to the cursor's last reply. A timed-out `getMore` is
+       * followed by the driver's `killCursors` on a fresh deadline of the same
+       * length, so a read that needs more than one batch settles within about
+       * twice `timeoutMS` against a stalled database.
+       */
+      timeoutMS?: number;
+    }
   ): Promise<T[]> {
+    const timeoutMS = requireBoundedInteger(opts?.timeoutMS, 'timeoutMS', 120_000);
     // Pass session through to findAll for transactional queries
     const foundDocs = await (this as any).collection.findAll(
       (this as any).normalizeReadFilter(filterArg),
-      { session: opts?.session },
+      { session: opts?.session, timeoutMS },
     );
     const returnArray: T[] = [];
     for (const foundDoc of foundDocs) {
@@ -5135,6 +5238,14 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
       /** Also count all filter matches (extra query). */
       withTotal?: boolean;
       session?: TSmartdataOrdinarySession;
+      /**
+       * Client-side deadline for the page and its optional count together
+       * (1..120000 ms). A page that needs more than one batch can settle
+       * within about twice `timeoutMS` against a stalled database: the
+       * driver's `killCursors` after a timed-out `getMore` gets a fresh
+       * deadline of the same length.
+       */
+      timeoutMS?: number;
     },
   ): Promise<{
     documents: T[];
@@ -5149,6 +5260,7 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
       ? optionsArg.limit!
       : 100;
     const limit = Math.min(requestedLimit, 1000);
+    const timeoutMS = requireBoundedInteger(optionsArg.timeoutMS, 'timeoutMS', 120_000);
     const baseSelector = (this as any).normalizeReadFilter(optionsArg.filter || {});
 
     let selector: any = baseSelector;
@@ -5172,10 +5284,11 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
       ordinaryWrite: false,
       prepared: collection.isInitializedForCurrentDatabase(),
       collectionName: collection.collectionName,
-    }, async (rawSessionArg) => {
-      await collection.init();
+      timeoutMS,
+    }, async (rawSessionArg, deadlineArg) => {
+      await deadlineArg.join(collection.init());
       const rawCursor = collection.mongoDbCollection
-        .find(selector, { session: rawSessionArg })
+        .find(selector, { session: rawSessionArg, ...deadlineArg.cursorOptions() })
         .sort({ [optionsArg.sortField]: sortDirection, [uniqueField]: sortDirection })
         .limit(limit + 1);
       return runCursorOperation(rawCursor, async (cursorArg) => {
@@ -5189,6 +5302,7 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
         const total = optionsArg.withTotal
           ? await collection.mongoDbCollection.countDocuments(baseSelector, {
               session: rawSessionArg,
+              ...deadlineArg.commandOptions(),
             })
           : undefined;
         return {
@@ -5203,7 +5317,7 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
             : {}),
           ...(total !== undefined ? { total } : {}),
         };
-      });
+      }, deadlineArg.signal);
     });
   }
 
@@ -5234,6 +5348,7 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
           'maxTimeMS',
           120_000,
         ),
+        timeoutMS: requireBoundedInteger(opts?.timeoutMS, 'timeoutMS', 120_000),
         session: opts?.session,
       },
     );
@@ -5250,6 +5365,8 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
     filterArg: MongoFilter<T>,
     opts?: {
       maxTimeMS?: number;
+      /** Client-side deadline for the call's database work (1..120000 ms), including model initialization, server selection and pool waits. */
+      timeoutMS?: number;
       session?: TSmartdataOrdinarySession;
     },
   ): Promise<boolean> {
@@ -5262,6 +5379,7 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
           'maxTimeMS',
           120_000,
         ),
+        timeoutMS: requireBoundedInteger(opts?.timeoutMS, 'timeoutMS', 120_000),
         session: opts?.session,
       },
     );
@@ -5406,10 +5524,9 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
         'Offset pages require sort, limit and an integer skip from 0 through 2147483647.',
       );
     }
-    const timeoutMS = requireBoundedInteger(opts?.timeoutMS === undefined ? 5_000 : opts.timeoutMS, 'timeoutMS', 120_000);
+    const timeoutMS = requireBoundedInteger(opts?.timeoutMS, 'timeoutMS', 120_000);
     const maxTimeMS = requireBoundedInteger(opts?.maxTimeMS, 'maxTimeMS', 120_000);
     const filter = (this as any).normalizeReadFilter(filterArg);
-    opts.signal?.throwIfAborted();
     const collection: SmartdataCollection<T> = (this as any).collection;
     if (!collection.isInitializedForCurrentDatabase()) {
       throw new SmartdataPersistenceError(
@@ -5420,18 +5537,20 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
     return runWithOrdinarySmartdataSession(opts.session, collection.smartdataDb, {
       ordinaryWrite: false,
       prepared: true,
-    }, async (rawSessionArg) => {
-      opts.signal?.throwIfAborted();
+      timeoutMS,
+      defaultTimeoutMS: 5_000,
+      signal: opts.signal,
+    }, async (rawSessionArg, deadlineArg) => {
       const rawCursor = collection.mongoDbCollection.find(filter, {
-        projection, sort, hint, skip, limit, maxTimeMS, timeoutMS,
-        timeoutMode: 'cursorLifetime', session: rawSessionArg, signal: opts.signal,
+        projection, sort, hint, skip, limit, maxTimeMS,
+        ...deadlineArg.cursorOptions(), session: rawSessionArg,
       });
       return runCursorOperation(rawCursor, async (cursorArg) => {
         const documents = await cursorArg.toArray();
         return documents.map((documentArg) =>
           (this as any).createInstanceFromMongoDbNativeDoc(documentArg) as T,
         );
-      }, opts.signal);
+      }, deadlineArg.signal);
     });
   }
 
@@ -5778,7 +5897,11 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
    * handle from `db.createSession()` — leased for the one write, like every
    * other model API — or a raw driver session.
    */
-  public async save(opts?: { session?: TSmartdataOrdinarySession }) {
+  public async save(opts?: {
+    session?: TSmartdataOrdinarySession;
+    /** Client-side deadline for the write (1..120000 ms); `beforeSave()` and `afterSave()` run outside it. */
+    timeoutMS?: number;
+  }) {
     if (getOrdinaryPersistencePolicy(this.constructor)) {
       throw new SmartdataPersistenceError('unsupported_operation',
         'Validated ordinary models use insert() or transactional postimage updates.');
@@ -5792,6 +5915,7 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
       }
       throw new Error('save() is unavailable for exact-persistence models.');
     }
+    const timeoutMS = requireBoundedInteger(opts?.timeoutMS, 'Model save timeoutMS', 120_000);
     // allow hook before saving
     if (typeof (this as any).beforeSave === 'function') {
       await (this as any).beforeSave();
@@ -5809,10 +5933,10 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
     // perform insert or update
     switch (this.creationStatus) {
       case 'db':
-        dbResult = await this.getCollectionSafe().update(self, { session: opts?.session });
+        dbResult = await this.getCollectionSafe().update(self, { session: opts?.session, timeoutMS });
         break;
       case 'new':
-        dbResult = await this.getCollectionSafe().insert(self, { session: opts?.session });
+        dbResult = await this.getCollectionSafe().insert(self, { session: opts?.session, timeoutMS });
         this.creationStatus = 'db';
         break;
       default:
@@ -5959,7 +6083,7 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
         $set: setObject,
         ...(Object.keys(unsetObject).length > 0 ? { $unset: unsetObject } : {}),
       },
-      { session: options.session },
+      { session: options.session, timeoutMS: options.timeoutMS },
     );
     if (result.matchedCount === 0) {
       // Nothing was written, so the instance keeps the update timestamp the
@@ -5986,7 +6110,11 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
    * `session` takes the handle from `db.createSession()` — leased for the one
    * write, like every other model API — or a raw driver session.
    */
-  public async delete(opts?: { session?: TSmartdataOrdinarySession }) {
+  public async delete(opts?: {
+    session?: TSmartdataOrdinarySession;
+    /** Client-side deadline for the write (1..120000 ms); `beforeDelete()` and `afterDelete()` run outside it. */
+    timeoutMS?: number;
+  }) {
     const exactPersistencePolicy = (this.constructor as any)[
       exactPersistencePolicySymbol
     ] as { forbiddenDelete?: () => Promise<never> } | undefined;
@@ -5996,12 +6124,13 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
       }
       throw new Error('delete() is forbidden for exact-persistence models.');
     }
+    const timeoutMS = requireBoundedInteger(opts?.timeoutMS, 'Model delete timeoutMS', 120_000);
     // allow hook before deleting
     if (typeof (this as any).beforeDelete === 'function') {
       await (this as any).beforeDelete();
     }
     // perform deletion
-    const result = await this.getCollectionSafe().delete(this, { session: opts?.session });
+    const result = await this.getCollectionSafe().delete(this, { session: opts?.session, timeoutMS });
     // allow hook after delete
     if (typeof (this as any).afterDelete === 'function') {
       await (this as any).afterDelete();