@lossless.org/client 1.6.0 → 1.8.0

package/dist_ts/nosqldb/classes.operationdeadline.d.ts

@@ -0,0 +1,61 @@
+import * as plugins from './plugins.js';
+/** Validates a caller's client deadline: a positive safe integer of at most 120000 ms. */
+export declare const requireOperationTimeoutMS: (valueArg: unknown, labelArg: string) => number | undefined;
+/** Validates a caller's cancellation signal: a genuine `AbortSignal`. */
+export declare const requireOperationSignal: (valueArg: unknown, labelArg: string) => AbortSignal | undefined;
+/**
+ * @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 declare class SmartdataOperationDeadline {
+    readonly signal?: AbortSignal | undefined;
+    static readonly unbounded: SmartdataOperationDeadline;
+    private readonly expiresAt;
+    constructor(timeoutMSArg: number | undefined, signal?: AbortSignal | undefined);
+    get bounded(): boolean;
+    /** Throws the signal's reason once the call was aborted. */
+    throwIfAborted(): void;
+    /**
+     * 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.
+     */
+    commandOptions(): {
+        timeoutMS?: number;
+    } & plugins.mongodb.Abortable;
+    /**
+     * 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.
+     */
+    cursorOptions(): {
+        timeoutMS?: number;
+        timeoutMode?: 'cursorLifetime';
+    } & plugins.mongodb.Abortable;
+    /**
+     * Whether `errorArg` is this call's interruption: its signal's abort reason
+     * or the driver's deadline expiry.
+     */
+    interrupted(errorArg: unknown): boolean;
+    /**
+     * 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.
+     */
+    join(workArg: Promise<void>): Promise<void>;
+    private remainingMS;
+}

package/dist_ts/nosqldb/classes.operationdeadline.js

