opusdev/vector-similarity-api

1import { type Document } from './bson';2import { MongoAPIError } from './error';3 4/** @public */5export const ExplainVerbosity = Object.freeze({6  queryPlanner: 'queryPlanner',7  queryPlannerExtended: 'queryPlannerExtended',8  executionStats: 'executionStats',9  allPlansExecution: 'allPlansExecution'10} as const);11 12/** @public */13export type ExplainVerbosity = string;14 15/**16 * For backwards compatibility, true is interpreted as "allPlansExecution"17 * and false as "queryPlanner".18 * @public19 */20export type ExplainVerbosityLike = ExplainVerbosity | boolean;21 22/** @public */23export interface ExplainCommandOptions {24  /** The explain verbosity for the command. */25  verbosity: ExplainVerbosity;26  /** The maxTimeMS setting for the command. */27  maxTimeMS?: number;28}29 30/**31 * @public32 *33 * When set, this configures an explain command.  Valid values are boolean (for legacy compatibility,34 * see {@link ExplainVerbosityLike}), a string containing the explain verbosity, or an object containing the verbosity and35 * an optional maxTimeMS.36 *37 * Examples of valid usage:38 *39 * ```typescript40 * collection.find({ name: 'john doe' }, { explain: true });41 * collection.find({ name: 'john doe' }, { explain: false });42 * collection.find({ name: 'john doe' }, { explain: 'queryPlanner' });43 * collection.find({ name: 'john doe' }, { explain: { verbosity: 'queryPlanner' } });44 * ```45 *46 * maxTimeMS can be configured to limit the amount of time the server47 * spends executing an explain by providing an object:48 *49 * ```typescript50 * // limits the `explain` command to no more than 2 seconds51 * collection.find({ name: 'john doe' }, {52 *   explain:  {53 *    verbosity: 'queryPlanner',54 *    maxTimeMS: 200055 *  }56 * });57 * ```58 */59export interface ExplainOptions {60  /** Specifies the verbosity mode for the explain output. */61  explain?: ExplainVerbosityLike | ExplainCommandOptions;62}63 64/** @internal */65export class Explain {66  readonly verbosity: ExplainVerbosity;67  readonly maxTimeMS?: number;68 69  private constructor(verbosity: ExplainVerbosityLike, maxTimeMS?: number) {70    if (typeof verbosity === 'boolean') {71      this.verbosity = verbosity72        ? ExplainVerbosity.allPlansExecution73        : ExplainVerbosity.queryPlanner;74    } else {75      this.verbosity = verbosity;76    }77 78    this.maxTimeMS = maxTimeMS;79  }80 81  static fromOptions({ explain }: ExplainOptions = {}): Explain | undefined {82    if (explain == null) return;83 84    if (typeof explain === 'boolean' || typeof explain === 'string') {85      return new Explain(explain);86    }87 88    const { verbosity, maxTimeMS } = explain;89    return new Explain(verbosity, maxTimeMS);90  }91}92 93export function validateExplainTimeoutOptions(options: Document, explain?: Explain) {94  const { maxTimeMS, timeoutMS } = options;95  if (timeoutMS != null && (maxTimeMS != null || explain?.maxTimeMS != null)) {96    throw new MongoAPIError('Cannot use maxTimeMS with timeoutMS for explain commands.');97  }98}99 100/**101 * Applies an explain to a given command.102 * @internal103 *104 * @param command - the command on which to apply the explain105 * @param options - the options containing the explain verbosity106 */107export function decorateWithExplain(108  command: Document,109  explain: Explain110): {111  explain: Document;112  verbosity: ExplainVerbosity;113  maxTimeMS?: number;114} {115  type ExplainCommand = ReturnType<typeof decorateWithExplain>;116  const { verbosity, maxTimeMS } = explain;117  const baseCommand: ExplainCommand = { explain: command, verbosity };118 119  if (typeof maxTimeMS === 'number') {120    baseCommand.maxTimeMS = maxTimeMS;121  }122 123  return baseCommand;124}125