@depup/mongodb 7.1.0-depup.0

package/src/operations/find.ts

@@ -0,0 +1,254 @@
+import type { Document } from '../bson';
+import { CursorResponse, ExplainedCursorResponse } from '../cmap/wire_protocol/responses';
+import { type AbstractCursorOptions, type CursorTimeoutMode } from '../cursor/abstract_cursor';
+import { MongoInvalidArgumentError } from '../error';
+import { type ExplainOptions } from '../explain';
+import type { ServerCommandOptions } from '../sdam/server';
+import { formatSort, type Sort } from '../sort';
+import { type TimeoutContext } from '../timeout';
+import { type MongoDBNamespace, normalizeHintField } from '../utils';
+import { type CollationOptions, CommandOperation, type CommandOperationOptions } from './command';
+import { Aspect, defineAspects, type Hint } from './operation';
+
+/**
+ * @public
+ */
+export interface FindOptions
+  extends Omit<CommandOperationOptions, 'writeConcern' | 'explain'>,
+    AbstractCursorOptions {
+  /** Sets the limit of documents returned in the query. */
+  limit?: number;
+  /** Set to sort the documents coming back from the query. Array of indexes, `[['a', 1]]` etc. */
+  sort?: Sort;
+  /** The fields to return in the query. Object of fields to either include or exclude (one of, not both), `{'a':1, 'b': 1}` **or** `{'a': 0, 'b': 0}` */
+  projection?: Document;
+  /** Set to skip N documents ahead in your query (useful for pagination). */
+  skip?: number;
+  /** Tell the query to use specific indexes in the query. Object of indexes to use, `{'_id':1}` */
+  hint?: Hint;
+  /** Specify if the cursor can timeout. */
+  timeout?: boolean;
+  /** Specify if the cursor is tailable. */
+  tailable?: boolean;
+  /** Specify if the cursor is a tailable-await cursor. Requires `tailable` to be true */
+  awaitData?: boolean;
+  /** Set the batchSize for the getMoreCommand when iterating over the query results. */
+  batchSize?: number;
+  /** If true, returns only the index keys in the resulting documents. */
+  returnKey?: boolean;
+  /** The inclusive lower bound for a specific index */
+  min?: Document;
+  /** The exclusive upper bound for a specific index */
+  max?: Document;
+  /** Number of milliseconds to wait before aborting the query. */
+  maxTimeMS?: number;
+  /** The maximum amount of time for the server to wait on new documents to satisfy a tailable cursor query. Requires `tailable` and `awaitData` to be true */
+  maxAwaitTimeMS?: number;
+  /** The server normally times out idle cursors after an inactivity period (10 minutes) to prevent excess memory use. Set this option to prevent that. */
+  noCursorTimeout?: boolean;
+  /** Specify collation (MongoDB 3.4 or higher) settings for update operation (see 3.4 documentation for available fields). */
+  collation?: CollationOptions;
+  /** Allows disk use for blocking sort operations exceeding 100MB memory. (MongoDB 3.2 or higher) */
+  allowDiskUse?: boolean;
+  /** Determines whether to close the cursor after the first batch. Defaults to false. */
+  singleBatch?: boolean;
+  /** For queries against a sharded collection, allows the command (or subsequent getMore commands) to return partial results, rather than an error, if one or more queried shards are unavailable. */
+  allowPartialResults?: boolean;
+  /** Determines whether to return the record identifier for each document. If true, adds a field $recordId to the returned documents. */
+  showRecordId?: boolean;
+  /** Map of parameter names and values that can be accessed using $$var (requires MongoDB 5.0). */
+  let?: Document;
+  /**
+   * Option to enable an optimized code path for queries looking for a particular range of `ts` values in the oplog. Requires `tailable` to be true.
+   * @deprecated Starting from MongoDB 4.4 this flag is not needed and will be ignored.
+   */
+  oplogReplay?: boolean;
+
+  /**
+   * Specifies the verbosity mode for the explain output.
+   * @deprecated This API is deprecated in favor of `collection.find().explain()`.
+   */
+  explain?: ExplainOptions['explain'];
+  /** @internal*/
+  timeoutMode?: CursorTimeoutMode;
+}
+
+/** @public */
+export type FindOneOptions = Omit<FindOptions, 'batchSize' | 'limit' | 'noCursorTimeout'>;
+
+/** @internal */
+export class FindOperation extends CommandOperation<CursorResponse> {
+  override SERVER_COMMAND_RESPONSE_TYPE = CursorResponse;
+
+  /**
+   * @remarks WriteConcern can still be present on the options because
+   * we inherit options from the client/db/collection.  The
+   * key must be present on the options in order to delete it.
+   * This allows typescript to delete the key but will
+   * not allow a writeConcern to be assigned as a property on options.
+   */
+  override options: FindOptions & { writeConcern?: never };
+  filter: Document;
+
+  constructor(ns: MongoDBNamespace, filter: Document = {}, options: FindOptions = {}) {
+    super(undefined, options);
+
+    this.options = { ...options };
+    delete this.options.writeConcern;
+    this.ns = ns;
+
+    if (typeof filter !== 'object' || Array.isArray(filter)) {
+      throw new MongoInvalidArgumentError('Query filter must be a plain object or ObjectId');
+    }
+
+    // special case passing in an ObjectId as a filter
+    this.filter = filter != null && filter._bsontype === 'ObjectId' ? { _id: filter } : filter;
+
+    this.SERVER_COMMAND_RESPONSE_TYPE = this.explain ? ExplainedCursorResponse : CursorResponse;
+  }
+
+  override get commandName() {
+    return 'find' as const;
+  }
+
+  override buildOptions(timeoutContext: TimeoutContext): ServerCommandOptions {
+    return {
+      ...this.options,
+      ...this.bsonOptions,
+      documentsReturnedIn: 'firstBatch',
+      session: this.session,
+      timeoutContext
+    };
+  }
+
+  override handleOk(
+    response: InstanceType<typeof this.SERVER_COMMAND_RESPONSE_TYPE>
+  ): CursorResponse {
+    return response;
+  }
+
+  override buildCommandDocument(): Document {
+    return makeFindCommand(this.ns, this.filter, this.options);
+  }
+}
+
+function makeFindCommand(ns: MongoDBNamespace, filter: Document, options: FindOptions): Document {
+  const findCommand: Document = {
+    find: ns.collection,
+    filter
+  };
+
+  if (options.sort) {
+    findCommand.sort = formatSort(options.sort);
+  }
+
+  if (options.projection) {
+    let projection = options.projection;
+    if (projection && Array.isArray(projection)) {
+      projection = projection.length
+        ? projection.reduce((result, field) => {
+            result[field] = 1;
+            return result;
+          }, {})
+        : { _id: 1 };
+    }
+
+    findCommand.projection = projection;
+  }
+
+  if (options.hint) {
+    findCommand.hint = normalizeHintField(options.hint);
+  }
+
+  if (typeof options.skip === 'number') {
+    findCommand.skip = options.skip;
+  }
+
+  if (typeof options.limit === 'number') {
+    if (options.limit < 0) {
+      findCommand.limit = -options.limit;
+      findCommand.singleBatch = true;
+    } else {
+      findCommand.limit = options.limit;
+    }
+  }
+
+  if (typeof options.batchSize === 'number') {
+    if (options.batchSize < 0) {
+      findCommand.limit = -options.batchSize;
+    } else {
+      if (options.batchSize === options.limit) {
+        // Spec dictates that if these are equal the batchSize should be one more than the
+        // limit to avoid leaving the cursor open.
+        findCommand.batchSize = options.batchSize + 1;
+      } else {
+        findCommand.batchSize = options.batchSize;
+      }
+    }
+  }
+
+  if (typeof options.singleBatch === 'boolean') {
+    findCommand.singleBatch = options.singleBatch;
+  }
+
+  // we check for undefined specifically here to allow falsy values
+  // eslint-disable-next-line no-restricted-syntax
+  if (options.comment !== undefined) {
+    findCommand.comment = options.comment;
+  }
+
+  if (options.max) {
+    findCommand.max = options.max;
+  }
+
+  if (options.min) {
+    findCommand.min = options.min;
+  }
+
+  if (typeof options.returnKey === 'boolean') {
+    findCommand.returnKey = options.returnKey;
+  }
+
+  if (typeof options.showRecordId === 'boolean') {
+    findCommand.showRecordId = options.showRecordId;
+  }
+
+  if (typeof options.tailable === 'boolean') {
+    findCommand.tailable = options.tailable;
+  }
+
+  if (typeof options.oplogReplay === 'boolean') {
+    findCommand.oplogReplay = options.oplogReplay;
+  }
+
+  if (typeof options.timeout === 'boolean') {
+    findCommand.noCursorTimeout = !options.timeout;
+  } else if (typeof options.noCursorTimeout === 'boolean') {
+    findCommand.noCursorTimeout = options.noCursorTimeout;
+  }
+
+  if (typeof options.awaitData === 'boolean') {
+    findCommand.awaitData = options.awaitData;
+  }
+
+  if (typeof options.allowPartialResults === 'boolean') {
+    findCommand.allowPartialResults = options.allowPartialResults;
+  }
+  if (typeof options.allowDiskUse === 'boolean') {
+    findCommand.allowDiskUse = options.allowDiskUse;
+  }
+
+  if (options.let) {
+    findCommand.let = options.let;
+  }
+
+  return findCommand;
+}
+
+defineAspects(FindOperation, [
+  Aspect.READ_OPERATION,
+  Aspect.RETRYABLE,
+  Aspect.EXPLAINABLE,
+  Aspect.CURSOR_CREATING,
+  Aspect.SUPPORTS_RAW_DATA
+]);