@@ -0,0 +1,149 @@
+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, labelArg) => {
+    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, labelArg) => {
+    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 {
+    signal;
+    static unbounded = new SmartdataOperationDeadline(undefined);
+    expiresAt;
+    constructor(timeoutMSArg, signal) {
+        this.signal = signal;
+        this.expiresAt = timeoutMSArg === undefined
+            ? undefined
+            : performance.now() + timeoutMSArg;
+    }
+    get bounded() {
+        return this.expiresAt !== undefined;
+    }
+    /** Throws the signal's reason once the call was aborted. */
+    throwIfAborted() {
+        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.
+     */
+    commandOptions() {
+        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.
+     */
+    cursorOptions() {
+        this.throwIfAborted();
+        return {
+            ...(this.expiresAt === undefined
+                ? {}
+                : { timeoutMS: this.remainingMS(), timeoutMode: 'cursorLifetime' }),
+            ...(this.signal === undefined ? {} : { signal: this.signal }),
+        };
+    }
+    /**
+     * Whether `errorArg` is this call's interruption: its signal's abort reason
+     * or the driver's deadline expiry.
+     */
+    interrupted(errorArg) {
+        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.
+     */
+    async join(workArg) {
+        this.throwIfAborted();
+        if (this.expiresAt === undefined && this.signal === undefined) {
+            await workArg;
+            return;
+        }
+        const remainingMS = this.expiresAt === undefined ? undefined : this.remainingMS();
+        let timer;
+        let onAbort;
+        let expired = false;
+        const interruption = new Promise((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;
+    }
+    remainingMS() {
+        const remainingMS = this.expiresAt - performance.now();
+        if (remainingMS <= 0) {
+            throw createSmartdataTimeoutError(deadlineExceededMessage);
+        }
+        return Math.ceil(remainingMS);
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5vcGVyYXRpb25kZWFkbGluZS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL25vc3FsZGIvY2xhc3Nlcy5vcGVyYXRpb25kZWFkbGluZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGNBQWMsQ0FBQztBQUN4QyxPQUFPLEVBQ0wseUJBQXlCLEVBQ3pCLDJCQUEyQixFQUMzQixvQkFBb0IsR0FDckIsTUFBTSwwQkFBMEIsQ0FBQztBQUVsQyxNQUFNLHVCQUF1QixHQUFHLG1EQUFtRCxDQUFDO0FBRXBGLDBGQUEwRjtBQUMxRixNQUFNLENBQUMsTUFBTSx5QkFBeUIsR0FBRyxDQUN2QyxRQUFpQixFQUNqQixRQUFnQixFQUNJLEVBQUU7SUFDdEIsSUFBSSxRQUFRLEtBQUssU0FBUyxFQUFFLENBQUM7UUFDM0IsT0FBTyxTQUFTLENBQUM7SUFDbkIsQ0FBQztJQUNELElBQ0UsT0FBTyxRQUFRLEtBQUssUUFBUTtXQUN6QixDQUFDLE1BQU0sQ0FBQyxhQUFhLENBQUMsUUFBUSxDQUFDO1dBQy9CLFFBQVEsR0FBRyxDQUFDO1dBQ1osUUFBUSxHQUFHLE9BQU8sRUFDckIsQ0FBQztRQUNELE1BQU0sSUFBSSx5QkFBeUIsQ0FDakMsa0JBQWtCLEVBQ2xCLEdBQUcsUUFBUSwwREFBMEQsQ0FDdEUsQ0FBQztJQUNKLENBQUM7SUFDRCxPQUFPLFFBQVEsQ0FBQztBQUNsQixDQUFDLENBQUM7QUFFRix5RUFBeUU7QUFDekUsTUFBTSxDQUFDLE1BQU0sc0JBQXNCLEdBQUcsQ0FDcEMsUUFBaUIsRUFDakIsUUFBZ0IsRUFDUyxFQUFFO0lBQzNCLElBQUksUUFBUSxLQUFLLFNBQVMsRUFBRSxDQUFDO1FBQzNCLE9BQU8sU0FBUyxDQUFDO0lBQ25CLENBQUM7SUFDRCxJQUFJLE9BQU8sQ0FBQyxRQUFRLENBQUMsS0FBSyxDQUFDLE9BQU8sQ0FBQyxRQUFRLENBQUMsSUFBSSxDQUFDLENBQUMs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

package/dist_ts/nosqldb/classes.persistence.d.ts

@@ -1,5 +1,5 @@
 import * as plugins from './plugins.js';
-export type TSmartdataPersistenceErrorCode = 'invalid_argument' | 'invalid_configuration' | 'invalid_document' | 'unique_conflict' | 'ambiguous_write' | 'unsupported_operation';
+export type TSmartdataPersistenceErrorCode = 'invalid_argument' | 'invalid_configuration' | 'invalid_document' | 'unique_conflict' | 'ambiguous_write' | 'unsupported_operation' | 'timeout';
 /**
  * Stable errors for ordinary SmartData model configuration and persistence.
  *
@@ -9,6 +9,21 @@ export declare class SmartdataPersistenceError extends Error {
     readonly code: TSmartdataPersistenceErrorCode;
     constructor(codeArg: TSmartdataPersistenceErrorCode, messageArg: string, optionsArg?: ErrorOptions);
 }
+/**
+ * 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 declare const createSmartdataTimeoutError: (messageArg: string, causeArg?: unknown) => SmartdataPersistenceError;
+/**
+ * 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 declare const isMongoDeadlineError: (errorArg: unknown) => boolean;
+/** Maps an expired driver deadline to `timeout`; every other error passes through unchanged. */
+export declare const normalizeDeadlineError: (errorArg: unknown) => unknown;
 export declare const isMongoTransactionRetryError: (errorArg: unknown) => boolean;
 export declare const isMongoDuplicateKeyError: (errorArg: unknown) => errorArg is plugins.mongodb.MongoServerError;
 /**

package/dist_ts/nosqldb/classes.persistence.js

@@ -12,6 +12,25 @@ export class SmartdataPersistenceError extends Error {
         this.code = codeArg;
     }
 }
+/**
+ * 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, causeArg) => 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) => 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) => isMongoDeadlineError(errorArg)
+    ? createSmartdataTimeoutError('SmartData operation exceeded its client deadline.', errorArg)
+    : errorArg;
 export const isMongoTransactionRetryError = (errorArg) => errorArg instanceof plugins.mongodb.MongoServerError &&
     (errorArg.hasErrorLabel('TransientTransactionError') ||
         errorArg.hasErrorLabel('UnknownTransactionCommitResult'));
@@ -43,4 +62,4 @@ export const normalizeOrdinaryPersistenceError = (errorArg, messageArg) => {
     }
     throw errorArg;
 };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5wZXJzaXN0ZW5jZS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL25vc3FsZGIvY2xhc3Nlcy5wZXJzaXN0ZW5jZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGNBQWMsQ0FBQztBQVV4Qzs7OztHQUlHO0FBQ0gsTUFBTSxPQUFPLHlCQUEwQixTQUFRLEtBQUs7SUFDbEMsSUFBSSxDQUFpQztJQUVyRCxZQUNFLE9BQXVDLEVBQ3ZDLFVBQWtCLEVBQ2xCLFVBQXlCO1FBRXpCLEtBQUssQ0FBQyxVQUFVLEVBQUUsVUFBVSxDQUFDLENBQUM7UUFDOUIsSUFBSSxDQUFDLElBQUksR0FBRywyQkFBMkIsQ0FBQztRQUN4QyxJQUFJLENBQUMsSUFBSSxHQUFHLE9BQU8sQ0FBQztJQUN0QixDQUFDO0NBQ0Y7QUFFRCxNQUFNLENBQUMsTUFBTSw0QkFBNEIsR0FBRyxDQUFDLFFBQWlCLEVBQVcsRUFBRSxDQUN6RSxRQUFRLFlBQVksT0FBTyxDQUFDLE9BQU8sQ0FBQyxnQkFBZ0I7SUFDcEQsQ0FDRSxRQUFRLENBQUMsYUFBYSxDQUFDLDJCQUEyQixDQUFDO1FBQ25ELFFBQVEsQ0FBQyxhQUFhLENBQUMsZ0NBQWdDLENBQUMsQ0FDekQsQ0FBQztBQUVKLE1BQU0sQ0FBQyxNQUFNLHdCQUF3QixHQUFHLENBQ3RDLFFBQWlCLEVBQzZCLEVBQUU7SUFDaEQsT0FBTyxDQUNMLFFBQVEsWUFBWSxPQUFPLENBQUMsT0FBTyxDQUFDLGdCQUFnQjtRQUNwRCxDQUFDLFFBQVEsQ0FBQyxJQUFJLEtBQUssS0FBSyxJQUFJLFFBQVEsQ0FBQyxRQUFRLEtBQUssY0FBYyxDQUFDLENBQ2xFLENBQUM7QUFDSixDQUFDLENBQUM7QUFFRjs7OztHQUlHO0FBQ0gsTUFBTSxDQUFDLE1BQU0seUJBQXlCLEdBQUcsQ0FDdkMsUUFBaUIsRUFDNkIsRUFBRTtJQUNoRCxPQUFPLENBQ0wsUUFBUSxZQUFZLE9BQU8sQ0FBQyxPQUFPLENBQUMsZ0JBQWdCO1FBQ3BELENBQUMsUUFBUSxDQUFDLElBQUksS0FBSyxFQUFFO1lBQ25CLFFBQVEsQ0FBQyxJQUFJLEtBQUssRUFBRTtZQUNwQixRQUFRLENBQUMsUUFBUSxLQUFLLHNCQUFzQjtZQUM1QyxRQUFRLENBQUMsUUFBUSxLQUFLLHVCQUF1QixDQUFDLENBQ2pELENBQUM7QUFDSixDQUFDLENBQUM7QUFFRixNQUFNLENBQUMsTUFBTSxpQ0FBaUMsR0FBRyxDQUMvQyxRQUFpQixFQUNqQixVQUFrQixFQUNYLEVBQUU7SUFDVCxJQUNFLFFBQVEsWUFBWSx5QkFBeUI7UUFDN0MsNEJBQTRCLENBQUMsUUFBUSxDQUFDLEVBQ3RDLENBQUM7UUFDRCxNQUFNLFFBQVEsQ0FBQztJQUNqQixDQUFDO0lBQ0QsSUFBSSx3QkFBd0IsQ0FBQyxRQUFRLENBQUMsRUFBRSxDQUFDO1FBQ3ZDLE1BQU0sSUFBSSx5QkFBeUIsQ0FBQyxpQkFBaUIsRUFBRSxVQUFVLEVBQUU7WUFDakUsS0FBSyxFQUFFLFFBQVE7U0FDaEIsQ0FBQyxDQUFDO0lBQ0wsQ0FBQztJQUNELE1BQU0sUUFBUSxDQUFDO0FBQ2pCLENBQUMsQ0FBQyJ9
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5wZXJzaXN0ZW5jZS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL25vc3FsZGIvY2xhc3Nlcy5wZXJzaXN0ZW5jZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGNBQWMsQ0FBQztBQVd4Qzs7OztHQUlHO0FBQ0gsTUFBTSxPQUFPLHlCQUEwQixTQUFRLEtBQUs7SUFDbEMsSUFBSSxDQUFpQztJQUVyRCxZQUNFLE9BQXVDLEVBQ3ZDLFVBQWtCLEVBQ2xCLFVBQXlCO1FBRXpCLEtBQUssQ0FBQyxVQUFVLEVBQUUsVUFBVSxDQUFDLENBQUM7UUFDOUIsSUFBSSxDQUFDLElBQUksR0FBRywyQkFBMkIsQ0FBQztRQUN4QyxJQUFJLENBQUMsSUFBSSxHQUFHLE9BQU8sQ0FBQztJQUN0QixDQUFDO0NBQ0Y7QUFFRDs7Ozs7R0FLRztBQUNILE1BQU0sQ0FBQyxNQUFNLDJCQUEyQixHQUFHLENBQ3pDLFVBQWtCLEVBQ2xCLFFBQWtCLEVBQ1MsRUFBRSxDQUM3QixJQUFJLHlCQUF5QixDQUMzQixTQUFTLEVBQ1QsVUFBVSxFQUNWLFFBQVEsS0FBSyxTQUFTLENBQUMsQ0FBQyxDQUFDLFNBQVMsQ0FBQyxDQUFDLENBQUMsRUFBRSxLQUFLLEVBQUUsUUFBUSxFQUFFLENBQ3pELENBQUM7QUFFSjs7OztHQUlHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sb0JBQW9CLEdBQUcsQ0FBQyxRQUFpQixFQUFXLEVBQUUsQ0FDakUsUUFBUSxZQUFZLE9BQU8sQ0FBQyxPQUFPLENBQUMsMEJBQTBCO09BQzNELENBQ0QsUUFBUSxZQUFZLE9BQU8sQ0FBQyxPQUFPLENBQUMsbUJBQW1CO1dBQ3BELFFBQVEsQ0FBQyxhQUFhLFlBQVksT0FBTyxDQUFDLE9BQU8sQ0FBQywwQkFBMEIsQ0FDaEYsQ0FBQztBQUVKLGdHQUFnRztBQUNoRyxNQUFNLENBQUMsTUFBTSxzQkFBc0IsR0FBRyxDQUFDLFFBQWlCLEVBQVcsRUFBRSxDQUNuRSxvQkFBb0IsQ0FBQyxRQUFRLENBQUM7SUFDNUIsQ0FBQyxDQUFDLDJCQUEyQixDQUFDLG1EQUFtRCxFQUFFLFFBQVEsQ0FBQztJQUM1RixDQUFDLENBQUMsUUFBUSxDQUFDO0FBRWYsTUFBTSxDQUFDLE1BQU0sNEJBQTRCLEdBQUcsQ0FBQyxRQUFpQixFQUFXLEVBQUUsQ0FDekUsUUFBUSxZQUFZLE9BQU8sQ0FBQyxPQUFPLENBQUMsZ0JBQWdCO0lBQ3BELENBQ0UsUUFBUSxDQUFDLGFBQWEsQ0FBQywyQkFBMkIsQ0FBQztRQUNuRCxRQUFRLENBQUMsYUFBYSxDQUFDLGdDQUFnQyxDQUFDLENBQ3pELENBQUM7QUFFSixNQUFNLENBQUMsTUFBTSx3QkFBd0IsR0FBRyxDQUN0QyxRQUFpQixFQUM2QixFQUFFO0lBQ2hELE9BQU8sQ0FDTCxRQUFRLFlBQVksT0FBTyxDQUFDLE9BQU8sQ0FBQyxnQkFBZ0I7UUFDcEQsQ0FBQyxRQUFRLENBQUMsSUFBSSxLQUFLLEtBQUssSUFBSSxRQUFRLENBQUMsUUFBUSxLQUFLLGNBQWMsQ0FBQyxDQUNsRSxDQUFDO0FBQ0osQ0FBQyxDQUFDO0FBRUY7Ozs7R0FJRztBQUNILE1BQU0sQ0FBQyxNQUFNLHlCQUF5QixHQUFHLENBQ3ZDLFFBQWlCLEVBQzZCLEVBQUU7SUFDaEQsT0FBTyxDQUNMLFFBQVEsWUFBWSxPQUFPLENBQUMsT0FBTyxDQUFDLGdCQUFnQjtRQUNwRCxDQUFDLFFBQVEsQ0FBQyxJQUFJLEtBQUssRUFBRTtZQUNuQixRQUFRLENBQUMsSUFBSSxLQUFLLEVBQUU7WUFDcEIsUUFBUSxDQUFDLFFBQVEsS0FBSyxzQkFBc0I7WUFDNUMsUUFBUSxDQUFDLFFBQVEsS0FBSyx1QkFBdUIsQ0FBQyxDQUNqRCxDQUFDO0FBQ0osQ0FBQyxDQUFDO0FBRUYsTUFBTSxDQUFDLE1BQU0saUNBQWlDLEdBQUcsQ0FDL0MsUUFBaUIsRUFDakIsVUFBa0IsRUFDWCxFQUFFO0lBQ1QsSUFDRSxRQUFRLFlBQVkseUJBQXlCO1FBQzdDLDRCQUE0QixDQUFDLFFBQVEsQ0FBQyxFQUN0QyxDQUFDO1FBQ0QsTUFBTSxRQUFRLENBQUM7SUFDakIsQ0FBQztJQUNELElBQUksd0JBQXdCLENBQUMsUUFBUSxDQUFDLEVBQUUsQ0FBQztRQUN2QyxNQUFNLElBQUkseUJBQXlCLENBQUMsaUJBQWlCLEVBQUUsVUFBVSxFQUFFO1lBQ2pFLEtBQUssRUFBRSxRQUFRO1NBQ2hCLENBQUMsQ0FBQztJQUNMLENBQUM7SUFDRCxNQUFNLFFBQVEsQ0FBQztBQUNqQixDQUFDLENBQUMifQ==

package/dist_ts/nosqldb/classes.session.d.ts

@@ -1,5 +1,6 @@
 import * as plugins from './plugins.js';
 import type { SmartdataDb } from './classes.db.js';
+import { SmartdataOperationDeadline } from './classes.operationdeadline.js';
 interface ISmartdataSessionAcquireOptions {
     ordinaryWrite?: boolean;
 }
@@ -8,9 +9,56 @@ interface IOrdinarySessionOperationOptions {
     prepared?: boolean;
     /** Names the collection whose preparation a refusal must ask for. */
     collectionName?: string;
+    /** The caller's validated client deadline for the call's database work. */
+    timeoutMS?: number;
+    /** The API's own default deadline; a transaction deadline replaces it. */
+    defaultTimeoutMS?: number;
+    /** The caller's validated cancellation signal for the call's database work. */
+    signal?: AbortSignal;
+}
+export interface ISmartdataTransactionOptions {
+    /**
+     * Client deadline for the whole transaction (1..120000 ms): every attempt,
+     * the operations the callback runs on the session, the driver's retries and
+     * the commit. Operations inside take no `timeoutMS` of their own.
+     */
+    timeoutMS?: number;
+    /**
+     * Cancels the transaction. Every operation the callback runs on the session
+     * observes it: the one in flight is interrupted and every later one is
+     * refused with the abort reason. An aborted transaction is rolled back and
+     * never committed; a commit already sent runs to its own outcome.
+     */
+    signal?: AbortSignal;
 }
 export declare class SmartdataSession {
-    withTransaction<TResult>(callbackArg: (sessionArg: SmartdataSession) => Promise<TResult>): Promise<TResult | undefined>;
+    /**
+     * Runs `callbackArg` in a transaction, retrying it as the driver decides.
+     *
+     * `timeoutMS` bounds the whole transaction through the driver's client-side
+     * operation timeout. When it expires the call rejects with a
+     * `SmartdataPersistenceError` of code `timeout`: before the commit was sent
+     * nothing was committed, during the commit the outcome is unknown. When the
+     * deadline expires inside the callback, the driver's closing
+     * `abortTransaction` runs on a fresh deadline of the same length, so a
+     * stalled database settles the call within about twice `timeoutMS`.
+     *
+     * `signal` cancels the transaction. An abort before the call rejects with
+     * the abort reason at once. An abort while the callback runs interrupts the
+     * operation in flight on the session and refuses every later one with the
+     * reason; once the callback has settled, the driver's `abortTransaction`
+     * rolls the attempt back and the call rejects with the reason, even when
+     * the callback caught it, and no further attempt starts. The driver cannot
+     * cancel a commit in flight, so an abort that arrives after the commit was
+     * sent leaves the commit to its own outcome: the call returns the result
+     * when it committed, and rejects with `timeout` ("the commit outcome is
+     * unknown") when the deadline expired during it.
+     *
+     * Any operation on the session that its deadline or a signal interrupts
+     * fails the attempt: the call rolls it back and rejects with that
+     * operation's error even when the callback caught it.
+     */
+    withTransaction<TResult>(callbackArg: (sessionArg: SmartdataSession) => Promise<TResult>, optionsArg?: ISmartdataTransactionOptions): Promise<TResult | undefined>;
     close(): Promise<void>;
 }
 export declare const createSmartdataSession: (ownerArg: SmartdataDb) => SmartdataSession;
@@ -36,7 +84,30 @@ export declare const leaseOrdinarySmartdataSession: (sessionArg: TSmartdataOrdin
     rawSession: plugins.mongodb.ClientSession | undefined;
     release: () => void;
 };
-export declare const runWithOrdinarySmartdataSession: <TResult>(sessionArg: TSmartdataOrdinarySession | undefined, ownerArg: SmartdataDb, optionsArg: IOrdinarySessionOperationOptions, operationArg: (rawSessionArg: plugins.mongodb.ClientSession | undefined) => Promise<TResult>) => Promise<TResult>;
+/**
+ * The deadline and signal one operation runs under. Inside an owned
+ * transaction with a deadline, the transaction's deadline bounds the
+ * operation through the session, and the driver refuses a second one on the
+ * same session, so an explicit operation deadline is refused and a default
+ * one is dropped. Inside an owned transaction with a signal, the operation
+ * observes that signal beside its own.
+ */
+export declare const resolveSmartdataOperationDeadline: (sessionArg: TSmartdataOrdinarySession | undefined, optionsArg: Pick<IOrdinarySessionOperationOptions, "timeoutMS" | "defaultTimeoutMS" | "signal">) => SmartdataOperationDeadline;
+/**
+ * The error one operation on the session boundary rejects with: an expired
+ * driver deadline becomes the `timeout` persistence error, everything else
+ * passes through. An operation its deadline or signal interrupted inside an
+ * owned transaction also fails the transaction attempt, so `withTransaction`
+ * rolls it back and rejects with that error even when the callback caught it:
+ * whatever the interrupted command did inside the transaction is unknown.
+ */
+export declare const settleSmartdataOperationError: (sessionArg: TSmartdataOrdinarySession | undefined, deadlineArg: SmartdataOperationDeadline, errorArg: unknown) => unknown;
+/**
+ * Runs one model operation on the ordinary session boundary: the owned
+ * session lease, the operation's client deadline and signal, and the mapping
+ * of an expired driver deadline to the `timeout` persistence error.
+ */
+export declare const runWithOrdinarySmartdataSession: <TResult>(sessionArg: TSmartdataOrdinarySession | undefined, ownerArg: SmartdataDb, optionsArg: IOrdinarySessionOperationOptions, operationArg: (rawSessionArg: plugins.mongodb.ClientSession | undefined, deadlineArg: SmartdataOperationDeadline) => Promise<TResult>) => Promise<TResult>;
 export declare const invalidateSmartdataSessions: (ownerArg: SmartdataDb) => Promise<void>;
 export declare const unwrapSmartdataSessionInvalidationErrors: (errorArg: unknown) => readonly unknown[] | undefined;
 export {};