@lossless.org/client 1.12.0 → 1.14.0

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

@@ -25,6 +25,12 @@ 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;
+/**
+ * The server or the driver stated that the transaction was aborted and may be
+ * run again from its start, so nothing of it was committed. A timeout the
+ * driver raises in place of such an error copies its labels.
+ */
+export declare const isMongoTransientTransactionError: (errorArg: unknown) => boolean;
 export declare const isMongoDuplicateKeyError: (errorArg: unknown) => errorArg is plugins.mongodb.MongoServerError;
 /**
  * MongoDB refuses an index whose key or name collides with an existing one:

package/dist_ts/nosqldb/classes.persistence.js

@@ -34,6 +34,13 @@ export const normalizeDeadlineError = (errorArg) => isMongoDeadlineError(errorAr
 export const isMongoTransactionRetryError = (errorArg) => errorArg instanceof plugins.mongodb.MongoServerError &&
     (errorArg.hasErrorLabel('TransientTransactionError') ||
         errorArg.hasErrorLabel('UnknownTransactionCommitResult'));
+/**
+ * The server or the driver stated that the transaction was aborted and may be
+ * run again from its start, so nothing of it was committed. A timeout the
+ * driver raises in place of such an error copies its labels.
+ */
+export const isMongoTransientTransactionError = (errorArg) => errorArg instanceof plugins.mongodb.MongoError
+    && errorArg.hasErrorLabel(plugins.mongodb.MongoErrorLabel.TransientTransactionError);
 export const isMongoDuplicateKeyError = (errorArg) => {
     return (errorArg instanceof plugins.mongodb.MongoServerError &&
         (errorArg.code === 11000 || errorArg.codeName === 'DuplicateKey'));
@@ -62,4 +69,4 @@ export const normalizeOrdinaryPersistenceError = (errorArg, messageArg) => {
     }
     throw errorArg;
 };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5wZXJzaXN0ZW5jZS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL25vc3FsZGIvY2xhc3Nlcy5wZXJzaXN0ZW5jZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGNBQWMsQ0FBQztBQVd4Qzs7OztHQUlHO0FBQ0gsTUFBTSxPQUFPLHlCQUEwQixTQUFRLEtBQUs7SUFDbEMsSUFBSSxDQUFpQztJQUVyRCxZQUNFLE9BQXVDLEVBQ3ZDLFVBQWtCLEVBQ2xCLFVBQXlCO1FBRXpCLEtBQUssQ0FBQyxVQUFVLEVBQUUsVUFBVSxDQUFDLENBQUM7UUFDOUIsSUFBSSxDQUFDLElBQUksR0FBRywyQkFBMkIsQ0FBQztRQUN4QyxJQUFJLENBQUMsSUFBSSxHQUFHLE9BQU8sQ0FBQztJQUN0QixDQUFDO0NBQ0Y7QUFFRDs7Ozs7R0FLRztBQUNILE1BQU0sQ0FBQyxNQUFNLDJCQUEyQixHQUFHLENBQ3pDLFVBQWtCLEVBQ2xCLFFBQWtCLEVBQ1MsRUFBRSxDQUM3QixJQUFJLHlCQUF5QixDQUMzQixTQUFTLEVBQ1QsVUFBVSxFQUNWLFFBQVEsS0FBSyxTQUFTLENBQUMsQ0FBQyxDQUFDLFNBQVMsQ0FBQyxDQUFDLENBQUMsRUFBRSxLQUFLLEVBQUUsUUFBUSxFQUFFLENBQ3pELENBQUM7QUFFSjs7OztHQUlHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sb0JBQW9CLEdBQUcsQ0FBQyxRQUFpQixFQUFXLEVBQUUsQ0FDakUsUUFBUSxZQUFZLE9BQU8sQ0FBQyxPQUFPLENBQUMsMEJBQTBCO09BQzNELENBQ0QsUUFBUSxZQUFZLE9BQU8sQ0FBQyxPQUFPLENBQUMsbUJBQW1CO1dBQ3BELFFBQVEsQ0FBQyxhQUFhLFlBQVksT0FBTyxDQUFDLE9BQU8sQ0FBQywwQkFBMEIsQ0FDaEYsQ0FBQztBQUVKLGdHQUFnRztBQUNoRyxNQUFNLENBQUMsTUFBTSxzQkFBc0IsR0FBRyxDQUFDLFFBQWlCLEVBQVcsRUFBRSxDQUNuRSxvQkFBb0IsQ0FBQyxRQUFRLENBQUM7SUFDNUIsQ0FBQyxDQUFDLDJCQUEyQixDQUFDLG1EQUFtRCxFQUFFLFFBQVEsQ0FBQztJQUM1RixDQUFDLENBQUMsUUFBUSxDQUFDO0FBRWYsTUFBTSxDQUFDLE1BQU0sNEJBQTRCLEdBQUcsQ0FBQyxRQUFpQixFQUFXLEVBQUUsQ0FDekUsUUFBUSxZQUFZLE9BQU8sQ0FBQyxPQUFPLENBQUMsZ0JBQWdCO0lBQ3BELENBQ0UsUUFBUSxDQUFDLGFBQWEsQ0FBQywyQkFBMkIsQ0FBQztRQUNuRCxRQUFRLENBQUMsYUFBYSxDQUFDLGdDQUFnQyxDQUFDLENBQ3pELENBQUM7QUFFSixNQUFNLENBQUMsTUFBTSx3QkFBd0IsR0FBRyxDQUN0QyxRQUFpQixFQUM2QixFQUFFO0lBQ2hELE9BQU8sQ0FDTCxRQUFRLFlBQVksT0FBTyxDQUFDLE9BQU8sQ0FBQyxnQkFBZ0I7UUFDcEQsQ0FBQyxRQUFRLENBQUMsSUFBSSxLQUFLLEtBQUssSUFBSSxRQUFRLENBQUMsUUFBUSxLQUFLLGNBQWMsQ0FBQyxDQUNsRSxDQUFDO0FBQ0osQ0FBQyxDQUFDO0FBRUY7Ozs7R0FJRztBQUNILE1BQU0sQ0FBQyxNQUFNLHlCQUF5QixHQUFHLENBQ3ZDLFFBQWlCLEVBQzZCLEVBQUU7SUFDaEQsT0FBTyxDQUNMLFFBQVEsWUFBWSxPQUFPLENBQUMsT0FBTyxDQUFDLGdCQUFnQjtRQUNwRCxDQUFDLFFBQVEsQ0FBQyxJQUFJLEtBQUssRUFBRTtZQUNuQixRQUFRLENBQUMsSUFBSSxLQUFLLEVBQUU7WUFDcEIsUUFBUSxDQUFDLFFBQVEsS0FBSyxzQkFBc0I7WUFDNUMsUUFBUSxDQUFDLFFBQVEsS0FBSyx1QkFBdUIsQ0FBQyxDQUNqRCxDQUFDO0FBQ0osQ0FBQyxDQUFDO0FBRUYsTUFBTSxDQUFDLE1BQU0saUNBQWlDLEdBQUcsQ0FDL0MsUUFBaUIsRUFDakIsVUFBa0IsRUFDWCxFQUFFO0lBQ1QsSUFDRSxRQUFRLFlBQVkseUJBQXlCO1FBQzdDLDRCQUE0QixDQUFDLFFBQVEsQ0FBQyxFQUN0QyxDQUFDO1FBQ0QsTUFBTSxRQUFRLENBQUM7SUFDakIsQ0FBQztJQUNELElBQUksd0JBQXdCLENBQUMsUUFBUSxDQUFDLEVBQUUsQ0FBQztRQUN2QyxNQUFNLElBQUkseUJBQXlCLENBQUMsaUJBQWlCLEVBQUUsVUFBVSxFQUFFO1lBQ2pFLEtBQUssRUFBRSxRQUFRO1NBQ2hCLENBQUMsQ0FBQztJQUNMLENBQUM7SUFDRCxNQUFNLFFBQVEsQ0FBQztBQUNqQixDQUFDLENBQUMifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5wZXJzaXN0ZW5jZS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL25vc3FsZGIvY2xhc3Nlcy5wZXJzaXN0ZW5jZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGNBQWMsQ0FBQztBQVd4Qzs7OztHQUlHO0FBQ0gsTUFBTSxPQUFPLHlCQUEwQixTQUFRLEtBQUs7SUFDbEMsSUFBSSxDQUFpQztJQUVyRCxZQUNFLE9BQXVDLEVBQ3ZDLFVBQWtCLEVBQ2xCLFVBQXlCO1FBRXpCLEtBQUssQ0FBQyxVQUFVLEVBQUUsVUFBVSxDQUFDLENBQUM7UUFDOUIsSUFBSSxDQUFDLElBQUksR0FBRywyQkFBMkIsQ0FBQztRQUN4QyxJQUFJLENBQUMsSUFBSSxHQUFHLE9BQU8sQ0FBQztJQUN0QixDQUFDO0NBQ0Y7QUFFRDs7Ozs7R0FLRztBQUNILE1BQU0sQ0FBQyxNQUFNLDJCQUEyQixHQUFHLENBQ3pDLFVBQWtCLEVBQ2xCLFFBQWtCLEVBQ1MsRUFBRSxDQUM3QixJQUFJLHlCQUF5QixDQUMzQixTQUFTLEVBQ1QsVUFBVSxFQUNWLFFBQVEsS0FBSyxTQUFTLENBQUMsQ0FBQyxDQUFDLFNBQVMsQ0FBQyxDQUFDLENBQUMsRUFBRSxLQUFLLEVBQUUsUUFBUSxFQUFFLENBQ3pELENBQUM7QUFFSjs7OztHQUlHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sb0JBQW9CLEdBQUcsQ0FBQyxRQUFpQixFQUFXLEVBQUUsQ0FDakUsUUFBUSxZQUFZLE9BQU8sQ0FBQyxPQUFPLENBQUMsMEJBQTBCO09BQzNELENBQ0QsUUFBUSxZQUFZLE9BQU8sQ0FBQyxPQUFPLENBQUMsbUJBQW1CO1dBQ3BELFFBQVEsQ0FBQyxhQUFhLFlBQVksT0FBTyxDQUFDLE9BQU8sQ0FBQywwQkFBMEIsQ0FDaEYsQ0FBQztBQUVKLGdHQUFnRztBQUNoRyxNQUFNLENBQUMsTUFBTSxzQkFBc0IsR0FBRyxDQUFDLFFBQWlCLEVBQVcsRUFBRSxDQUNuRSxvQkFBb0IsQ0FBQyxRQUFRLENBQUM7SUFDNUIsQ0FBQyxDQUFDLDJCQUEyQixDQUFDLG1EQUFtRCxFQUFFLFFBQVEsQ0FBQztJQUM1RixDQUFDLENBQUMsUUFBUSxDQUFDO0FBRWYsTUFBTSxDQUFDLE1BQU0sNEJBQTRCLEdBQUcsQ0FBQyxRQUFpQixFQUFXLEVBQUUsQ0FDekUsUUFBUSxZQUFZLE9BQU8sQ0FBQyxPQUFPLENBQUMsZ0JBQWdCO0lBQ3BELENBQ0UsUUFBUSxDQUFDLGFBQWEsQ0FBQywyQkFBMkIsQ0FBQztRQUNuRCxRQUFRLENBQUMsYUFBYSxDQUFDLGdDQUFnQyxDQUFDLENBQ3pELENBQUM7QUFFSjs7OztHQUlHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sZ0NBQWdDLEdBQUcsQ0FBQyxRQUFpQixFQUFXLEVBQUUsQ0FDN0UsUUFBUSxZQUFZLE9BQU8sQ0FBQyxPQUFPLENBQUMsVUFBVTtPQUMzQyxRQUFRLENBQUMsYUFBYSxDQUFDLE9BQU8sQ0FBQyxPQUFPLENBQUMsZUFBZSxDQUFDLHlCQUF5QixDQUFDLENBQUM7QUFFdkYsTUFBTSxDQUFDLE1BQU0sd0JBQXdCLEdBQUcsQ0FDdEMsUUFBaUIsRUFDNkIsRUFBRTtJQUNoRCxPQUFPLENBQ0wsUUFBUSxZQUFZLE9BQU8sQ0FBQyxPQUFPLENBQUMsZ0JBQWdCO1FBQ3BELENBQUMsUUFBUSxDQUFDLElBQUksS0FBSyxLQUFLLElBQUksUUFBUSxDQUFDLFFBQVEsS0FBSyxjQUFjLENBQUMsQ0FDbEUsQ0FBQztBQUNKLENBQUMsQ0FBQztBQUVGOzs7O0dBSUc7QUFDSCxNQUFNLENBQUMsTUFBTSx5QkFBeUIsR0FBRyxDQUN2QyxRQUFpQixFQUM2QixFQUFFO0lBQ2hELE9BQU8sQ0FDTCxRQUFRLFlBQVksT0FBTyxDQUFDLE9BQU8sQ0FBQyxnQkFBZ0I7UUFDcEQsQ0FBQyxRQUFRLENBQUMsSUFBSSxLQUFLLEVBQUU7WUFDbkIsUUFBUSxDQUFDLElBQUksS0FBSyxFQUFFO1lBQ3BCLFFBQVEsQ0FBQyxRQUFRLEtBQUssc0JBQXNCO1lBQzVDLFFBQVEsQ0FBQyxRQUFRLEtBQUssdUJBQXVCLENBQUMsQ0FDakQsQ0FBQztBQUNKLENBQUMsQ0FBQztBQUVGLE1BQU0sQ0FBQyxNQUFNLGlDQUFpQyxHQUFHLENBQy9DLFFBQWlCLEVBQ2pCLFVBQWtCLEVBQ1gsRUFBRTtJQUNULElBQ0UsUUFBUSxZQUFZLHlCQUF5QjtRQUM3Qyw0QkFBNEIsQ0FBQyxRQUFRLENBQUMsRUFDdEMsQ0FBQztRQUNELE1BQU0sUUFBUSxDQUFDO0lBQ2pCLENBQUM7SUFDRCxJQUFJLHdCQUF3QixDQUFDLFFBQVEsQ0FBQyxFQUFFLENBQUM7UUFDdkMsTUFBTSxJQUFJLHlCQUF5QixDQUFDLGlCQUFpQixFQUFFLFVBQVUsRUFBRTtZQUNqRSxLQUFLLEVBQUUsUUFBUTtTQUNoQixDQUFDLENBQUM7SUFDTCxDQUFDO0lBQ0QsTUFBTSxRQUFRLENBQUM7QUFDakIsQ0FBQyxDQUFDIn0=

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

