mongodb 6.12.0-dev.20250124.sha.70d476aa → 6.12.0-dev.20250128.sha.654069fc

package/src/cursor/abstract_cursor.ts

@@ -12,7 +12,7 @@ import {
   MongoTailableCursorError
 } from '../error';
 import type { MongoClient } from '../mongo_client';
-import { TypedEventEmitter } from '../mongo_types';
+import { type Abortable, TypedEventEmitter } from '../mongo_types';
 import { executeOperation } from '../operations/execute_operation';
 import { GetMoreOperation } from '../operations/get_more';
 import { KillCursorsOperation } from '../operations/kill_cursors';
@@ -22,7 +22,13 @@ import { type AsyncDisposable, configureResourceManagement } from '../resource_m
 import type { Server } from '../sdam/server';
 import { ClientSession, maybeClearPinnedConnection } from '../sessions';
 import { type CSOTTimeoutContext, type Timeout, TimeoutContext } from '../timeout';
-import { type MongoDBNamespace, squashError } from '../utils';
+import {
+  addAbortListener,
+  type Disposable,
+  kDispose,
+  type MongoDBNamespace,
+  squashError
+} from '../utils';
 
 /**
  * @internal
@@ -61,6 +67,10 @@ export interface CursorStreamOptions {
 /** @public */
 export type CursorFlag = (typeof CURSOR_FLAGS)[number];
 
+function removeActiveCursor(this: AbstractCursor) {
+  this.client.s.activeCursors.delete(this);
+}
+
 /**
  * @public
  * @experimental
@@ -247,12 +257,14 @@ export abstract class AbstractCursor<
 
   /** @internal */
   protected deserializationOptions: OnDemandDocumentDeserializeOptions;
+  protected signal: AbortSignal | undefined;
+  private abortListener: Disposable | undefined;
 
   /** @internal */
   protected constructor(
     client: MongoClient,
     namespace: MongoDBNamespace,
-    options: AbstractCursorOptions = {}
+    options: AbstractCursorOptions & Abortable = {}
   ) {
     super();
 
@@ -352,6 +364,12 @@ export abstract class AbstractCursor<
     };
 
     this.timeoutContext = options.timeoutContext;
+    this.signal = options.signal;
+    this.abortListener = addAbortListener(
+      this.signal,
+      () => void this.close().then(undefined, squashError)
+    );
+    this.trackCursor();
   }
 
   /**
@@ -431,6 +449,14 @@ export abstract class AbstractCursor<
     await this.close();
   }
 
+  /** Adds cursor to client's tracking so it will be closed by MongoClient.close() */
+  private trackCursor() {
+    this.cursorClient.s.activeCursors.add(this);
+    if (!this.listeners('close').includes(removeActiveCursor)) {
+      this.once('close', removeActiveCursor);
+    }
+  }
+
   /** Returns current buffered documents length */
   bufferedCount(): number {
     return this.documents?.length ?? 0;
@@ -455,6 +481,8 @@ export abstract class AbstractCursor<
   }
 
   async *[Symbol.asyncIterator](): AsyncGenerator<TSchema, void, void> {
+    this.signal?.throwIfAborted();
+
     if (this.closed) {
       return;
     }
@@ -481,6 +509,8 @@ export abstract class AbstractCursor<
         }
 
         yield document;
