@depup/mongodb 7.1.0-depup.0

package/src/operations/command.ts

@@ -0,0 +1,171 @@
+import { type Connection } from '..';
+import type { BSONSerializeOptions, Document } from '../bson';
+import { MIN_SUPPORTED_RAW_DATA_WIRE_VERSION } from '../cmap/wire_protocol/constants';
+import { MongoInvalidArgumentError } from '../error';
+import {
+  decorateWithExplain,
+  Explain,
+  type ExplainOptions,
+  validateExplainTimeoutOptions
+} from '../explain';
+import { ReadConcern } from '../read_concern';
+import type { ReadPreference } from '../read_preference';
+import type { ServerCommandOptions } from '../sdam/server';
+import type { ClientSession } from '../sessions';
+import { type TimeoutContext } from '../timeout';
+import { commandSupportsReadConcern, maxWireVersion, MongoDBNamespace } from '../utils';
+import { WriteConcern, type WriteConcernOptions } from '../write_concern';
+import type { ReadConcernLike } from './../read_concern';
+import { AbstractOperation, Aspect, type OperationOptions } from './operation';
+
+/** @public */
+export interface CollationOptions {
+  locale: string;
+  caseLevel?: boolean;
+  caseFirst?: string;
+  strength?: number;
+  numericOrdering?: boolean;
+  alternate?: string;
+  maxVariable?: string;
+  backwards?: boolean;
+  normalization?: boolean;
+}
+
+/** @public */
+export interface CommandOperationOptions
+  extends OperationOptions,
+    WriteConcernOptions,
+    ExplainOptions {
+  /** Specify a read concern and level for the collection. (only MongoDB 3.2 or higher supported) */
+  readConcern?: ReadConcernLike;
+  /** Collation */
+  collation?: CollationOptions;
+  /**
+   * maxTimeMS is a server-side time limit in milliseconds for processing an operation.
+   */
+  maxTimeMS?: number;
+  /**
+   * 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;
+  // Admin command overrides.
+  dbName?: string;
+  authdb?: string;
+
+  /**
+   * Used when the command needs to grant access to the underlying namespaces for time series collections.
+   * Only available on server versions 8.2 and above and is not meant for public use.
+   * @internal
+   * @sinceServerVersion 8.2
+   **/
+  rawData?: boolean;
+}
+
+/** @internal */
+export interface OperationParent {
+  s: { namespace: MongoDBNamespace };
+  readConcern?: ReadConcern;
+  writeConcern?: WriteConcern;
+  readPreference?: ReadPreference;
+  bsonOptions?: BSONSerializeOptions;
+  timeoutMS?: number;
+}
+
+/** @internal */
+export abstract class CommandOperation<T> extends AbstractOperation<T> {
+  override options: CommandOperationOptions;
+  readConcern?: ReadConcern;
+  writeConcern?: WriteConcern;
+  explain?: Explain;
+
+  constructor(parent?: OperationParent, options?: CommandOperationOptions) {
+    super(options);
+    this.options = options ?? {};
+
+    // NOTE: this was explicitly added for the add/remove user operations, it's likely
+    //       something we'd want to reconsider. Perhaps those commands can use `Admin`
+    //       as a parent?
+    const dbNameOverride = options?.dbName || options?.authdb;
+    if (dbNameOverride) {
+      this.ns = new MongoDBNamespace(dbNameOverride, '$cmd');
+    } else {
+      this.ns = parent
+        ? parent.s.namespace.withCollection('$cmd')
+        : new MongoDBNamespace('admin', '$cmd');
+    }
+
+    this.readConcern = ReadConcern.fromOptions(options);
+    this.writeConcern = WriteConcern.fromOptions(options);
+
+    if (this.hasAspect(Aspect.EXPLAINABLE)) {
+      this.explain = Explain.fromOptions(options);
+      if (this.explain) validateExplainTimeoutOptions(this.options, this.explain);
+    } else if (options?.explain != null) {
+      throw new MongoInvalidArgumentError(`Option "explain" is not supported on this command`);
+    }
+  }
+
+  override get canRetryWrite(): boolean {
+    if (this.hasAspect(Aspect.EXPLAINABLE)) {
+      return this.explain == null;
+    }
+    return super.canRetryWrite;
+  }
+
+  abstract buildCommandDocument(connection: Connection, session?: ClientSession): Document;
+
+  override buildOptions(timeoutContext: TimeoutContext): ServerCommandOptions {
+    return {
+      ...this.options,
+      ...this.bsonOptions,
+      timeoutContext,
+      readPreference: this.readPreference,
+      session: this.session
+    };
+  }
+
+  override buildCommand(connection: Connection, session?: ClientSession): Document {
+    const command = this.buildCommandDocument(connection, session);
+
+    const inTransaction = this.session && this.session.inTransaction();
+
+    if (this.readConcern && commandSupportsReadConcern(command) && !inTransaction) {
+      Object.assign(command, { readConcern: this.readConcern });
+    }
+
+    if (this.writeConcern && this.hasAspect(Aspect.WRITE_OPERATION) && !inTransaction) {
+      WriteConcern.apply(command, this.writeConcern);
+    }
+
+    if (
+      this.options.collation &&
+      typeof this.options.collation === 'object' &&
+      !this.hasAspect(Aspect.SKIP_COLLATION)
+    ) {
+      Object.assign(command, { collation: this.options.collation });
+    }
+
+    if (typeof this.options.maxTimeMS === 'number') {
+      command.maxTimeMS = this.options.maxTimeMS;
+    }
+
+    if (
+      this.options.rawData != null &&
+      this.hasAspect(Aspect.SUPPORTS_RAW_DATA) &&
+      maxWireVersion(connection) >= MIN_SUPPORTED_RAW_DATA_WIRE_VERSION
+    ) {
+      command.rawData = this.options.rawData;
+    }
+
+    if (this.hasAspect(Aspect.EXPLAINABLE) && this.explain) {
+      return decorateWithExplain(command, this.explain);
+    }
+
+    return command;
+  }
+}