@@ -0,0 +1,65 @@
+import * as plugins from './plugins.js';
+import type { SmartdataDb } from './classes.db.js';
+import type { MongoFilter, TSmartdataProjection, TSmartdataSort } from './classes.doc.js';
+export interface ISmartdataQueryPlanOptions<T> {
+    /** Validated exactly like the filter of the model's ordinary reads. */
+    filter: MongoFilter<T>;
+    /** Declared paths or `_id`, each 1 or -1, as for `getCursor()` and `getOffsetPage()`. */
+    sort?: TSmartdataSort<T>;
+    /** Declared paths or `_id`, 0 or 1, as for `getCursor()` and `getOffsetPage()`. */
+    projection?: TSmartdataProjection<T>;
+    /** 1..10000. Without it the plan executes over every match. */
+    limit?: number;
+    /** Client deadline for the explained execution. Default 5000ms, maximum 120000ms. */
+    timeoutMS?: number;
+    signal?: AbortSignal;
+}
+/** One stage of the winning plan, in depth-first order from the root. */
+export interface ISmartdataQueryPlanStage {
+    /** The engine's stage name, such as `IXSCAN`, `COLLSCAN`, `FETCH`, `SORT` or `LIMIT`. */
+    readonly stage: string;
+    /** 0 for the root; a stage's inputs follow it at one level deeper. */
+    readonly depth: number;
+    /** The index the stage reads, when the engine names one. */
+    readonly indexName?: string;
+    /** The scan direction, when the engine states one. */
+    readonly direction?: 'forward' | 'backward';
+}
+export interface ISmartdataQueryPlan {
+    /** The winning plan's stage tree, flattened depth-first. */
+    readonly stages: readonly ISmartdataQueryPlanStage[];
+    readonly nReturned: number;
+    readonly totalKeysExamined: number;
+    readonly totalDocsExamined: number;
+    /** Present when the engine reports it. */
+    readonly executionTimeMillis?: number;
+}
+/** @internal The query-plan options after their bounds are checked. */
+export interface IValidatedQueryPlanOptions<T> {
+    readonly filter: MongoFilter<T>;
+    readonly sort: TSmartdataSort<T> | undefined;
+    readonly projection: TSmartdataProjection<T> | undefined;
+    readonly limit: number | undefined;
+    readonly timeoutMS: number;
+    readonly signal: AbortSignal | undefined;
+}
+/** @internal The normalized query one inspection explains. */
+export interface IQueryPlanRequest {
+    readonly collectionName: string;
+    readonly filter: plugins.mongodb.Filter<plugins.mongodb.Document>;
+    readonly sort: plugins.mongodb.Sort | undefined;
+    readonly projection: plugins.mongodb.Document | undefined;
+    readonly limit: number | undefined;
+    readonly timeoutMS: number;
+    readonly signal: AbortSignal | undefined;
+}
+/** @internal Refuses every option shape the query-plan inspection does not define. */
+export declare const requireQueryPlanOptions: <T>(optionsArg: ISmartdataQueryPlanOptions<T>) => IValidatedQueryPlanOptions<T>;
+/** @internal Reduces an `executionStats` explanation to the stable summary; exported for its unit test. */
+export declare const summarizeQueryPlanExplanation: (explanationArg: plugins.mongodb.Document) => ISmartdataQueryPlan;
+/**
+ * @internal Explains one model query with `executionStats` on the given
+ * database. Nothing is created, bound or hydrated; the raw explanation never
+ * leaves this module.
+ */
+export declare const inspectQueryPlan: (dbArg: SmartdataDb, requestArg: IQueryPlanRequest) => Promise<ISmartdataQueryPlan>;