+
+        this.signal?.throwIfAborted();
       }
     } finally {
       // Only close the cursor if it has not already been closed. This finally clause handles
@@ -496,9 +526,16 @@ export abstract class AbstractCursor<
   }
 
   stream(options?: CursorStreamOptions): Readable & AsyncIterable<TSchema> {
+    const readable = new ReadableCursorStream(this);
+    const abortListener = addAbortListener(this.signal, function () {
+      readable.destroy(this.reason);
+    });
+    readable.once('end', () => {
+      abortListener?.[kDispose]();
+    });
+
     if (options?.transform) {
       const transform = options.transform;
-      const readable = new ReadableCursorStream(this);
 
       const transformedStream = readable.pipe(
         new Transform({
@@ -522,10 +559,12 @@ export abstract class AbstractCursor<
       return transformedStream;
     }
 
-    return new ReadableCursorStream(this);
+    return readable;
   }
 
   async hasNext(): Promise<boolean> {
+    this.signal?.throwIfAborted();
+
     if (this.cursorId === Long.ZERO) {
       return false;
     }
@@ -551,6 +590,8 @@ export abstract class AbstractCursor<
 
   /** Get the next available document from the cursor, returns null if no more documents are available. */
   async next(): Promise<TSchema | null> {
+    this.signal?.throwIfAborted();
+
     if (this.cursorId === Long.ZERO) {
       throw new MongoCursorExhaustedError();
     }
@@ -581,6 +622,8 @@ export abstract class AbstractCursor<
    * Try to get the next available document from the cursor or `null` if an empty batch is returned
    */
   async tryNext(): Promise<TSchema | null> {
+    this.signal?.throwIfAborted();
+
     if (this.cursorId === Long.ZERO) {
       throw new MongoCursorExhaustedError();
     }
@@ -620,6 +663,8 @@ export abstract class AbstractCursor<
    * @deprecated - Will be removed in a future release. Use for await...of instead.
    */
   async forEach(iterator: (doc: TSchema) => boolean | void): Promise<void> {
+    this.signal?.throwIfAborted();
+
     if (typeof iterator !== 'function') {
       throw new MongoInvalidArgumentError('Argument "iterator" must be a function');
     }
@@ -645,6 +690,8 @@ export abstract class AbstractCursor<
    * cursor.rewind() can be used to reset the cursor.
    */
   async toArray(): Promise<TSchema[]> {
+    this.signal?.throwIfAborted();
+
     const array: TSchema[] = [];
     // at the end of the loop (since readBufferedDocuments is called) the buffer will be empty
     // then, the 'await of' syntax will run a getMore call
@@ -824,16 +871,15 @@ export abstract class AbstractCursor<
     this.isClosed = false;
     this.isKilled = false;
     this.initialized = false;
+    this.hasEmittedClose = false;
+    this.trackCursor();
 
-    const session = this.cursorSession;
-    if (session) {
-      // We only want to end this session if we created it, and it hasn't ended yet
-      if (session.explicit === false) {
-        if (!session.hasEnded) {
-          session.endSession().then(undefined, squashError);
-        }
-        this.cursorSession = this.cursorClient.startSession({ owner: this, explicit: false });
+    // We only want to end this session if we created it, and it hasn't ended yet
+    if (this.cursorSession.explicit === false) {
+      if (!this.cursorSession.hasEnded) {
+        this.cursorSession.endSession().then(undefined, squashError);
       }
+      this.cursorSession = this.cursorClient.startSession({ owner: this, explicit: false });
     }
   }
 
@@ -968,8 +1014,8 @@ export abstract class AbstractCursor<
 
   /** @internal */
   private async cleanup(timeoutMS?: number, error?: Error) {
+    this.abortListener?.[kDispose]();
     this.isClosed = true;
-    const session = this.cursorSession;
     const timeoutContextForKillCursors = (): CursorTimeoutContext | undefined => {
       if (timeoutMS != null) {
         this.timeoutContext?.clear();
@@ -991,7 +1037,7 @@ export abstract class AbstractCursor<
         !this.cursorId.isZero() &&
         this.cursorNamespace &&
         this.selectedServer &&
-        !session.hasEnded
+        !this.cursorSession.hasEnded
       ) {
         this.isKilled = true;
         const cursorId = this.cursorId;
@@ -1000,7 +1046,7 @@ export abstract class AbstractCursor<
         await executeOperation(
           this.cursorClient,
           new KillCursorsOperation(cursorId, this.cursorNamespace, this.selectedServer, {
-            session
+            session: this.cursorSession
           }),
           timeoutContextForKillCursors()
         );
@@ -1008,14 +1054,16 @@ export abstract class AbstractCursor<
     } catch (error) {
       squashError(error);
     } finally {
-      if (session?.owner === this) {
-        await session.endSession({ error });
-      }
-      if (!session?.inTransaction()) {
-        maybeClearPinnedConnection(session, { error });
+      try {
+        if (this.cursorSession?.owner === this) {
+          await this.cursorSession.endSession({ error });
+        }
+        if (!this.cursorSession?.inTransaction()) {
+          maybeClearPinnedConnection(this.cursorSession, { error });
+        }
+      } finally {
+        this.emitClose();
       }
-
-      this.emitClose();
     }
   }
 

package/src/cursor/aggregation_cursor.ts

@@ -8,6 +8,7 @@ import {
   validateExplainTimeoutOptions
 } from '../explain';
 import type { MongoClient } from '../mongo_client';
+import { type Abortable } from '../mongo_types';
 import { AggregateOperation, type AggregateOptions } from '../operations/aggregate';
 import { executeOperation } from '../operations/execute_operation';
 import type { ClientSession } from '../sessions';
@@ -32,14 +33,14 @@ export interface AggregationCursorOptions extends AbstractCursorOptions, Aggrega
 export class AggregationCursor<TSchema = any> extends ExplainableCursor<TSchema> {
   public readonly pipeline: Document[];
   /** @internal */
-  private aggregateOptions: AggregateOptions;
+  private aggregateOptions: AggregateOptions & Abortable;
 
   /** @internal */
   constructor(
     client: MongoClient,
     namespace: MongoDBNamespace,
     pipeline: Document[] = [],
-    options: AggregateOptions = {}
+    options: AggregateOptions & Abortable = {}
   ) {
     super(client, namespace, options);
 
@@ -73,7 +74,8 @@ export class AggregationCursor<TSchema = any> extends ExplainableCursor<TSchema>
     const options = {
       ...this.aggregateOptions,
       ...this.cursorOptions,
-      session
+      session,
+      signal: this.signal
     };
     if (options.explain) {
       try {

package/src/cursor/find_cursor.ts

@@ -9,6 +9,7 @@ import {
   validateExplainTimeoutOptions
 } from '../explain';
 import type { MongoClient } from '../mongo_client';
+import { type Abortable } from '../mongo_types';
 import type { CollationOptions } from '../operations/command';
 import { CountOperation, type CountOptions } from '../operations/count';
 import { executeOperation } from '../operations/execute_operation';
@@ -36,14 +37,14 @@ export class FindCursor<TSchema = any> extends ExplainableCursor<TSchema> {
   /** @internal */
   private numReturned = 0;
   /** @internal */
-  private readonly findOptions: FindOptions;
+  private readonly findOptions: FindOptions & Abortable;
 
   /** @internal */
   constructor(
     client: MongoClient,
     namespace: MongoDBNamespace,
     filter: Document = {},
-    options: FindOptions = {}
+    options: FindOptions & Abortable = {}
   ) {
     super(client, namespace, options);
 
@@ -72,7 +73,8 @@ export class FindCursor<TSchema = any> extends ExplainableCursor<TSchema> {
     const options = {
       ...this.findOptions, // NOTE: order matters here, we may need to refine this
       ...this.cursorOptions,
-      session
+      session,
+      signal: this.signal
     };
 
     if (options.explain) {

package/src/cursor/list_collections_cursor.ts

@@ -1,5 +1,6 @@
 import type { Document } from '../bson';
 import type { Db } from '../db';
+import { type Abortable } from '../mongo_types';
 import { executeOperation } from '../operations/execute_operation';
 import {
   type CollectionInfo,
@@ -17,9 +18,9 @@ export class ListCollectionsCursor<
 > extends AbstractCursor<T> {
   parent: Db;
   filter: Document;
-  options?: ListCollectionsOptions;
+  options?: ListCollectionsOptions & Abortable;
 
-  constructor(db: Db, filter: Document, options?: ListCollectionsOptions) {
+  constructor(db: Db, filter: Document, options?: ListCollectionsOptions & Abortable) {
     super(db.client, db.s.namespace, options);
     this.parent = db;
     this.filter = filter;
@@ -38,7 +39,8 @@ export class ListCollectionsCursor<
     const operation = new ListCollectionsOperation(this.parent, this.filter, {
       ...this.cursorOptions,
       ...this.options,
-      session
+      session,
+      signal: this.signal
     });
 
     const response = await executeOperation(this.parent.client, operation, this.timeoutContext);

package/src/db.ts

@@ -8,7 +8,7 @@ import { ListCollectionsCursor } from './cursor/list_collections_cursor';
 import { RunCommandCursor, type RunCursorCommandOptions } from './cursor/run_command_cursor';
 import { MongoInvalidArgumentError } from './error';
 import type { MongoClient, PkFactory } from './mongo_client';
-import type { TODO_NODE_3286 } from './mongo_types';
+import type { Abortable, TODO_NODE_3286 } from './mongo_types';
 import type { AggregateOptions } from './operations/aggregate';
 import { CollectionsOperation } from './operations/collections';
 import {
@@ -273,7 +273,7 @@ export class Db {
    * @param command - The command to run
    * @param options - Optional settings for the command
    */
-  async command(command: Document, options?: RunCommandOptions): Promise<Document> {
+  async command(command: Document, options?: RunCommandOptions & Abortable): Promise<Document> {
     // Intentionally, we do not inherit options from parent for this operation.
     return await executeOperation(
       this.client,
@@ -284,7 +284,8 @@ export class Db {
           ...resolveBSONOptions(options),
           timeoutMS: options?.timeoutMS ?? this.timeoutMS,
           session: options?.session,
-          readPreference: options?.readPreference
+          readPreference: options?.readPreference,
+          signal: options?.signal
         })
       )
     );
@@ -351,22 +352,25 @@ export class Db {
    */
   listCollections(
     filter: Document,
-    options: Exclude<ListCollectionsOptions, 'nameOnly'> & { nameOnly: true }
+    options: Exclude<ListCollectionsOptions, 'nameOnly'> & { nameOnly: true } & Abortable
   ): ListCollectionsCursor<Pick<CollectionInfo, 'name' | 'type'>>;
   listCollections(
     filter: Document,
-    options: Exclude<ListCollectionsOptions, 'nameOnly'> & { nameOnly: false }
+    options: Exclude<ListCollectionsOptions, 'nameOnly'> & { nameOnly: false } & Abortable
   ): ListCollectionsCursor<CollectionInfo>;
   listCollections<
     T extends Pick<CollectionInfo, 'name' | 'type'> | CollectionInfo =
       | Pick<CollectionInfo, 'name' | 'type'>
       | CollectionInfo
-  >(filter?: Document, options?: ListCollectionsOptions): ListCollectionsCursor<T>;
+  >(filter?: Document, options?: ListCollectionsOptions & Abortable): ListCollectionsCursor<T>;
   listCollections<
     T extends Pick<CollectionInfo, 'name' | 'type'> | CollectionInfo =
       | Pick<CollectionInfo, 'name' | 'type'>
       | CollectionInfo
-  >(filter: Document = {}, options: ListCollectionsOptions = {}): ListCollectionsCursor<T> {
+  >(
+    filter: Document = {},
+    options: ListCollectionsOptions & Abortable = {}
+  ): ListCollectionsCursor<T> {
     return new ListCollectionsCursor<T>(this, filter, resolveOptions(this, options));
   }
 

package/src/index.ts

@@ -430,6 +430,7 @@ export type {
   SeverityLevel
 } from './mongo_logger';
 export type {
+  Abortable,
   CommonEvents,
   EventsDescription,
   GenericListener,

package/src/mongo_client.ts

@@ -18,6 +18,7 @@ import type { ClientMetadata } from './cmap/handshake/client_metadata';
 import type { CompressorName } from './cmap/wire_protocol/compression';
 import { parseOptions, resolveSRVRecord } from './connection_string';
 import { MONGO_CLIENT_EVENTS } from './constants';
+import { type AbstractCursor } from './cursor/abstract_cursor';
 import { Db, type DbOptions } from './db';
 import type { Encrypter } from './encrypter';
 import { MongoInvalidArgumentError } from './error';
@@ -323,6 +324,12 @@ export interface MongoClientPrivate {
    * - used to notify the leak checker in our tests if test author forgot to clean up explicit sessions
    */
   readonly activeSessions: Set<ClientSession>;
+  /**
+   * We keep a reference to the cursors that are created from this client.
+   * - used to track and close all cursors in client.close().
+   *   Cursors in this set are ones that still need to have their close method invoked (no other conditions are considered)
+   */
+  readonly activeCursors: Set<AbstractCursor>;
   readonly sessionPool: ServerSessionPool;
   readonly options: MongoOptions;
   readonly readConcern?: ReadConcern;
@@ -398,6 +405,7 @@ export class MongoClient extends TypedEventEmitter<MongoClientEvents> implements
       hasBeenClosed: false,
       sessionPool: new ServerSessionPool(this),
       activeSessions: new Set(),
+      activeCursors: new Set(),
       authProviders: new MongoClientAuthProviders(),
 
       get options() {
@@ -521,6 +529,10 @@ export class MongoClient extends TypedEventEmitter<MongoClientEvents> implements
    * This means the time to setup the `MongoClient` does not count against `timeoutMS`.
    * If you are using `timeoutMS` we recommend connecting your client explicitly in advance of any operation to avoid this inconsistent execution time.
    *
+   * @remarks
+   * The driver will look up corresponding SRV and TXT records if the connection string starts with `mongodb+srv://`.
+   * If those look ups throw a DNS Timeout error, the driver will retry the look up once.
+   *
    * @see docs.mongodb.org/manual/reference/connection-string/
    */
   async connect(): Promise<this> {
@@ -646,6 +658,11 @@ export class MongoClient extends TypedEventEmitter<MongoClientEvents> implements
       writable: false
     });
 
+    const activeCursorCloses = Array.from(this.s.activeCursors, cursor => cursor.close());
+    this.s.activeCursors.clear();
+
+    await Promise.all(activeCursorCloses);
+
     const activeSessionEnds = Array.from(this.s.activeSessions, session => session.endSession());
     this.s.activeSessions.clear();
 
@@ -727,6 +744,10 @@ export class MongoClient extends TypedEventEmitter<MongoClientEvents> implements
    * @remarks
    * The programmatically provided options take precedence over the URI options.
    *
+   * @remarks
+   * The driver will look up corresponding SRV and TXT records if the connection string starts with `mongodb+srv://`.
+   * If those look ups throw a DNS Timeout error, the driver will retry the look up once.
+   *
    * @see https://www.mongodb.com/docs/manual/reference/connection-string/
    */
   static async connect(url: string, options?: MongoClientOptions): Promise<MongoClient> {

package/src/mongo_logger.ts

@@ -1,6 +1,24 @@
 import { inspect, promisify } from 'util';
+import { isUint8Array } from 'util/types';
 
-import { type Document, EJSON, type EJSONOptions, type ObjectId } from './bson';
+import {
+  type Binary,
+  type BSONRegExp,
+  type BSONSymbol,
+  type Code,
+  type DBRef,
+  type Decimal128,
+  type Document,
+  type Double,
+  EJSON,
+  type EJSONOptions,
+  type Int32,
+  type Long,
+  type MaxKey,
+  type MinKey,
+  type ObjectId,
+  type Timestamp
+} from './bson';
 import type { CommandStartedEvent } from './cmap/command_monitoring_events';
 import type {
   ConnectionCheckedInEvent,
@@ -413,6 +431,20 @@ export interface LogConvertible extends Record<string, any> {
   toLog(): Record<string, any>;
 }
 
+type BSONObject =
+  | BSONRegExp
+  | BSONSymbol
+  | Code
+  | DBRef
+  | Decimal128
+  | Double
+  | Int32
+  | Long
+  | MaxKey
+  | MinKey
+  | ObjectId
+  | Timestamp
+  | Binary;
 /** @internal */
 export function stringifyWithMaxLen(
   value: any,
@@ -421,13 +453,107 @@ export function stringifyWithMaxLen(
 ): string {
   let strToTruncate = '';
 
+  let currentLength = 0;
+  const maxDocumentLengthEnsurer = function maxDocumentLengthEnsurer(key: string, value: any) {
+    if (currentLength >= maxDocumentLength) {
+      return undefined;
+    }
+    // Account for root document
+    if (key === '') {
+      // Account for starting brace
+      currentLength += 1;
+      return value;
+    }
+
+    // +4 accounts for 2 quotation marks, colon and comma after value
+    // Note that this potentially undercounts since it does not account for escape sequences which
+    // will have an additional backslash added to them once passed through JSON.stringify.
+    currentLength += key.length + 4;
+
+    if (value == null) return value;
+
+    switch (typeof value) {
+      case 'string':
+        // +2 accounts for quotes
+        // Note that this potentially undercounts similarly to the key length calculation
+        currentLength += value.length + 2;
+        break;
+      case 'number':
+      case 'bigint':
+        currentLength += String(value).length;
+        break;
+      case 'boolean':
+        currentLength += value ? 4 : 5;
+        break;
+      case 'object':
+        if (isUint8Array(value)) {
+          // '{"$binary":{"base64":"<base64 string>","subType":"XX"}}'
+          // This is an estimate based on the fact that the base64 is approximately 1.33x the length of
+          // the actual binary sequence https://en.wikipedia.org/wiki/Base64
+          currentLength += (22 + value.byteLength + value.byteLength * 0.33 + 18) | 0;
+        } else if ('_bsontype' in value) {
+          const v = value as BSONObject;
+          switch (v._bsontype) {
+            case 'Int32':
+              currentLength += String(v.value).length;
+              break;
+            case 'Double':
+              // Account for representing integers as <value>.0
+              currentLength +=
+                (v.value | 0) === v.value ? String(v.value).length + 2 : String(v.value).length;
+              break;
+            case 'Long':
+              currentLength += v.toString().length;
+              break;
+            case 'ObjectId':
+              // '{"$oid":"XXXXXXXXXXXXXXXXXXXXXXXX"}'
+              currentLength += 35;
+              break;
+            case 'MaxKey':
+            case 'MinKey':
+              // '{"$maxKey":1}' or '{"$minKey":1}'
+              currentLength += 13;
+              break;
+            case 'Binary':
+              // '{"$binary":{"base64":"<base64 string>","subType":"XX"}}'
+              // This is an estimate based on the fact that the base64 is approximately 1.33x the length of
+              // the actual binary sequence https://en.wikipedia.org/wiki/Base64
+              currentLength += (22 + value.position + value.position * 0.33 + 18) | 0;
+              break;
+            case 'Timestamp':
+              // '{"$timestamp":{"t":<t>,"i":<i>}}'
+              currentLength += 19 + String(v.t).length + 5 + String(v.i).length + 2;
+              break;
+            case 'Code':
+              // '{"$code":"<code>"}' or '{"$code":"<code>","$scope":<scope>}'
+              if (v.scope == null) {
+                currentLength += v.code.length + 10 + 2;
+              } else {
+                // Ignoring actual scope object, so this undercounts by a significant amount
+                currentLength += v.code.length + 10 + 11;
+              }
+              break;
+            case 'BSONRegExp':
+              // '{"$regularExpression":{"pattern":"<pattern>","options":"<options>"}}'
+              currentLength += 34 + v.pattern.length + 13 + v.options.length + 3;
+              break;
+          }
+        }
+    }
+    return value;
+  };
+
   if (typeof value === 'string') {
     strToTruncate = value;
   } else if (typeof value === 'function') {
     strToTruncate = value.name;
   } else {
     try {
-      strToTruncate = EJSON.stringify(value, options);
+      if (maxDocumentLength !== 0) {
+        strToTruncate = EJSON.stringify(value, maxDocumentLengthEnsurer, 0, options);
+      } else {
+        strToTruncate = EJSON.stringify(value, options);
+      }
     } catch (e) {
       strToTruncate = `Extended JSON serialization failed with: ${e.message}`;
     }

package/src/mongo_types.ts

@@ -474,6 +474,44 @@ export class TypedEventEmitter<Events extends EventsDescription> extends EventEm
 /** @public */
 export class CancellationToken extends TypedEventEmitter<{ cancel(): void }> {}
 
+/** @public */
+export type Abortable = {
+  /**
+   * @experimental
+   * When provided, the corresponding `AbortController` can be used to abort an asynchronous action.
+   *
+   * The `signal.reason` value is used as the error thrown.
+   *
+   * @remarks
+   * **NOTE:** If an abort signal aborts an operation while the driver is writing to the underlying
+   * socket or reading the response from the server, the socket will be closed.
+   * If signals are aborted at a high rate during socket read/writes this can lead to a high rate of connection reestablishment.
+   *
+   * We plan to mitigate this in a future release, please follow NODE-6062 (`timeoutMS` expiration suffers the same limitation).
+   *
+   * AbortSignals are likely a best fit for human interactive interruption (ex. ctrl-C) where the frequency
+   * of cancellation is reasonably low. If a signal is programmatically aborted for 100s of operations you can empty
+   * the driver's connection pool.
+   *
+   * @example
+   * ```js
+   * const controller = new AbortController();
+   * const { signal } = controller;
+   * process.on('SIGINT', () => controller.abort(new Error('^C pressed')));
+   *
+   * try {
+   *   const res = await fetch('...', { signal });
+   *   await collection.findOne(await res.json(), { signal });
+   * catch (error) {
+   *   if (error === signal.reason) {
+   *     // signal abort error handling
+   *   }
+   * }
+   * ```
+   */
+  signal?: AbortSignal | undefined;
+};
+
 /**
  * Helper types for dot-notation filter attributes
  */