package/src/operations/count.ts

@@ -0,0 +1,74 @@
+import { type Connection } from '..';
+import type { Document } from '../bson';
+import { MongoDBResponse } from '../cmap/wire_protocol/responses';
+import type { Collection } from '../collection';
+import type { ClientSession } from '../sessions';
+import type { MongoDBNamespace } from '../utils';
+import { CommandOperation, type CommandOperationOptions } from './command';
+import { Aspect, defineAspects } from './operation';
+
+/** @public */
+export interface CountOptions extends CommandOperationOptions {
+  /** The number of documents to skip. */
+  skip?: number;
+  /** The maximum amounts to count before aborting. */
+  limit?: number;
+  /**
+   * Number of milliseconds to wait before aborting the query.
+   */
+  maxTimeMS?: number;
+  /** An index name hint for the query. */
+  hint?: string | Document;
+}
+
+/** @internal */
+export class CountOperation extends CommandOperation<number> {
+  override SERVER_COMMAND_RESPONSE_TYPE = MongoDBResponse;
+  override options: CountOptions;
+  collectionName?: string;
+  query: Document;
+
+  constructor(namespace: MongoDBNamespace, filter: Document, options: CountOptions) {
+    super({ s: { namespace: namespace } } as unknown as Collection, options);
+
+    this.options = options;
+    this.collectionName = namespace.collection;
+    this.query = filter;
+  }
+
+  override get commandName() {
+    return 'count' as const;
+  }
+
+  override buildCommandDocument(_connection: Connection, _session?: ClientSession): Document {
+    const options = this.options;
+    const cmd: Document = {
+      count: this.collectionName,
+      query: this.query
+    };
+
+    if (typeof options.limit === 'number') {
+      cmd.limit = options.limit;
+    }
+
+    if (typeof options.skip === 'number') {
+      cmd.skip = options.skip;
+    }
+
+    if (options.hint != null) {
+      cmd.hint = options.hint;
+    }
+
+    if (typeof options.maxTimeMS === 'number') {
+      cmd.maxTimeMS = options.maxTimeMS;
+    }
+
+    return cmd;
+  }
+
+  override handleOk(response: InstanceType<typeof this.SERVER_COMMAND_RESPONSE_TYPE>): number {
+    return response.getNumber('n') ?? 0;
+  }
+}
+
+defineAspects(CountOperation, [Aspect.READ_OPERATION, Aspect.RETRYABLE, Aspect.SUPPORTS_RAW_DATA]);