package/src/operations/find_and_modify.ts

@@ -0,0 +1,319 @@
+import { type Connection } from '..';
+import type { Document } from '../bson';
+import { MongoDBResponse } from '../cmap/wire_protocol/responses';
+import type { Collection } from '../collection';
+import { MongoCompatibilityError, MongoInvalidArgumentError } from '../error';
+import { ReadPreference } from '../read_preference';
+import type { ClientSession } from '../sessions';
+import { formatSort, type Sort, type SortForCmd } from '../sort';
+import { decorateWithCollation, hasAtomicOperators, maxWireVersion } from '../utils';
+import { type WriteConcern, type WriteConcernSettings } from '../write_concern';
+import { CommandOperation, type CommandOperationOptions } from './command';
+import { Aspect, defineAspects } from './operation';
+
+/** @public */
+export const ReturnDocument = Object.freeze({
+  BEFORE: 'before',
+  AFTER: 'after'
+} as const);
+
+/** @public */
+export type ReturnDocument = (typeof ReturnDocument)[keyof typeof ReturnDocument];
+
+/** @public */
+export interface FindOneAndDeleteOptions extends CommandOperationOptions {
+  /** An optional hint for query optimization. See the {@link https://www.mongodb.com/docs/manual/reference/command/update/#update-command-hint|update command} reference for more information.*/
+  hint?: Document;
+  /** Limits the fields to return for all matching documents. */
+  projection?: Document;
+  /** Determines which document the operation modifies if the query selects multiple documents. */
+  sort?: Sort;
+  /** Map of parameter names and values that can be accessed using $$var (requires MongoDB 5.0). */
+  let?: Document;
+  /**
+   * Return the ModifyResult instead of the modified document. Defaults to false
+   */
+  includeResultMetadata?: boolean;
+}
+
+/** @public */
+export interface FindOneAndReplaceOptions extends CommandOperationOptions {
+  /** Allow driver to bypass schema validation. */
+  bypassDocumentValidation?: boolean;
+  /** An optional hint for query optimization. See the {@link https://www.mongodb.com/docs/manual/reference/command/update/#update-command-hint|update command} reference for more information.*/
+  hint?: Document;
+  /** Limits the fields to return for all matching documents. */
+  projection?: Document;
+  /** When set to 'after', returns the updated document rather than the original. The default is 'before'.  */
+  returnDocument?: ReturnDocument;
+  /** Determines which document the operation modifies if the query selects multiple documents. */
+  sort?: Sort;
+  /** Upsert the document if it does not exist. */
+  upsert?: boolean;
+  /** Map of parameter names and values that can be accessed using $$var (requires MongoDB 5.0). */
+  let?: Document;
+  /**
+   * Return the ModifyResult instead of the modified document. Defaults to false
+   */
+  includeResultMetadata?: boolean;
+}
+
+/** @public */
+export interface FindOneAndUpdateOptions extends CommandOperationOptions {
+  /** Optional list of array filters referenced in filtered positional operators */
+  arrayFilters?: Document[];
+  /** Allow driver to bypass schema validation. */
+  bypassDocumentValidation?: boolean;
+  /** An optional hint for query optimization. See the {@link https://www.mongodb.com/docs/manual/reference/command/update/#update-command-hint|update command} reference for more information.*/
+  hint?: Document;
+  /** Limits the fields to return for all matching documents. */
+  projection?: Document;
+  /** When set to 'after', returns the updated document rather than the original. The default is 'before'.  */
+  returnDocument?: ReturnDocument;
+  /** Determines which document the operation modifies if the query selects multiple documents. */
+  sort?: Sort;
+  /** Upsert the document if it does not exist. */
+  upsert?: boolean;
+  /** Map of parameter names and values that can be accessed using $$var (requires MongoDB 5.0). */
+  let?: Document;
+  /**
+   * Return the ModifyResult instead of the modified document. Defaults to false
+   */
+  includeResultMetadata?: boolean;
+}
+
+/** @internal */
+interface FindAndModifyCmdBase {
+  remove: boolean;
+  new: boolean;
+  upsert: boolean;
+  update?: Document;
+  sort?: SortForCmd;
+  fields?: Document;
+  bypassDocumentValidation?: boolean;
+  arrayFilters?: Document[];
+  maxTimeMS?: number;
+  let?: Document;
+  writeConcern?: WriteConcern | WriteConcernSettings;
+  /**
+   * Comment to apply to the operation.
+   *
+   * In server versions pre-4.4, 'comment' must be string.  A server
+   * error will be thrown if any other type is provided.
+   *
+   * In server versions 4.4 and above, 'comment' can be any valid BSON type.
+   */
+  comment?: unknown;
+}
+
+function configureFindAndModifyCmdBaseUpdateOpts(
+  cmdBase: FindAndModifyCmdBase,
+  options: FindOneAndReplaceOptions | FindOneAndUpdateOptions
+): FindAndModifyCmdBase {
+  cmdBase.new = options.returnDocument === ReturnDocument.AFTER;
+  cmdBase.upsert = options.upsert === true;
+
+  if (options.bypassDocumentValidation === true) {
+    cmdBase.bypassDocumentValidation = options.bypassDocumentValidation;
+  }
+  return cmdBase;
+}
+
+/** @internal */
+export class FindAndModifyOperation extends CommandOperation<Document> {
+  override SERVER_COMMAND_RESPONSE_TYPE = MongoDBResponse;
+  override options: FindOneAndReplaceOptions | FindOneAndUpdateOptions | FindOneAndDeleteOptions;
+  collection: Collection;
+  query: Document;
+  doc?: Document;
+
+  constructor(
+    collection: Collection,
+    query: Document,
+    options: FindOneAndReplaceOptions | FindOneAndUpdateOptions | FindOneAndDeleteOptions
+  ) {
+    super(collection, options);
+    this.options = options;
+    // force primary read preference
+    this.readPreference = ReadPreference.primary;
+
+    this.collection = collection;
+    this.query = query;
+  }
+
+  override get commandName() {
+    return 'findAndModify' as const;
+  }
+
+  override buildCommandDocument(
+    connection: Connection,
+    _session?: ClientSession
+  ): Document & FindAndModifyCmdBase {
+    const options = this.options;
+    const command: Document & FindAndModifyCmdBase = {
+      findAndModify: this.collection.collectionName,
+      query: this.query,
+      remove: false,
+      new: false,
+      upsert: false
+    };
+
+    options.includeResultMetadata ??= false;
+
+    const sort = formatSort(options.sort);
+    if (sort) {
+      command.sort = sort;
+    }
+
+    if (options.projection) {
+      command.fields = options.projection;
+    }
+
+    if (options.maxTimeMS) {
+      command.maxTimeMS = options.maxTimeMS;
+    }
+
+    // Decorate the findAndModify command with the write Concern
+    if (options.writeConcern) {
+      command.writeConcern = options.writeConcern;
+    }
+
+    if (options.let) {
+      command.let = options.let;
+    }
+
+    // we check for undefined specifically here to allow falsy values
+    // eslint-disable-next-line no-restricted-syntax
+    if (options.comment !== undefined) {
+      command.comment = options.comment;
+    }
+
+    decorateWithCollation(command, options);
+
+    if (options.hint) {
+      const unacknowledgedWrite = this.writeConcern?.w === 0;
+      if (unacknowledgedWrite && maxWireVersion(connection) < 9) {
+        throw new MongoCompatibilityError(
+          'hint for the findAndModify command is only supported on MongoDB 4.4+'
+        );
+      }
+
+      command.hint = options.hint;
+    }
+
+    return command;
+  }
+
+  override handleOk(response: InstanceType<typeof this.SERVER_COMMAND_RESPONSE_TYPE>): Document {
+    const result = super.handleOk(response);
+    return this.options.includeResultMetadata ? result : (result.value ?? null);
+  }
+}
+
+/** @internal */
+export class FindOneAndDeleteOperation extends FindAndModifyOperation {
+  constructor(collection: Collection, filter: Document, options: FindOneAndDeleteOptions) {
+    // Basic validation
+    if (filter == null || typeof filter !== 'object') {
+      throw new MongoInvalidArgumentError('Argument "filter" must be an object');
+    }
+
+    super(collection, filter, options);
+  }
+
+  override buildCommandDocument(
+    connection: Connection,
+    session?: ClientSession
+  ): Document & FindAndModifyCmdBase {
+    const document = super.buildCommandDocument(connection, session);
+    document.remove = true;
+    return document;
+  }
+}
+
+/** @internal */
+export class FindOneAndReplaceOperation extends FindAndModifyOperation {
+  private replacement: Document;
+  constructor(
+    collection: Collection,
+    filter: Document,
+    replacement: Document,
+    options: FindOneAndReplaceOptions
+  ) {
+    if (filter == null || typeof filter !== 'object') {
+      throw new MongoInvalidArgumentError('Argument "filter" must be an object');
+    }
+
+    if (replacement == null || typeof replacement !== 'object') {
+      throw new MongoInvalidArgumentError('Argument "replacement" must be an object');
+    }
+
+    if (hasAtomicOperators(replacement)) {
+      throw new MongoInvalidArgumentError('Replacement document must not contain atomic operators');
+    }
+
+    super(collection, filter, options);
+    this.replacement = replacement;
+  }
+
+  override buildCommandDocument(
+    connection: Connection,
+    session?: ClientSession
+  ): Document & FindAndModifyCmdBase {
+    const document = super.buildCommandDocument(connection, session);
+    document.update = this.replacement;
+    configureFindAndModifyCmdBaseUpdateOpts(document, this.options);
+    return document;
+  }
+}
+
+/** @internal */
+export class FindOneAndUpdateOperation extends FindAndModifyOperation {
+  override options: FindOneAndUpdateOptions;
+
+  private update: Document;
+  constructor(
+    collection: Collection,
+    filter: Document,
+    update: Document,
+    options: FindOneAndUpdateOptions
+  ) {
+    if (filter == null || typeof filter !== 'object') {
+      throw new MongoInvalidArgumentError('Argument "filter" must be an object');
+    }
+
+    if (update == null || typeof update !== 'object') {
+      throw new MongoInvalidArgumentError('Argument "update" must be an object');
+    }
+
+    if (!hasAtomicOperators(update, options)) {
+      throw new MongoInvalidArgumentError('Update document requires atomic operators');
+    }
+
+    super(collection, filter, options);
+    this.update = update;
+    this.options = options;
+  }
+
+  override buildCommandDocument(
+    connection: Connection,
+    session?: ClientSession
+  ): Document & FindAndModifyCmdBase {
+    const document = super.buildCommandDocument(connection, session);
+    document.update = this.update;
+    configureFindAndModifyCmdBaseUpdateOpts(document, this.options);
+
+    if (this.options.arrayFilters) {
+      document.arrayFilters = this.options.arrayFilters;
+    }
+
+    return document;
+  }
+}
+
+defineAspects(FindAndModifyOperation, [
+  Aspect.WRITE_OPERATION,
+  Aspect.RETRYABLE,
+  Aspect.EXPLAINABLE,
+  Aspect.SUPPORTS_RAW_DATA
+]);

