@lossless.org/client 1.12.0 → 1.14.0

package/ts/nosqldb/classes.queryplaninspection.ts

@@ -0,0 +1,220 @@
+import * as plugins from './plugins.js';
+import type { SmartdataDb } from './classes.db.js';
+import type { MongoFilter, TSmartdataProjection, TSmartdataSort } from './classes.doc.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';
+
+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;
+}
+
+const queryPlanOptionKeys: readonly string[] = ['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: unknown): valueArg is Record<string, unknown> =>
+  typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg);
+
+const isPlainRecord = (valueArg: unknown): valueArg is Record<string, unknown> => {
+  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 = <T>(
+  optionsArg: ISmartdataQueryPlanOptions<T>,
+): IValidatedQueryPlanOptions<T> => {
+  const options: unknown = 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: unknown = 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 = (): SmartdataPersistenceError =>
+  new SmartdataPersistenceError('unsupported_operation', 'The engine returned an unreadable query plan.');
+
+const readCount = (valueArg: unknown): number => {
+  if (typeof valueArg !== 'number' || !Number.isSafeInteger(valueArg) || valueArg < 0) {
+    throw unreadablePlan();
+  }
+  return valueArg;
+};
+
+const readPlanString = (valueArg: unknown): string => {
+  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: unknown): ISmartdataQueryPlanStage[] => {
+  const root = isRecord(winningPlanArg) && winningPlanArg.stage === undefined && isRecord(winningPlanArg.queryPlan)
+    ? winningPlanArg.queryPlan
+    : winningPlanArg;
+  const stages: ISmartdataQueryPlanStage[] = [];
+  const visit = (nodeArg: unknown, depthArg: number): void => {
+    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: plugins.mongodb.Document): ISmartdataQueryPlan => {
+  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: SmartdataDb,
+  requestArg: IQueryPlanRequest,
+): Promise<ISmartdataQueryPlan> => {
+  const { signal } = requestArg;
+  signal?.throwIfAborted();
+  let failure: { readonly error: unknown } | undefined;
+  let explanation: plugins.mongodb.Document;
+  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);
+};

package/ts/nosqldb/classes.session.ts

@@ -11,6 +11,7 @@ import {
   SmartdataPersistenceError,
   createSmartdataTimeoutError,
   isMongoDeadlineError,
+  isMongoTransientTransactionError,
   normalizeDeadlineError,
   normalizeOrdinaryPersistenceError,
 } from './classes.persistence.js';
@@ -44,6 +45,45 @@ interface ISmartdataSessionBinding {
 /** How far a transaction had got when its session ended outside the callback's control. */
 type TSmartdataTransactionEnd = 'before_commit' | 'during_commit';
 
+/**
+ * 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';
+
+/** The commit outcome of every value a `withTransaction()` call rejected with. */
+const transactionCommitOutcomes = new WeakMap<object, TSmartdataTransactionCommitOutcome>();
+
+/**
+ * Records what `errorArg`, the rejection of a `withTransaction()` call, means
+ * for the commit, and returns it for the throw. A value several transactions
+ * rejected with keeps `unknown` once any of them may have committed. A
+ * primitive cannot be recorded.
+ */
+const rejectTransaction = (
+  errorArg: unknown,
+  outcomeArg: TSmartdataTransactionCommitOutcome,
+): unknown => {
+  if (
+    ((typeof errorArg === 'object' && errorArg !== null) || typeof errorArg === 'function')
+    && transactionCommitOutcomes.get(errorArg) !== 'unknown'
+  ) {
+    transactionCommitOutcomes.set(errorArg, outcomeArg);
+  }
+  return errorArg;
+};
+
+const commitOutcomeOfTransactionEnd = (
+  endArg: TSmartdataTransactionEnd,
+): TSmartdataTransactionCommitOutcome =>
+  endArg === 'during_commit' ? 'unknown' : 'not_committed';
+
 /**
  * The session of a transaction ended while it ran, for example through the
  * database's `close()`. The driver then returns the callback's result without
@@ -154,6 +194,30 @@ const normalizeTransactionOptions = (
   };
 };
 
+/** Everything `withTransaction()` refuses before a transaction starts. */
+const admitTransaction = (
+  sessionArg: SmartdataSession,
+  callbackArg: unknown,
+  optionsArg: ISmartdataTransactionOptions | undefined,
+): { binding: ISmartdataSessionBinding; timeoutMS?: number; signal?: AbortSignal } => {
+  if (typeof callbackArg !== 'function') {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      'SmartData transaction callback must be a function.',
+    );
+  }
+  const { timeoutMS, signal } = normalizeTransactionOptions(optionsArg);
+  const binding = resolveBinding(sessionArg);
+  if (binding.operationActive || binding.transactionActive) {
+    throw new SmartdataPersistenceError(
+      'unsupported_operation',
+      'Parallel or nested SmartData session operations are not supported.',
+    );
+  }
+  signal?.throwIfAborted();
+  return { binding, timeoutMS, signal };
+};
+
 const assertTransactionSucceeded = (bindingArg: ISmartdataSessionBinding): void => {
   if (bindingArg.transactionFailure) {
     throw bindingArg.transactionFailure.error;
@@ -161,6 +225,25 @@ const assertTransactionSucceeded = (bindingArg: ISmartdataSessionBinding): void
 };
 
 export 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`.
+   */
+  public static getCommitOutcome(errorArg: unknown): TSmartdataTransactionCommitOutcome | undefined {
+    return (typeof errorArg === 'object' && errorArg !== null) || typeof errorArg === 'function'
+      ? transactionCommitOutcomes.get(errorArg)
+      : undefined;
+  }
+
   /**
    * Runs `callbackArg` in a transaction, retrying it as the driver decides.
    *
@@ -192,26 +275,22 @@ export 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.
    */
   public async withTransaction<TResult>(
     callbackArg: (sessionArg: SmartdataSession) => Promise<TResult>,
     optionsArg?: ISmartdataTransactionOptions,
   ): Promise<TResult | undefined> {
-    if (typeof callbackArg !== 'function') {
-      throw new SmartdataPersistenceError(
-        'invalid_argument',
-        'SmartData transaction callback must be a function.',
-      );
-    }
-    const { timeoutMS, signal } = normalizeTransactionOptions(optionsArg);
-    const binding = resolveBinding(this);
-    if (binding.operationActive || binding.transactionActive) {
-      throw new SmartdataPersistenceError(
-        'unsupported_operation',
-        'Parallel or nested SmartData session operations are not supported.',
-      );
+    let admitted: ReturnType<typeof admitTransaction>;
+    try {
+      admitted = admitTransaction(this, callbackArg, optionsArg);
+    } catch (errorArg) {
+      throw rejectTransaction(errorArg, 'not_committed');
     }
-    signal?.throwIfAborted();
+    const { binding, timeoutMS, signal } = admitted;
     binding.transactionActive = true;
     binding.transactionTimeoutMS = timeoutMS;
     binding.transactionSignal = signal;
@@ -219,7 +298,8 @@ export class SmartdataSession {
     let callbackError: unknown;
     /** The signal or deadline interruption that failed the last attempt. */
     let attemptInterruption: { error: unknown } | undefined;
-    let sessionEndedError: SmartdataPersistenceError | undefined;
+    /** The session-ended rejection the last attempt failed with, and how far that transaction had got. */
+    let sessionEnded: { error: SmartdataPersistenceError; end: TSmartdataTransactionEnd } | undefined;
     const runAttempt = async () => {
       const attempt = Symbol('smartdataTransactionAttempt');
       binding.transactionAttempt = attempt;
@@ -260,11 +340,14 @@ export class SmartdataSession {
           if (binding.transactionEnded) {
             // The driver would commit or return the result on a session that is
             // being ended; the attempt fails instead, keeping the callback's error.
-            sessionEndedError = createTransactionSessionEndedError(
-              binding.transactionEnded,
-              callbackThrown?.error,
-            );
-            throw sessionEndedError;
+            sessionEnded = {
+              error: createTransactionSessionEndedError(
+                binding.transactionEnded,
+                callbackThrown?.error,
+              ),
+              end: binding.transactionEnded,
+            };
+            throw sessionEnded.error;
           }
           if (callbackReturned && activeOperation) {
             throw new SmartdataPersistenceError(
@@ -287,22 +370,25 @@ export class SmartdataSession {
         throw errorArg;
       }
     };
-    let result: TResult | undefined;
-    let transactionEnded: TSmartdataTransactionEnd | undefined;
-    try {
-      result = timeoutMS === undefined
-        ? await binding.rawSession.withTransaction(runAttempt)
-        : await binding.rawSession.withTransaction(runAttempt, { timeoutMS });
-      transactionEnded = binding.transactionEnded;
-    } catch (errorArg) {
+    /**
+     * What the call rejects with when the driver's `withTransaction()` rejected
+     * with `errorArg`, and whether the transaction could have committed. Once
+     * the last attempt's callback returned, the driver was committing: every
+     * error from there on leaves the commit outcome unknown, unless it states
+     * that the transaction was aborted. The driver starts another attempt only
+     * after such an error, so an earlier attempt never committed.
+     */
+    const settleTransactionRejection = (
+      errorArg: unknown,
+    ): { error: unknown; outcome: TSmartdataTransactionCommitOutcome } => {
       // The driver's closing abort replaces the attempt's error when it finds
       // the transaction already aborted, as a session that close() ended leaves
       // it; the interruption that failed the attempt keeps its rejection.
       if (attemptInterruption) {
-        throw normalizeDeadlineError(attemptInterruption.error);
+        return { error: normalizeDeadlineError(attemptInterruption.error), outcome: 'not_committed' };
       }
-      if (sessionEndedError) {
-        throw sessionEndedError;
+      if (sessionEnded) {
+        return { error: sessionEnded.error, outcome: commitOutcomeOfTransactionEnd(sessionEnded.end) };
       }
       if (
         binding.transactionEnded
@@ -310,26 +396,53 @@ export class SmartdataSession {
         && !isMongoDeadlineError(errorArg)
         && !(errorArg instanceof SmartdataPersistenceError && errorArg.code === 'timeout')
       ) {
-        throw createTransactionSessionEndedError(binding.transactionEnded, errorArg);
+        return {
+          error: createTransactionSessionEndedError(binding.transactionEnded, errorArg),
+          outcome: commitOutcomeOfTransactionEnd(binding.transactionEnded),
+        };
       }
       if (errorArg === callbackError) {
-        throw normalizeDeadlineError(errorArg);
+        return { error: normalizeDeadlineError(errorArg), outcome: 'not_committed' };
       }
+      const outcome: TSmartdataTransactionCommitOutcome =
+        binding.transactionCommitReached && !isMongoTransientTransactionError(errorArg)
+          ? 'unknown'
+          : 'not_committed';
       if (isMongoDeadlineError(errorArg)) {
-        throw createSmartdataTimeoutError(
-          binding.transactionCommitReached
-            ? 'SmartData transaction exceeded its client deadline during commit; the commit outcome is unknown.'
-            : 'SmartData transaction exceeded its client deadline before commit; nothing was committed.',
-          errorArg,
-        );
+        return {
+          error: createSmartdataTimeoutError(
+            outcome === 'unknown'
+              ? 'SmartData transaction exceeded its client deadline during commit; the commit outcome is unknown.'
+              : binding.transactionCommitReached
+                ? 'SmartData transaction exceeded its client deadline after the database aborted its commit; nothing was committed.'
+                : 'SmartData transaction exceeded its client deadline before commit; nothing was committed.',
+            errorArg,
+          ),
+          outcome,
+        };
       }
       if (binding.transactionUsesOrdinaryWrite) {
-        return normalizeOrdinaryPersistenceError(
-          errorArg,
-          'SmartData transaction conflicts with a unique index.',
-        );
+        try {
+          normalizeOrdinaryPersistenceError(
+            errorArg,
+            'SmartData transaction conflicts with a unique index.',
+          );
+        } catch (normalizedArg) {
+          return { error: normalizedArg, outcome };
+        }
       }
-      throw errorArg;
+      return { error: errorArg, outcome };
+    };
+    let result: TResult | undefined;
+    let transactionEnded: TSmartdataTransactionEnd | undefined;
+    try {
+      result = timeoutMS === undefined
+        ? await binding.rawSession.withTransaction(runAttempt)
+        : await binding.rawSession.withTransaction(runAttempt, { timeoutMS });
+      transactionEnded = binding.transactionEnded;
+    } catch (errorArg) {
+      const { error, outcome } = settleTransactionRejection(errorArg);
+      throw rejectTransaction(error, outcome);
     } finally {
       binding.transactionActive = false;
       binding.transactionTimeoutMS = undefined;
@@ -340,7 +453,10 @@ export class SmartdataSession {
       binding.transactionEnded = undefined;
     }
     if (transactionEnded) {
-      throw createTransactionSessionEndedError(transactionEnded);
+      throw rejectTransaction(
+        createTransactionSessionEndedError(transactionEnded),
+        commitOutcomeOfTransactionEnd(transactionEnded),
+      );
     }
     return result;
   }

package/ts/nosqldb/index.ts

@@ -45,6 +45,9 @@ export type {
   ISmartdataStoredDocumentEvidence, ISmartdataStoredEvidenceInspection,
   TSmartdataOrdinaryDocumentEvidence,
 } from './classes.storedinspection.js';
+export type {
+  ISmartdataQueryPlanOptions, ISmartdataQueryPlan, ISmartdataQueryPlanStage,
+} from './classes.queryplaninspection.js';
 export { SmartdataPersistenceError } from './classes.persistence.js';
 export type { TSmartdataPersistenceErrorCode } from './classes.persistence.js';
 export * from './classes.exactpersistence.js';