package/src/operations/create_collection.ts

@@ -0,0 +1,218 @@
+import { type Connection } from '..';
+import type { Document } from '../bson';
+import {
+  MIN_SUPPORTED_QE_SERVER_VERSION,
+  MIN_SUPPORTED_QE_WIRE_VERSION
+} from '../cmap/wire_protocol/constants';
+import { MongoDBResponse } from '../cmap/wire_protocol/responses';
+import { Collection } from '../collection';
+import type { Db } from '../db';
+import { MongoCompatibilityError } from '../error';
+import type { PkFactory } from '../mongo_client';
+import type { ClientSession } from '../sessions';
+import { TimeoutContext } from '../timeout';
+import { maxWireVersion } from '../utils';
+import { CommandOperation, type CommandOperationOptions } from './command';
+import { executeOperation } from './execute_operation';
+import { CreateIndexesOperation } from './indexes';
+import { Aspect, defineAspects } from './operation';
+
+const ILLEGAL_COMMAND_FIELDS = new Set([
+  'w',
+  'wtimeout',
+  'timeoutMS',
+  'j',
+  'fsync',
+  'pkFactory',
+  'raw',
+  'readPreference',
+  'session',
+  'readConcern',
+  'writeConcern',
+  'raw',
+  'fieldsAsRaw',
+  'useBigInt64',
+  'promoteLongs',
+  'promoteValues',
+  'promoteBuffers',
+  'bsonRegExp',
+  'serializeFunctions',
+  'ignoreUndefined',
+  'enableUtf8Validation'
+]);
+
+/** @public
+ * Configuration options for timeseries collections
+ * @see https://www.mongodb.com/docs/manual/core/timeseries-collections/
+ */
+export interface TimeSeriesCollectionOptions extends Document {
+  timeField: string;
+  metaField?: string;
+  granularity?: 'seconds' | 'minutes' | 'hours' | string;
+  bucketMaxSpanSeconds?: number;
+  bucketRoundingSeconds?: number;
+}
+
+/** @public
+ * Configuration options for clustered collections
+ * @see https://www.mongodb.com/docs/manual/core/clustered-collections/
+ */
+export interface ClusteredCollectionOptions extends Document {
+  name?: string;
+  key: Document;
+  unique: boolean;
+}
+
+/** @public */
+export interface CreateCollectionOptions extends Omit<CommandOperationOptions, 'rawData'> {
+  /** Create a capped collection */
+  capped?: boolean;
+  /** The size of the capped collection in bytes */
+  size?: number;
+  /** The maximum number of documents in the capped collection */
+  max?: number;
+  /** Available for the MMAPv1 storage engine only to set the usePowerOf2Sizes and the noPadding flag */
+  flags?: number;
+  /** Allows users to specify configuration to the storage engine on a per-collection basis when creating a collection */
+  storageEngine?: Document;
+  /** Allows users to specify validation rules or expressions for the collection. For more information, see Document Validation */
+  validator?: Document;
+  /** Determines how strictly MongoDB applies the validation rules to existing documents during an update */
+  validationLevel?: string;
+  /** Determines whether to error on invalid documents or just warn about the violations but allow invalid documents to be inserted */
+  validationAction?: string;
+  /** Allows users to specify a default configuration for indexes when creating a collection */
+  indexOptionDefaults?: Document;
+  /** The name of the source collection or view from which to create the view. The name is not the full namespace of the collection or view (i.e., does not include the database name and implies the same database as the view to create) */
+  viewOn?: string;
+  /** An array that consists of the aggregation pipeline stage. Creates the view by applying the specified pipeline to the viewOn collection or view */
+  pipeline?: Document[];
+  /** A primary key factory function for generation of custom _id keys. */
+  pkFactory?: PkFactory;
+  /** A document specifying configuration options for timeseries collections. */
+  timeseries?: TimeSeriesCollectionOptions;
+  /** A document specifying configuration options for clustered collections. For MongoDB 5.3 and above. */
+  clusteredIndex?: ClusteredCollectionOptions;
+  /** The number of seconds after which a document in a timeseries or clustered collection expires. */
+  expireAfterSeconds?: number;
+  /** @experimental */
+  encryptedFields?: Document;
+  /**
+   * If set, enables pre-update and post-update document events to be included for any
+   * change streams that listen on this collection.
+   */
+  changeStreamPreAndPostImages?: { enabled: boolean };
+}
+
+/* @internal */
+const INVALID_QE_VERSION =
+  'Driver support of Queryable Encryption is incompatible with server. Upgrade server to use Queryable Encryption.';
+
+/** @internal */
+export class CreateCollectionOperation extends CommandOperation<Collection> {
+  override SERVER_COMMAND_RESPONSE_TYPE = MongoDBResponse;
+  override options: CreateCollectionOptions;
+  db: Db;
+  name: string;
+
+  constructor(db: Db, name: string, options: CreateCollectionOptions = {}) {
+    super(db, options);
+
+    this.options = options;
+    this.db = db;
+    this.name = name;
+  }
+
+  override get commandName() {
+    return 'create' as const;
+  }
+
+  override buildCommandDocument(_connection: Connection, _session?: ClientSession): Document {
+    const isOptionValid = ([k, v]: [k: string, v: unknown]) =>
+      v != null && typeof v !== 'function' && !ILLEGAL_COMMAND_FIELDS.has(k);
+    return {
+      create: this.name,
+      ...Object.fromEntries(Object.entries(this.options).filter(isOptionValid))
+    };
+  }
+
+  override handleOk(
+    _response: InstanceType<typeof this.SERVER_COMMAND_RESPONSE_TYPE>
+  ): Collection<Document> {
+    return new Collection(this.db, this.name, this.options);
+  }
+}
+
+export async function createCollections<TSchema extends Document>(
+  db: Db,
+  name: string,
+  options: CreateCollectionOptions
+): Promise<Collection<TSchema>> {
+  const timeoutContext = TimeoutContext.create({
+    session: options.session,
+    serverSelectionTimeoutMS: db.client.s.options.serverSelectionTimeoutMS,
+    waitQueueTimeoutMS: db.client.s.options.waitQueueTimeoutMS,
+    timeoutMS: options.timeoutMS
+  });
+
+  const encryptedFields: Document | undefined =
+    options.encryptedFields ??
+    db.client.s.options.autoEncryption?.encryptedFieldsMap?.[`${db.databaseName}.${name}`];
+
+  if (encryptedFields) {
+    class CreateSupportingFLEv2CollectionOperation extends CreateCollectionOperation {
+      override buildCommandDocument(connection: Connection, session?: ClientSession): Document {
+        if (
+          !connection.description.loadBalanced &&
+          maxWireVersion(connection) < MIN_SUPPORTED_QE_WIRE_VERSION
+        ) {
+          throw new MongoCompatibilityError(
+            `${INVALID_QE_VERSION} The minimum server version required is ${MIN_SUPPORTED_QE_SERVER_VERSION}`
+          );
+        }
+
+        return super.buildCommandDocument(connection, session);
+      }
+    }
+
+    // Create auxilliary collections for queryable encryption support.
+    const escCollection = encryptedFields.escCollection ?? `enxcol_.${name}.esc`;
+    const ecocCollection = encryptedFields.ecocCollection ?? `enxcol_.${name}.ecoc`;
+
+    for (const collectionName of [escCollection, ecocCollection]) {
+      const createOp = new CreateSupportingFLEv2CollectionOperation(db, collectionName, {
+        clusteredIndex: {
+          key: { _id: 1 },
+          unique: true
+        },
+        session: options.session
+      });
+      await executeOperation(db.client, createOp, timeoutContext);
+    }
+
+    if (!options.encryptedFields) {
+      options = { ...options, encryptedFields };
+    }
+  }
+
+  const coll = await executeOperation(
+    db.client,
+    new CreateCollectionOperation(db, name, options),
+    timeoutContext
+  );
+
+  if (encryptedFields) {
+    // Create the required index for queryable encryption support.
+    const createIndexOp = CreateIndexesOperation.fromIndexSpecification(
+      db,
+      name,
+      { __safeContent__: 1 },
+      { session: options.session }
+    );
+    await executeOperation(db.client, createIndexOp, timeoutContext);
+  }
+
+  return coll as unknown as Collection<TSchema>;
+}
+
+defineAspects(CreateCollectionOperation, [Aspect.WRITE_OPERATION]);