package/src/operations/get_more.ts

@@ -0,0 +1,108 @@
+import type { Document, Long } from '../bson';
+import { type Connection } from '../cmap/connection';
+import { CursorResponse } from '../cmap/wire_protocol/responses';
+import { MongoRuntimeError } from '../error';
+import type { Server, ServerCommandOptions } from '../sdam/server';
+import { type TimeoutContext } from '../timeout';
+import { maxWireVersion, type MongoDBNamespace } from '../utils';
+import { AbstractOperation, Aspect, defineAspects, type OperationOptions } from './operation';
+
+/** @internal */
+export interface GetMoreOptions extends OperationOptions {
+  /** Set the batchSize for the getMoreCommand when iterating over the query results. */
+  batchSize?: number;
+  /**
+   * Comment to apply to the operation.
+   *
+   * getMore only supports 'comment' in server versions 4.4 and above.
+   */
+  comment?: unknown;
+  /** Number of milliseconds to wait before aborting the query. */
+  maxTimeMS?: number;
+  /** TODO(NODE-4413): Address bug with maxAwaitTimeMS not being passed in from the cursor correctly */
+  maxAwaitTimeMS?: number;
+}
+
+/**
+ * GetMore command: https://www.mongodb.com/docs/manual/reference/command/getMore/
+ * @internal
+ */
+export interface GetMoreCommand {
+  getMore: Long;
+  collection: string;
+  batchSize?: number;
+  maxTimeMS?: number;
+  /** Only supported on wire versions 10 or greater */
+  comment?: unknown;
+}
+
+/** @internal */
+export class GetMoreOperation extends AbstractOperation<CursorResponse> {
+  override SERVER_COMMAND_RESPONSE_TYPE = CursorResponse;
+  cursorId: Long;
+  override options: GetMoreOptions;
+
+  constructor(ns: MongoDBNamespace, cursorId: Long, server: Server, options: GetMoreOptions) {
+    super(options);
+
+    this.options = options;
+    this.ns = ns;
+    this.cursorId = cursorId;
+    this.server = server;
+  }
+
+  override get commandName() {
+    return 'getMore' as const;
+  }
+
+  override buildCommand(connection: Connection): Document {
+    if (this.cursorId == null || this.cursorId.isZero()) {
+      throw new MongoRuntimeError('Unable to iterate cursor with no id');
+    }
+
+    const collection = this.ns.collection;
+    if (collection == null) {
+      // Cursors should have adopted the namespace returned by MongoDB
+      // which should always defined a collection name (even a pseudo one, ex. db.aggregate())
+      throw new MongoRuntimeError('A collection name must be determined before getMore');
+    }
+
+    const getMoreCmd: GetMoreCommand = {
+      getMore: this.cursorId,
+      collection
+    };
+
+    if (typeof this.options.batchSize === 'number') {
+      getMoreCmd.batchSize = Math.abs(this.options.batchSize);
+    }
+
+    if (typeof this.options.maxAwaitTimeMS === 'number') {
+      getMoreCmd.maxTimeMS = this.options.maxAwaitTimeMS;
+    }
+
+    // we check for undefined specifically here to allow falsy values
+    // eslint-disable-next-line no-restricted-syntax
+    if (this.options.comment !== undefined && maxWireVersion(connection) >= 9) {
+      getMoreCmd.comment = this.options.comment;
+    }
+
+    return getMoreCmd;
+  }
+
+  override buildOptions(timeoutContext: TimeoutContext): ServerCommandOptions {
+    return {
+      returnFieldSelector: null,
+      documentsReturnedIn: 'nextBatch',
+      timeoutContext,
+      ...this.options
+    };
+  }
+
+  override handleOk(
+    response: InstanceType<typeof this.SERVER_COMMAND_RESPONSE_TYPE>
+  ): CursorResponse {
+    return response;
+  }
+}
+
+defineAspects(GetMoreOperation, [Aspect.READ_OPERATION, Aspect.MUST_SELECT_SAME_SERVER]);