package/dist_ts/nosqldb/classes.queryplaninspection.js

@@ -0,0 +1,148 @@
+import * as plugins from './plugins.js';
+import { SmartdataPersistenceError, createSmartdataTimeoutError, isMongoDeadlineError } from './classes.persistence.js';
+import { requireOperationSignal, requireOperationTimeoutMS } from './classes.operationdeadline.js';
+import { runCursorOperation } from './classes.cursoroperation.js';
+import { collectionTopologyDbInspectionSymbol } from './classes.collectiontopology.js';
+const queryPlanOptionKeys = ['filter', 'sort', 'projection', 'limit', 'timeoutMS', 'signal'];
+const maximumPlanStages = 256;
+const maximumPlanDepth = 64;
+const maximumPlanStringLength = 1024;
+/** MongoDB's `CommandNotFound`, the answer of an engine that implements no `explain`. */
+const commandNotFoundCode = 59;
+const isRecord = (valueArg) => typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg);
+const isPlainRecord = (valueArg) => {
+    if (!isRecord(valueArg))
+        return false;
+    const prototype = Object.getPrototypeOf(valueArg);
+    return prototype === Object.prototype || prototype === null;
+};
+/** @internal Refuses every option shape the query-plan inspection does not define. */
+export const requireQueryPlanOptions = (optionsArg) => {
+    const options = optionsArg;
+    if (!isPlainRecord(options) || Reflect.ownKeys(options).some((keyArg) => typeof keyArg !== 'string' || !queryPlanOptionKeys.includes(keyArg) ||
+        !('value' in Object.getOwnPropertyDescriptor(options, keyArg)))) {
+        throw new SmartdataPersistenceError('invalid_argument', 'Invalid query plan inspection options.');
+    }
+    if (!isPlainRecord(optionsArg.filter)) {
+        throw new SmartdataPersistenceError('invalid_argument', 'Query plan inspection requires a plain filter object.');
+    }
+    const limit = optionsArg.limit;
+    if (limit !== undefined &&
+        (typeof limit !== 'number' || !Number.isSafeInteger(limit) || limit < 1 || limit > 10_000)) {
+        throw new SmartdataPersistenceError('invalid_argument', 'limit must be an integer from 1 through 10000.');
+    }
+    return {
+        filter: optionsArg.filter,
+        sort: optionsArg.sort,
+        projection: optionsArg.projection,
+        limit,
+        timeoutMS: requireOperationTimeoutMS(optionsArg.timeoutMS, 'timeoutMS') ?? 5_000,
+        signal: requireOperationSignal(optionsArg.signal, 'signal'),
+    };
+};
+const unreadablePlan = () => new SmartdataPersistenceError('unsupported_operation', 'The engine returned an unreadable query plan.');
+const readCount = (valueArg) => {
+    if (typeof valueArg !== 'number' || !Number.isSafeInteger(valueArg) || valueArg < 0) {
+        throw unreadablePlan();
+    }
+    return valueArg;
+};
+const readPlanString = (valueArg) => {
+    if (typeof valueArg !== 'string' || valueArg.length === 0 || valueArg.length > maximumPlanStringLength) {
+        throw unreadablePlan();
+    }
+    return valueArg;
+};
+/**
+ * Flattens the winning plan depth-first. MongoDB's slot-based engine wraps the
+ * classic tree as `queryPlan`; every other field of a stage stays behind.
+ */
+const flattenWinningPlan = (winningPlanArg) => {
+    const root = isRecord(winningPlanArg) && winningPlanArg.stage === undefined && isRecord(winningPlanArg.queryPlan)
+        ? winningPlanArg.queryPlan
+        : winningPlanArg;
+    const stages = [];
+    const visit = (nodeArg, depthArg) => {
+        if (!isRecord(nodeArg) || depthArg >= maximumPlanDepth || stages.length === maximumPlanStages) {
+            throw unreadablePlan();
+        }
+        const direction = nodeArg.direction === 'forward' || nodeArg.direction === 'backward'
+            ? nodeArg.direction
+            : undefined;
+        stages.push(Object.freeze({
+            stage: readPlanString(nodeArg.stage),
+            depth: depthArg,
+            ...(nodeArg.indexName === undefined ? {} : { indexName: readPlanString(nodeArg.indexName) }),
+            ...(direction === undefined ? {} : { direction }),
+        }));
+        const inputs = nodeArg.inputStages === undefined ? [] : nodeArg.inputStages;
+        if (!Array.isArray(inputs))
+            throw unreadablePlan();
+        if (nodeArg.inputStage !== undefined)
+            visit(nodeArg.inputStage, depthArg + 1);
+        for (const input of inputs)
+            visit(input, depthArg + 1);
+    };
+    visit(root, 0);
+    return stages;
+};
+/** @internal Reduces an `executionStats` explanation to the stable summary; exported for its unit test. */
+export const summarizeQueryPlanExplanation = (explanationArg) => {
+    const queryPlanner = explanationArg.queryPlanner;
+    const executionStats = explanationArg.executionStats;
+    if (!isRecord(queryPlanner) || !isRecord(executionStats) || executionStats.executionSuccess === false) {
+        throw unreadablePlan();
+    }
+    const stages = flattenWinningPlan(queryPlanner.winningPlan);
+    const executionTimeMillis = executionStats.executionTimeMillis === undefined
+        ? undefined
+        : readCount(executionStats.executionTimeMillis);
+    return Object.freeze({
+        stages: Object.freeze(stages),
+        nReturned: readCount(executionStats.nReturned),
+        totalKeysExamined: readCount(executionStats.totalKeysExamined),
+        totalDocsExamined: readCount(executionStats.totalDocsExamined),
+        ...(executionTimeMillis === undefined ? {} : { executionTimeMillis }),
+    });
+};
+/**
+ * @internal Explains one model query with `executionStats` on the given
+ * database. Nothing is created, bound or hydrated; the raw explanation never
+ * leaves this module.
+ */
+export const inspectQueryPlan = async (dbArg, requestArg) => {
+    const { signal } = requestArg;
+    signal?.throwIfAborted();
+    let failure;
+    let explanation;
+    try {
+        explanation = await dbArg[collectionTopologyDbInspectionSymbol](async (mongoDbArg) => {
+            const cursor = mongoDbArg.collection(requestArg.collectionName).find(requestArg.filter, {
+                ...(requestArg.sort === undefined ? {} : { sort: requestArg.sort }),
+                ...(requestArg.projection === undefined ? {} : { projection: requestArg.projection }),
+                ...(requestArg.limit === undefined ? {} : { limit: requestArg.limit }),
+                ...(signal === undefined ? {} : { signal }),
+            });
+            try {
+                return await runCursorOperation(cursor, (cursorArg) => cursorArg.explain('executionStats', { timeoutMS: requestArg.timeoutMS }), signal);
+            }
+            catch (errorArg) {
+                failure = { error: errorArg };
+                throw errorArg;
+            }
+        });
+    }
+    catch (errorArg) {
+        signal?.throwIfAborted();
+        if (failure !== undefined && isMongoDeadlineError(failure.error)) {
+            throw createSmartdataTimeoutError('Query plan inspection exceeded its client deadline.', failure.error);
+        }
+        if (failure !== undefined && failure.error instanceof plugins.mongodb.MongoServerError &&
+            failure.error.code === commandNotFoundCode) {
+            throw new SmartdataPersistenceError('unsupported_operation', 'The connected engine does not explain queries.');
+        }
+        throw errorArg;
+    }
+    return summarizeQueryPlanExplanation(explanation);
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5xdWVyeXBsYW5pbnNwZWN0aW9uLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHMvbm9zcWxkYi9jbGFzc2VzLnF1ZXJ5cGxhbmluc3BlY3Rpb24udHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSxjQUFjLENBQUM7QUFHeEMsT0FBTyxFQUFFLHlCQUF5QixFQUFFLDJCQUEyQixFQUFFLG9CQUFvQixFQUFFLE1BQU0sMEJBQTBCLENBQUM7QUFDeEgsT0FBTyxFQUFFLHNCQUFzQixFQUFFLHlCQUF5QixFQUFFLE1BQU0sZ0NBQWdDLENBQUM7QUFDbkcsT0FBTyxFQUFFLGtCQUFrQixFQUFFLE1BQU0sOEJBQThCLENBQUM7QUFDbEUsT0FBTyxFQUFFLG9DQUFvQyxFQUFFLE1BQU0saUNBQWlDLENBQUM7QUEyRHZGLE1BQU0sbUJBQW1CLEdBQXNCLENBQUMsUUFBUSxFQUFFLE1BQU0sRUFBRSxZQUFZLEVBQUUsT0FBTyxFQUFFLFdBQVcsRUFBRSxRQUFRLENBQUMsQ0FBQztBQUNoSCxNQUFNLGlCQUFpQixHQUFHLEdBQUcsQ0FBQztBQUM5QixNQUFNLGdCQUFnQixHQUFHLEVBQUUsQ0FBQztBQUM1QixNQUFNLHVCQUF1QixHQUFHLElBQUksQ0FBQztBQUNyQyx5RkFBeUY7QUFDekYsTUFBTSxtQkFBbUIsR0FBRyxFQUFFLENBQUM7QUFFL0IsTUFBTSxRQUFRLEdBQUcsQ0FBQyxRQUFpQixFQUF1QyxFQUFFLENBQzFFLE9BQU8sUUFBUSxLQUFLLFFBQVEsSUFBSSxRQUFRLEtBQUssSUFBSSxJQUFJLENBQUMsS0FBSyxDQUFDLE9BQU8sQ0FBQyxRQUFRLENBQUMsQ0FBQztBQUVoRixNQUFNLGFBQWEsR0FBRyxDQUFDLFFBQWlCLEVBQXVDLEVBQUU7SUFDL0UsSUFBSSxDQUFDLFFBQVEsQ0FBQyxRQUFRLENBQUM7UUFBRSxPQUFPLEtBQUssQ0FBQztJQUN0QyxNQUFNLFNBQVMsR0FBRyxN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

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

@@ -1,6 +1,17 @@
 import * as plugins from './plugins.js';
 import type { SmartdataDb } from './classes.db.js';
 import { SmartdataOperationDeadline } from './classes.operationdeadline.js';
+/**
+ * Whether a transaction that `SmartdataSession.withTransaction()` rejected
+ * could have committed:
+ *
+ * - `not_committed`: nothing of the transaction was committed. The call failed
+ *   before the driver sent a commit, or the database answered the commit with
+ *   an error that states the transaction was aborted.
+ * - `unknown`: a commit was sent and its outcome was never confirmed; it may
+ *   have applied.
+ */
+export type TSmartdataTransactionCommitOutcome = 'not_committed' | 'unknown';
 interface ISmartdataSessionAcquireOptions {
     ordinaryWrite?: boolean;
 }
@@ -32,6 +43,20 @@ export interface ISmartdataTransactionOptions {
     signal?: AbortSignal;
 }
 export declare class SmartdataSession {
+    /**
+     * Whether the transaction whose `withTransaction()` call rejected with
+     * `errorArg` could have committed: `not_committed` when nothing of it was
+     * committed, `unknown` when a commit was sent and never confirmed, so it may
+     * have applied. Every rejection of `withTransaction()` carries one, whatever
+     * it is: the client's own errors, the callback's error, the abort reason or
+     * a driver error, which all keep their identity. A value several calls
+     * rejected with reads `unknown` once any of them may have committed.
+     *
+     * Returns `undefined` for any other value, and for a primitive rejection —
+     * a callback that throws a string, or a string abort reason — which cannot
+     * carry the outcome; treat `undefined` as `unknown`.
+     */
+    static getCommitOutcome(errorArg: unknown): TSmartdataTransactionCommitOutcome | undefined;
     /**
      * Runs `callbackArg` in a transaction, retrying it as the driver decides.
      *
@@ -63,6 +88,10 @@ export declare class SmartdataSession {
      * `unsupported_operation`: before the callback returned nothing was
      * committed, afterwards the commit outcome is unknown. The callback's
      * error, if it threw, is the `cause`.
+     *
+     * Every rejection states whether the transaction could have committed:
+     * `SmartdataSession.getCommitOutcome(error)` returns `not_committed` or
+     * `unknown` for the value the call rejected with.
      */
     withTransaction<TResult>(callbackArg: (sessionArg: SmartdataSession) => Promise<TResult>, optionsArg?: ISmartdataTransactionOptions): Promise<TResult | undefined>;
     close(): Promise<void>;