package/src/operations/delete.ts

@@ -0,0 +1,183 @@
+import type { Document } from '../bson';
+import { type Connection } from '../cmap/connection';
+import { MongoDBResponse } from '../cmap/wire_protocol/responses';
+import { MongoCompatibilityError, MongoServerError } from '../error';
+import type { ClientSession } from '../sessions';
+import { maxWireVersion, type MongoDBCollectionNamespace, type MongoDBNamespace } from '../utils';
+import { type WriteConcernOptions } from '../write_concern';
+import { type CollationOptions, CommandOperation, type CommandOperationOptions } from './command';
+import { Aspect, defineAspects, type Hint } from './operation';
+
+/** @public */
+export interface DeleteOptions extends CommandOperationOptions, WriteConcernOptions {
+  /** If true, when an insert fails, don't execute the remaining writes. If false, continue with remaining inserts when one fails. */
+  ordered?: boolean;
+  /** Specifies the collation to use for the operation */
+  collation?: CollationOptions;
+  /** Specify that the update query should only consider plans using the hinted index */
+  hint?: string | Document;
+  /** Map of parameter names and values that can be accessed using $$var (requires MongoDB 5.0). */
+  let?: Document;
+}
+
+/** @public */
+export interface DeleteResult {
+  /** Indicates whether this write result was acknowledged. If not, then all other members of this result will be undefined. */
+  acknowledged: boolean;
+  /** The number of documents that were deleted */
+  deletedCount: number;
+}
+
+/** @public */
+export interface DeleteStatement {
+  /** The query that matches documents to delete. */
+  q: Document;
+  /** The number of matching documents to delete. */
+  limit: number;
+  /** Specifies the collation to use for the operation. */
+  collation?: CollationOptions;
+  /** A document or string that specifies the index to use to support the query predicate. */
+  hint?: Hint;
+}
+
+/** @internal */
+export class DeleteOperation extends CommandOperation<Document> {
+  override SERVER_COMMAND_RESPONSE_TYPE = MongoDBResponse;
+  override options: DeleteOptions;
+  statements: DeleteStatement[];
+
+  constructor(ns: MongoDBNamespace, statements: DeleteStatement[], options: DeleteOptions) {
+    super(undefined, options);
+    this.options = options;
+    this.ns = ns;
+    this.statements = statements;
+  }
+
+  override get commandName() {
+    return 'delete' as const;
+  }
+
+  override get canRetryWrite(): boolean {
+    if (super.canRetryWrite === false) {
+      return false;
+    }
+
+    return this.statements.every(op => (op.limit != null ? op.limit > 0 : true));
+  }
+
+  override buildCommandDocument(connection: Connection, _session?: ClientSession): Document {
+    const options = this.options;
+
+    const ordered = typeof options.ordered === 'boolean' ? options.ordered : true;
+    const command: Document = {
+      delete: this.ns.collection,
+      deletes: this.statements,
+      ordered
+    };
+
+    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;
+    }
+
+    const unacknowledgedWrite = this.writeConcern && this.writeConcern.w === 0;
+    if (unacknowledgedWrite && maxWireVersion(connection) < 9) {
+      if (this.statements.find((o: Document) => o.hint)) {
+        throw new MongoCompatibilityError(
+          `hint for the delete command is only supported on MongoDB 4.4+`
+        );
+      }
+    }
+
+    return command;
+  }
+}
+
+export class DeleteOneOperation extends DeleteOperation {
+  constructor(ns: MongoDBCollectionNamespace, filter: Document, options: DeleteOptions) {
+    super(ns, [makeDeleteStatement(filter, { ...options, limit: 1 })], options);
+  }
+
+  override handleOk(
+    response: InstanceType<typeof this.SERVER_COMMAND_RESPONSE_TYPE>
+  ): DeleteResult {
+    const res = super.handleOk(response);
+
+    // @ts-expect-error Explain commands have broken TS
+    if (this.explain) return res;
+
+    if (res.code) throw new MongoServerError(res);
+    if (res.writeErrors) throw new MongoServerError(res.writeErrors[0]);
+
+    return {
+      acknowledged: this.writeConcern?.w !== 0,
+      deletedCount: res.n
+    };
+  }
+}
+export class DeleteManyOperation extends DeleteOperation {
+  constructor(ns: MongoDBCollectionNamespace, filter: Document, options: DeleteOptions) {
+    super(ns, [makeDeleteStatement(filter, options)], options);
+  }
+
+  override handleOk(
+    response: InstanceType<typeof this.SERVER_COMMAND_RESPONSE_TYPE>
+  ): DeleteResult {
+    const res = super.handleOk(response);
+
+    // @ts-expect-error Explain commands have broken TS
+    if (this.explain) return res;
+
+    if (res.code) throw new MongoServerError(res);
+    if (res.writeErrors) throw new MongoServerError(res.writeErrors[0]);
+
+    return {
+      acknowledged: this.writeConcern?.w !== 0,
+      deletedCount: res.n
+    };
+  }
+}
+
+export function makeDeleteStatement(
+  filter: Document,
+  options: DeleteOptions & { limit?: number }
+): DeleteStatement {
+  const op: DeleteStatement = {
+    q: filter,
+    limit: typeof options.limit === 'number' ? options.limit : 0
+  };
+
+  if (options.collation) {
+    op.collation = options.collation;
+  }
+
+  if (options.hint) {
+    op.hint = options.hint;
+  }
+
+  return op;
+}
+
+defineAspects(DeleteOperation, [
+  Aspect.RETRYABLE,
+  Aspect.WRITE_OPERATION,
+  Aspect.SUPPORTS_RAW_DATA
+]);
+defineAspects(DeleteOneOperation, [
+  Aspect.RETRYABLE,
+  Aspect.WRITE_OPERATION,
+  Aspect.EXPLAINABLE,
+  Aspect.SKIP_COLLATION,
+  Aspect.SUPPORTS_RAW_DATA
+]);
+defineAspects(DeleteManyOperation, [
+  Aspect.WRITE_OPERATION,
+  Aspect.EXPLAINABLE,
+  Aspect.SKIP_COLLATION,
+  Aspect.SUPPORTS_RAW_DATA
+]);