@lossless.org/client 1.13.0 → 1.15.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/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';