@lossless.org/client 1.6.0 → 1.8.0

package/ts/nosqldb/classes.exactpersistence.ts

@@ -7,7 +7,17 @@ import type { SmartdataCollection } from './classes.collection.js';
 import { getIdentityIndexName } from './classes.collectiontopology.js';
 import { registerCollectionReconnectHandler } from './classes.collectionlifecycle.js';
 import type { SmartdataSession } from './classes.session.js';
-import { acquireSmartdataSession } from './classes.session.js';
+import {
+  acquireSmartdataSession,
+  settleSmartdataOperationError,
+  resolveSmartdataOperationDeadline,
+} from './classes.session.js';
+import {
+  type SmartdataOperationDeadline,
+  requireOperationSignal,
+  requireOperationTimeoutMS,
+} from './classes.operationdeadline.js';
+import { normalizeDeadlineError } from './classes.persistence.js';
 import {
   convertFilterForMongoDb,
   type MongoFilter,
@@ -217,7 +227,22 @@ export interface IExactReadOptions extends IExactSessionOptions {
   signal?: AbortSignal;
 }
 
-export interface IFindStoredOptions<TPersisted extends object> extends IExactReadOptions {
+/**
+ * Options of every exact call: `insert()`, `transition()`, `delete()`,
+ * `count()`, `distinct()` and `findStoredOne()`, and through
+ * `IFindStoredOptions` `findStored()`.
+ */
+export interface IExactBoundedOptions extends IExactReadOptions {
+  /**
+   * Client deadline (1..120000 ms), handed to the driver as its client-side
+   * operation timeout for every command of the call, including the wait for
+   * the lazy first-touch preparation. Inside a transaction with a deadline it
+   * is refused; the transaction's deadline bounds the call.
+   */
+  timeoutMS?: number;
+}
+
+export interface IFindStoredOptions<TPersisted extends object> extends IExactBoundedOptions {
   filter?: MongoFilter<TStoredDocument<TPersisted>>;
   sort?: Partial<
     Record<TExactDocumentPath<TStoredDocument<TPersisted>>, 1 | -1>
@@ -253,36 +278,6 @@ const bytesEqual = (leftArg: Uint8Array, rightArg: Uint8Array): boolean => {
   return true;
 };
 
-const waitWithSignal = async <T>(
-  promiseArg: Promise<T>,
-  signalArg?: AbortSignal,
-): Promise<T> => {
-  if (!signalArg) return promiseArg;
-  signalArg.throwIfAborted();
-  return new Promise<T>((resolve, reject) => {
-    let settled = false;
-    const beginSettlement = (): boolean => {
-      if (settled) return false;
-      settled = true;
-      signalArg.removeEventListener('abort', onAbort);
-      return true;
-    };
-    const onAbort = () => {
-      if (beginSettlement()) reject(signalArg.reason);
-    };
-    signalArg.addEventListener('abort', onAbort, { once: true });
-    if (signalArg.aborted) onAbort();
-    void promiseArg.then(
-      (valueArg) => {
-        if (beginSettlement()) resolve(valueArg);
-      },
-      (errorArg) => {
-        if (beginSettlement()) reject(errorArg);
-      },
-    );
-  });
-};
-
 const hasOwn = (documentArg: object, keyArg: PropertyKey): boolean =>
   Object.prototype.hasOwnProperty.call(documentArg, keyArg);
 
@@ -1073,17 +1068,17 @@ export class SmartdataExactCollection<
   }
 
   private async beginOperation(
-    optionsArg: IExactSessionOptions,
-    signalArg?: AbortSignal,
+    sessionArg: SmartdataSession | undefined,
+    boundsArg: { timeoutMS?: number; signal?: AbortSignal },
   ): Promise<{
     session?: plugins.mongodb.ClientSession;
+    deadline: SmartdataOperationDeadline;
     release: () => void;
   }> {
-    signalArg?.throwIfAborted();
-    if (!optionsArg.session) {
-      await waitWithSignal(this.initialize(), signalArg);
-      signalArg?.throwIfAborted();
-      return { release: () => {} };
+    if (!sessionArg) {
+      const deadline = resolveSmartdataOperationDeadline(undefined, boundsArg);
+      await deadline.join(this.initialize());
+      return { deadline, release: () => {} };
     }
     if (
       !this.collection.isInitializedForCurrentDatabase()
@@ -1095,35 +1090,66 @@ export class SmartdataExactCollection<
       );
     }
     const lease = acquireSmartdataSession(
-      optionsArg.session,
+      sessionArg,
       this.collection.smartdataDb,
     );
-    if (signalArg?.aborted) {
+    try {
+      const deadline = resolveSmartdataOperationDeadline(sessionArg, boundsArg);
+      deadline.throwIfAborted();
+      return {
+        session: lease.rawSession,
+        deadline,
+        release: lease.release,
+      };
+    } catch (errorArg) {
       lease.release();
-      signalArg.throwIfAborted();
+      throw errorArg;
     }
-    return {
-      session: lease.rawSession,
-      release: lease.release,
-    };
   }
 
+  /**
+   * Runs one exact call on its session lease under its client deadline and
+   * signal. A signal that is already aborted rejects with its reason before
+   * anything is sent. An expired driver deadline surfaces as the `timeout`
+   * persistence error; a write the deadline or signal interrupts in flight
+   * is reported by the write itself as `ambiguous_write`, and inside a
+   * transaction any interruption fails the attempt.
+   */
   private async runOperation<TResult>(
-    optionsArg: IExactSessionOptions,
+    optionsArg: IExactBoundedOptions,
     operationArg: (
-      sessionArg?: plugins.mongodb.ClientSession,
+      sessionArg: plugins.mongodb.ClientSession | undefined,
+      deadlineArg: SmartdataOperationDeadline,
     ) => Promise<TResult>,
-    signalArg?: AbortSignal,
   ): Promise<TResult> {
-    const operation = await this.beginOperation(optionsArg, signalArg);
+    const bounds = {
+      timeoutMS: requireOperationTimeoutMS(optionsArg.timeoutMS, 'Exact operation timeoutMS'),
+      signal: requireOperationSignal(optionsArg.signal, 'Exact operation signal'),
+    };
+    bounds.signal?.throwIfAborted();
+    const operation = await this.beginOperation(optionsArg.session, bounds);
     try {
-      signalArg?.throwIfAborted();
-      return await operationArg(operation.session);
+      return await operationArg(operation.session, operation.deadline);
+    } catch (errorArg) {
+      throw settleSmartdataOperationError(optionsArg.session, operation.deadline, errorArg);
     } finally {
       operation.release();
     }
   }
 
+  /**
+   * The error of a non-transactional write that its client deadline or
+   * signal interrupted after the write was handed to the driver: the command
+   * may have reached the database, so its outcome is unknown and no
+   * reconciliation read runs on the interrupted call's budget.
+   */
+  private interruptedWriteError(labelArg: string, causeArg: unknown): Error {
+    return this.ambiguousWriteError(
+      `${labelArg} was interrupted by its client deadline or signal in flight; its outcome is unknown.`,
+      normalizeDeadlineError(causeArg),
+    );
+  }
+
   private canonicalizeDocument<TDocument extends object>(
     documentArg: TDocument,
     labelArg: string,
@@ -1355,11 +1381,12 @@ export class SmartdataExactCollection<
 
   private async findByReconcileIdentity(
     identityArg: string,
-    sessionArg?: plugins.mongodb.ClientSession,
+    sessionArg: plugins.mongodb.ClientSession | undefined,
+    deadlineArg: SmartdataOperationDeadline,
   ): Promise<TStoredDocument<TPersisted> | null> {
     const rawDocument = await this.collection.mongoDbCollection.findOne({
       [this.reconcileBy]: identityArg,
-    }, { session: sessionArg });
+    }, { session: sessionArg, ...deadlineArg.commandOptions() });
     return rawDocument
       ? this.canonicalizeStoredDocument(rawDocument)
       : null;
@@ -1424,11 +1451,12 @@ export class SmartdataExactCollection<
     currentArg: TStoredDocument<TPersisted>,
     identityArg: string,
     causeArg: unknown,
-    sessionArg?: plugins.mongodb.ClientSession,
+    sessionArg: plugins.mongodb.ClientSession | undefined,
+    deadlineArg: SmartdataOperationDeadline,
   ): Promise<TExactDeleteResult> {
     let reconciled: TStoredDocument<TPersisted> | null;
     try {
-      reconciled = await this.findByReconcileIdentity(identityArg, sessionArg);
+      reconciled = await this.findByReconcileIdentity(identityArg, sessionArg, deadlineArg);
     } catch (errorArg) {
       if (isTransientTransactionError(errorArg, sessionArg)) {
         throw errorArg;
@@ -1449,9 +1477,9 @@ export class SmartdataExactCollection<
 
   public async insert(
     documentArg: TModel | TExactPersistedDocument<TPersisted>,
-    optionsArg: IExactSessionOptions = {},
+    optionsArg: IExactBoundedOptions = {},
   ): Promise<TExactInsertResult<TPersisted>> {
-    return this.runOperation(optionsArg, async (sessionArg) => {
+    return this.runOperation(optionsArg, async (sessionArg, deadlineArg) => {
     const persistedDocument = await this.createPersistedDocument(documentArg);
     const identity = this.validateReconcileIdentity(persistedDocument);
     const expectedStoredDocument = this.canonicalizeStoredDocument({
@@ -1459,7 +1487,7 @@ export class SmartdataExactCollection<
       ...persistedDocument,
     });
     if (hasActiveTransaction(sessionArg)) {
-      const existing = await this.findByReconcileIdentity(identity, sessionArg);
+      const existing = await this.findByReconcileIdentity(identity, sessionArg, deadlineArg);
       if (existing) {
         return this.persistedDocumentsEqual(
           this.getPersistedBody(existing),
@@ -1471,10 +1499,11 @@ export class SmartdataExactCollection<
     }
 
     let result: plugins.mongodb.InsertOneResult;
+    const insertOptions = { session: sessionArg, ...deadlineArg.commandOptions() };
     try {
       result = await this.collection.mongoDbCollection.insertOne(
         expectedStoredDocument,
-        { session: sessionArg },
+        insertOptions,
       );
     } catch (errorArg) {
       if (isTransientTransactionError(errorArg, sessionArg)) {
@@ -1490,9 +1519,12 @@ export class SmartdataExactCollection<
         }
         throw errorArg;
       }
+      if (deadlineArg.interrupted(errorArg)) {
+        throw this.interruptedWriteError('Exact insert', errorArg);
+      }
       let reconciled: TStoredDocument<TPersisted> | null;
       try {
-        reconciled = await this.findByReconcileIdentity(identity, sessionArg);
+        reconciled = await this.findByReconcileIdentity(identity, sessionArg, deadlineArg);
       } catch (reconciliationError) {
         if (isTransientTransactionError(reconciliationError, sessionArg)) {
           throw reconciliationError;
@@ -1544,7 +1576,7 @@ export class SmartdataExactCollection<
       }
       let reconciled: TStoredDocument<TPersisted> | null;
       try {
-        reconciled = await this.findByReconcileIdentity(identity, sessionArg);
+        reconciled = await this.findByReconcileIdentity(identity, sessionArg, deadlineArg);
       } catch (errorArg) {
         if (isTransientTransactionError(errorArg, sessionArg)) {
           throw errorArg;
@@ -1592,15 +1624,15 @@ export class SmartdataExactCollection<
 
   public async findStoredOne(
     filterArg: MongoFilter<TStoredDocument<TPersisted>>,
-    optionsArg: IExactReadOptions = {},
+    optionsArg: IExactBoundedOptions = {},
   ): Promise<TStoredDocument<TPersisted> | null> {
-    return this.runOperation(optionsArg, async (sessionArg) => {
+    return this.runOperation(optionsArg, async (sessionArg, deadlineArg) => {
     const cursor = this.collection.mongoDbCollection.find(
       convertFilterForMongoDb(filterArg),
       {
         session: sessionArg,
-        signal: optionsArg.signal,
         singleBatch: true,
+        ...deadlineArg.cursorOptions(),
       },
     ).limit(1);
     const nativeCursorClose = cursor.close.bind(cursor);
@@ -1625,17 +1657,16 @@ export class SmartdataExactCollection<
     }
     await cursor.close();
     return storedDocument;
-    }, optionsArg.signal);
+    });
   }
 
   public async findStored(
     optionsArg: IFindStoredOptions<TPersisted> = {},
   ): Promise<Array<TStoredDocument<TPersisted>>> {
-    optionsArg.signal?.throwIfAborted();
-    return this.runOperation(optionsArg, async (sessionArg) => {
+    return this.runOperation(optionsArg, async (sessionArg, deadlineArg) => {
     let cursor = this.collection.mongoDbCollection.find(
       convertFilterForMongoDb(optionsArg.filter || {}),
-      { session: sessionArg, signal: optionsArg.signal },
+      { session: sessionArg, ...deadlineArg.cursorOptions() },
     );
     // The driver abort listener does not await close, so every close must join
     // the same native cleanup before runOperation releases its session lease.
@@ -1670,17 +1701,17 @@ export class SmartdataExactCollection<
     }
     await cursor.close();
     return storedDocuments;
-    }, optionsArg.signal);
+    });
   }
 
   public async count(
     filterArg: MongoFilter<TStoredDocument<TPersisted>> = {},
-    optionsArg: IExactSessionOptions = {},
+    optionsArg: IExactBoundedOptions = {},
   ): Promise<number> {
-    return this.runOperation(optionsArg, async (sessionArg) =>
+    return this.runOperation(optionsArg, async (sessionArg, deadlineArg) =>
       this.collection.mongoDbCollection.countDocuments(
         convertFilterForMongoDb(filterArg),
-        { session: sessionArg },
+        { session: sessionArg, ...deadlineArg.commandOptions() },
       )
     );
   }
@@ -1690,15 +1721,15 @@ export class SmartdataExactCollection<
   >(
     fieldArg: TField,
     filterArg: MongoFilter<TStoredDocument<TPersisted>> = {},
-    optionsArg: IExactSessionOptions = {},
+    optionsArg: IExactBoundedOptions = {},
   ): Promise<Array<TExactDistinctValue<
     TExactDocumentPathValue<TStoredDocument<TPersisted>, TField>
   >>> {
-    return this.runOperation(optionsArg, async (sessionArg) =>
+    return this.runOperation(optionsArg, async (sessionArg, deadlineArg) =>
       (await this.collection.mongoDbCollection.distinct(
         fieldArg as string,
         convertFilterForMongoDb(filterArg),
-        { session: sessionArg },
+        { session: sessionArg, ...deadlineArg.commandOptions() },
       )) as Array<TExactDistinctValue<
         TExactDocumentPathValue<TStoredDocument<TPersisted>, TField>
       >>
@@ -1710,9 +1741,9 @@ export class SmartdataExactCollection<
       current: TStoredDocument<TPersisted>;
       change: (modelArg: TModel) => void;
     },
-    sessionOptionsArg: IExactSessionOptions = {},
+    sessionOptionsArg: IExactBoundedOptions = {},
   ): Promise<TExactTransitionResult<TPersisted>> {
-    return this.runOperation(sessionOptionsArg, async (sessionArg) => {
+    return this.runOperation(sessionOptionsArg, async (sessionArg, deadlineArg) => {
     const current = this.canonicalizeStoredDocument(optionsArg.current);
     const currentBody = this.getPersistedBody(current);
     const currentIdentity = this.validateReconcileIdentity(currentBody);
@@ -1756,16 +1787,18 @@ export class SmartdataExactCollection<
       ? { _id: current._id, _smartdataRevision: current._smartdataRevision }
       : { _id: current._id, _smartdataRevision: { $exists: false } };
 
+    const replaceOptions = {
+      returnDocument: 'after' as const,
+      includeResultMetadata: false as const,
+      upsert: false,
+      session: sessionArg,
+      ...deadlineArg.commandOptions(),
+    };
     try {
       const postimage = await this.collection.mongoDbCollection.findOneAndReplace(
         selector,
         expectedStoredDocument,
-        {
-          returnDocument: 'after',
-          includeResultMetadata: false,
-          upsert: false,
-          session: sessionArg,
-        },
+        replaceOptions,
       );
       if (!postimage) {
         return { status: 'concurrent_change' };
@@ -1792,10 +1825,13 @@ export class SmartdataExactCollection<
       if (hasActiveTransaction(sessionArg)) {
         throw errorArg;
       }
+      if (deadlineArg.interrupted(errorArg)) {
+        throw this.interruptedWriteError('Exact transition', errorArg);
+      }
       try {
         const reconciledRaw = await this.collection.mongoDbCollection.findOne({
           _id: current._id,
-        }, { session: sessionArg });
+        }, { session: sessionArg, ...deadlineArg.commandOptions() });
         if (reconciledRaw) {
           const reconciled = this.canonicalizeStoredDocument(reconciledRaw);
           if (
@@ -1826,10 +1862,10 @@ export class SmartdataExactCollection<
     optionsArg: {
       current: TStoredDocument<TPersisted>;
     },
-    sessionOptionsArg: IExactSessionOptions = {},
+    sessionOptionsArg: IExactBoundedOptions = {},
   ): Promise<TExactDeleteResult> {
     const { current, identity } = this.canonicalizeDeleteCurrent(optionsArg);
-    return this.runOperation(sessionOptionsArg, async (sessionArg) => {
+    return this.runOperation(sessionOptionsArg, async (sessionArg, deadlineArg) => {
     const selector = current._smartdataRevision !== undefined
       ? {
           _id: current._id,
@@ -1842,10 +1878,9 @@ export class SmartdataExactCollection<
           _smartdataRevision: { $exists: false },
         };
     let result: plugins.mongodb.DeleteResult;
+    const deleteOptions = { session: sessionArg, ...deadlineArg.commandOptions() };
     try {
-      result = await this.collection.mongoDbCollection.deleteOne(selector, {
-        session: sessionArg,
-      });
+      result = await this.collection.mongoDbCollection.deleteOne(selector, deleteOptions);
     } catch (errorArg) {
       if (isTransientTransactionError(errorArg, sessionArg)) {
         throw errorArg;
@@ -1853,7 +1888,10 @@ export class SmartdataExactCollection<
       if (hasActiveTransaction(sessionArg)) {
         throw errorArg;
       }
-      return this.reconcileDeleteOutcome(current, identity, errorArg, sessionArg);
+      if (deadlineArg.interrupted(errorArg)) {
+        throw this.interruptedWriteError('Exact delete', errorArg);
+      }
+      return this.reconcileDeleteOutcome(current, identity, errorArg, sessionArg, deadlineArg);
     }
     if (
       result.acknowledged === true &&
@@ -1874,11 +1912,11 @@ export class SmartdataExactCollection<
           result,
         );
       }
-      return this.reconcileDeleteOutcome(current, identity, result, sessionArg);
+      return this.reconcileDeleteOutcome(current, identity, result, sessionArg, deadlineArg);
     }
 
     try {
-      await this.findByReconcileIdentity(identity, sessionArg);
+      await this.findByReconcileIdentity(identity, sessionArg, deadlineArg);
     } catch (errorArg) {
       if (isTransientTransactionError(errorArg, sessionArg)) {
         throw errorArg;

package/ts/nosqldb/classes.operationdeadline.ts

@@ -0,0 +1,179 @@
+import * as plugins from './plugins.js';
+import {
+  SmartdataPersistenceError,
+  createSmartdataTimeoutError,
+  isMongoDeadlineError,
+} from './classes.persistence.js';
+
+const deadlineExceededMessage = 'SmartData operation exceeded its client deadline.';
+
+/** Validates a caller's client deadline: a positive safe integer of at most 120000 ms. */
+export const requireOperationTimeoutMS = (
+  valueArg: unknown,
+  labelArg: string,
+): number | undefined => {
+  if (valueArg === undefined) {
+    return undefined;
+  }
+  if (
+    typeof valueArg !== 'number'
+    || !Number.isSafeInteger(valueArg)
+    || valueArg < 1
+    || valueArg > 120_000
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${labelArg} must be a positive safe integer no greater than 120000.`,
+    );
+  }
+  return valueArg;
+};
+
+/** Validates a caller's cancellation signal: a genuine `AbortSignal`. */
+export const requireOperationSignal = (
+  valueArg: unknown,
+  labelArg: string,
+): AbortSignal | undefined => {
+  if (valueArg === undefined) {
+    return undefined;
+  }
+  if (plugins.nodeUtil.types.isProxy(valueArg) || !(valueArg instanceof AbortSignal)) {
+    throw new SmartdataPersistenceError('invalid_argument', `${labelArg} must be an AbortSignal.`);
+  }
+  return valueArg;
+};
+
+/**
+ * @internal The client-side deadline and cancellation of one model API call.
+ *
+ * Every database command of the call receives the time that is left as the
+ * driver's `timeoutMS`, so server selection, connection checkout, the round
+ * trip and the server-side `maxTimeMS` the driver derives all run on one
+ * clock, and the driver closes a connection whose reply did not arrive in
+ * time. An unbounded deadline hands the driver nothing, which leaves an
+ * enclosing transaction deadline or the connection's own settings in charge.
+ *
+ * The call's `signal` — its own, an enclosing transaction's, or both — goes
+ * to the driver with every command, which stops waiting for server
+ * selection or a pooled connection and closes a connection whose command is
+ * in flight, rejecting with the signal's reason.
+ */
+export class SmartdataOperationDeadline {
+  public static readonly unbounded = new SmartdataOperationDeadline(undefined);
+
+  private readonly expiresAt: number | undefined;
+
+  constructor(
+    timeoutMSArg: number | undefined,
+    public readonly signal?: AbortSignal,
+  ) {
+    this.expiresAt = timeoutMSArg === undefined
+      ? undefined
+      : performance.now() + timeoutMSArg;
+  }
+
+  public get bounded(): boolean {
+    return this.expiresAt !== undefined;
+  }
+
+  /** Throws the signal's reason once the call was aborted. */
+  public throwIfAborted(): void {
+    this.signal?.throwIfAborted();
+  }
+
+  /**
+   * Driver options for one command. Throws the abort reason once the call was
+   * aborted and `timeout` once the deadline has passed, so a command these
+   * options were built for was never handed to the driver.
+   */
+  public commandOptions(): { timeoutMS?: number } & plugins.mongodb.Abortable {
+    this.throwIfAborted();
+    return {
+      ...(this.expiresAt === undefined ? {} : { timeoutMS: this.remainingMS() }),
+      ...(this.signal === undefined ? {} : { signal: this.signal }),
+    };
+  }
+
+  /**
+   * Driver options for a cursor the deadline bounds from its first command to
+   * its last reply. When a `getMore` times out, the driver's own cleanup runs
+   * the cursor's `killCursors` on a fresh deadline of the full `timeoutMS`
+   * before it rethrows, and no driver option shortens that, so a stalled
+   * database settles a multi-batch read within about twice the deadline.
+   */
+  public cursorOptions(): {
+    timeoutMS?: number;
+    timeoutMode?: 'cursorLifetime';
+  } & plugins.mongodb.Abortable {
+    this.throwIfAborted();
+    return {
+      ...(this.expiresAt === undefined
+        ? {}
+        : { timeoutMS: this.remainingMS(), timeoutMode: 'cursorLifetime' as const }),
+      ...(this.signal === undefined ? {} : { signal: this.signal }),
+    };
+  }
+
+  /**
+   * Whether `errorArg` is this call's interruption: its signal's abort reason
+   * or the driver's deadline expiry.
+   */
+  public interrupted(errorArg: unknown): boolean {
+    return (this.signal?.aborted === true && errorArg === this.signal.reason)
+      || isMongoDeadlineError(errorArg);
+  }
+
+  /**
+   * Waits within the deadline for work another owner drives, such as the
+   * collection initialization every model call shares. Expiry or an abort
+   * ends only this call's wait: the owner keeps the work, its outcome and its
+   * cleanup, and the next caller joins the same work again.
+   */
+  public async join(workArg: Promise<void>): Promise<void> {
+    this.throwIfAborted();
+    if (this.expiresAt === undefined && this.signal === undefined) {
+      await workArg;
+      return;
+    }
+    const remainingMS = this.expiresAt === undefined ? undefined : this.remainingMS();
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let onAbort: (() => void) | undefined;
+    let expired = false;
+    const interruption = new Promise<void>((resolveArg) => {
+      if (remainingMS !== undefined) {
+        timer = setTimeout(() => {
+          expired = true;
+          resolveArg();
+        }, remainingMS);
+      }
+      if (this.signal !== undefined) {
+        onAbort = () => resolveArg();
+        this.signal.addEventListener('abort', onAbort, { once: true });
+      }
+    });
+    // The owner observes the work's failure itself; this wait must not turn a
+    // failure it stopped waiting for into an unhandled rejection.
+    const settled = workArg.then(() => undefined, () => undefined);
+    try {
+      await Promise.race([settled, interruption]);
+    } finally {
+      clearTimeout(timer);
+      if (onAbort !== undefined) {
+        this.signal?.removeEventListener('abort', onAbort);
+      }
+    }
+    this.throwIfAborted();
+    if (expired) {
+      throw createSmartdataTimeoutError(deadlineExceededMessage);
+    }
+    await workArg;
+  }
+
+  private remainingMS(): number {
+    const remainingMS = this.expiresAt! - performance.now();
+    if (remainingMS <= 0) {
+      throw createSmartdataTimeoutError(deadlineExceededMessage);
+    }
+    return Math.ceil(remainingMS);
+  }
+}

package/ts/nosqldb/classes.persistence.ts

@@ -6,7 +6,8 @@ export type TSmartdataPersistenceErrorCode =
   | 'invalid_document'
   | 'unique_conflict'
   | 'ambiguous_write'
-  | 'unsupported_operation';
+  | 'unsupported_operation'
+  | 'timeout';
 
 /**
  * Stable errors for ordinary SmartData model configuration and persistence.
@@ -27,6 +28,40 @@ export class SmartdataPersistenceError extends Error {
   }
 }
 
+/**
+ * The client-side deadline of a model call or transaction expired. The
+ * driver's own `MongoOperationTimeoutError` stays available as `cause` when
+ * the driver enforced it. A write or commit that expired has an unknown
+ * outcome: it may have been applied before the reply was lost.
+ */
+export const createSmartdataTimeoutError = (
+  messageArg: string,
+  causeArg?: unknown,
+): SmartdataPersistenceError =>
+  new SmartdataPersistenceError(
+    'timeout',
+    messageArg,
+    causeArg === undefined ? undefined : { cause: causeArg },
+  );
+
+/**
+ * The driver enforced a client deadline. A bulk write reports a driver error
+ * wrapped in `MongoBulkWriteError`, whose `errorResponse` is the original
+ * error and whose result still states what earlier batches wrote.
+ */
+export const isMongoDeadlineError = (errorArg: unknown): boolean =>
+  errorArg instanceof plugins.mongodb.MongoOperationTimeoutError
+  || (
+    errorArg instanceof plugins.mongodb.MongoBulkWriteError
+    && errorArg.errorResponse instanceof plugins.mongodb.MongoOperationTimeoutError
+  );
+
+/** Maps an expired driver deadline to `timeout`; every other error passes through unchanged. */
+export const normalizeDeadlineError = (errorArg: unknown): unknown =>
+  isMongoDeadlineError(errorArg)
+    ? createSmartdataTimeoutError('SmartData operation exceeded its client deadline.', errorArg)
+    : errorArg;
+
 export const isMongoTransactionRetryError = (errorArg: unknown): boolean =>
   errorArg instanceof plugins.mongodb.MongoServerError &&
   (