asyncbox - npm Package Compare versions

Comparing version 6.2.0 to 6.3.0

build/lib/asyncbox.d.ts

@@ -1,2 +0,2 @@
-import type { LongSleepOptions, MapFilterOptions, WaitForConditionOptions } from './types.js';
+import type { CancellablePromise, LongSleepOptions, MapFilterOptions, SleepOptions, WaitForConditionOptions } from './types.js';
 /** Error thrown by {@link withTimeout} when the deadline is exceeded. */
@@ -6,8 +6,25 @@ export declare class TimeoutError extends Error {
 }
+/** Thrown when a promise is cancelled via `cancel`. */
+export declare class PromiseCancellationError extends Error {
+    constructor(message?: string);
+}
 /**
- * An async/await version of setTimeout
- * @param ms - The number of milliseconds to wait
+ * An async/await version of `setTimeout`. The returned promise has a `cancel()` method that clears
+ * the timer and usually rejects with {@link PromiseCancellationError} unless you use the object form with
+ * `cancelError: null` to resolve on cancel.
+ *
+ * @param ms - Milliseconds to wait
+ * @returns A thenable you can `await`; call `.cancel()` to abort early.
  */
-export declare function sleep(ms: number): Promise<void>;
+export declare function sleep(ms: number): CancellablePromise<void>;
 /**
+ * Object form: `ms` plus optional `cancelError` (non-empty string or `Error`, `null` to resolve on
+ * cancel, or omitted / `undefined` / `''` for default {@link PromiseCancellationError}). Any non-array
+ * object with a finite `ms` is accepted at runtime (including class instances), matching structural typing.
+ *
+ * @param options - Duration and optional cancellation behavior
+ * @returns A thenable you can `await`; call `.cancel()` to abort early.
+ */
+export declare function sleep(options: SleepOptions): CancellablePromise<void>;
+/**
  * Resolves with `promise` or rejects if it does not settle before `timeoutMs`.
@@ -86,3 +103,3 @@ *
 export declare function waitForCondition<T>(condFn: () => Promise<T> | T, options?: WaitForConditionOptions): Promise<T>;
-export type { Progress, ProgressCallback, LongSleepOptions, WaitForConditionOptions, } from './types.js';
+export type { CancellablePromise, Progress, ProgressCallback, LongSleepOptions, SleepArg, SleepOptions, WaitForConditionOptions, } from './types.js';
 //# sourceMappingURL=asyncbox.d.ts.map

build/lib/asyncbox.d.ts.map

@@ -1,1 +0,1 @@
-{"version":3,"file":"asyncbox.d.ts","sourceRoot":"","sources":["../../lib/asyncbox.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,gBAAgB,EAAE,gBAAgB,EAAE,uBAAuB,EAAC,MAAM,YAAY,CAAC;AAI5F,yEAAyE;AACzE,qBAAa,YAAa,SAAQ,KAAK;gBACzB,OAAO,CAAC,EAAE,MAAM;CAI7B;AAED;;;GAGG;AACH,wBAAsB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAErD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,WAAW,CAAC,CAAC,EACjC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,SAAS,EAAE,MAAM,EACjB,cAAc,CAAC,EAAE,MAAM,GAAG,KAAK,GAC9B,OAAO,CAAC,CAAC,CAAC,CAsBZ;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,SAAS,CAC7B,EAAE,EAAE,MAAM,EACV,EAAC,WAAkC,EAAE,UAAiB,EAAE,UAAiB,EAAC,GAAE,gBAAqB,GAChG,OAAO,CAAC,IAAI,CAAC,CAiBf;AAED;;;;;GAKG;AACH,wBAAsB,KAAK,CAAC,CAAC,GAAG,GAAG,EACjC,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,EAClC,GAAG,IAAI,EAAE,GAAG,EAAE,GACb,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAgBnB;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,CAAC,GAAG,GAAG,EACzC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,EAClC,GAAG,IAAI,EAAE,GAAG,EAAE,GACb,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAiBnB;AAED;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAAE,CAAC,EACjC,IAAI,EAAE,CAAC,EAAE,EACT,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EACpC,OAAO,GAAE,gBAAuB,GAC/B,OAAO,CAAC,CAAC,EAAE,CAAC,CAed;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAAC,CAAC,EACjC,IAAI,EAAE,CAAC,EAAE,EACT,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,EAChD,OAAO,GAAE,gBAAuB,GAC/B,OAAO,CAAC,CAAC,EAAE,CAAC,CAwBd;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACtC,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EAC5B,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,CAAC,CAAC,CA8BZ;AAGD,YAAY,EACV,QAAQ,EACR,gBAAgB,EAChB,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"asyncbox.d.ts","sourceRoot":"","sources":["../../lib/asyncbox.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAEhB,YAAY,EACZ,uBAAuB,EACxB,MAAM,YAAY,CAAC;AAIpB,yEAAyE;AACzE,qBAAa,YAAa,SAAQ,KAAK;gBACzB,OAAO,CAAC,EAAE,MAAM;CAI7B;AAED,uDAAuD;AACvD,qBAAa,wBAAyB,SAAQ,KAAK;gBACrC,OAAO,GAAE,MAA4B;CAIlD;AAED;;;;;;;GAOG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;AAC5D;;;;;;;GAOG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;AAsCvE;;;;;;;;;;;;;GAaG;AACH,wBAAsB,WAAW,CAAC,CAAC,EACjC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,SAAS,EAAE,MAAM,EACjB,cAAc,CAAC,EAAE,MAAM,GAAG,KAAK,GAC9B,OAAO,CAAC,CAAC,CAAC,CAsBZ;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,SAAS,CAC7B,EAAE,EAAE,MAAM,EACV,EAAC,WAAkC,EAAE,UAAiB,EAAE,UAAiB,EAAC,GAAE,gBAAqB,GAChG,OAAO,CAAC,IAAI,CAAC,CAiBf;AAED;;;;;GAKG;AACH,wBAAsB,KAAK,CAAC,CAAC,GAAG,GAAG,EACjC,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,EAClC,GAAG,IAAI,EAAE,GAAG,EAAE,GACb,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAgBnB;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,CAAC,GAAG,GAAG,EACzC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,EAClC,GAAG,IAAI,EAAE,GAAG,EAAE,GACb,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAiBnB;AAED;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAAE,CAAC,EACjC,IAAI,EAAE,CAAC,EAAE,EACT,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EACpC,OAAO,GAAE,gBAAuB,GAC/B,OAAO,CAAC,CAAC,EAAE,CAAC,CAed;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAAC,CAAC,EACjC,IAAI,EAAE,CAAC,EAAE,EACT,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,EAChD,OAAO,GAAE,gBAAuB,GAC/B,OAAO,CAAC,CAAC,EAAE,CAAC,CAwBd;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACtC,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EAC5B,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,CAAC,CAAC,CA8BZ;AAGD,YAAY,EACV,kBAAkB,EAClB,QAAQ,EACR,gBAAgB,EAChB,gBAAgB,EAChB,QAAQ,EACR,YAAY,EACZ,uBAAuB,GACxB,MAAM,YAAY,CAAC"}

build/lib/asyncbox.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TimeoutError = void 0;
+exports.PromiseCancellationError = exports.TimeoutError = void 0;
 exports.sleep = sleep;
@@ -22,9 +22,46 @@ exports.withTimeout = withTimeout;
 exports.TimeoutError = TimeoutError;
-/**
- * An async/await version of setTimeout
- * @param ms - The number of milliseconds to wait
- */
-async function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+/** Thrown when a promise is cancelled via `cancel`. */
+class PromiseCancellationError extends Error {
+    constructor(message = 'Promise cancelled') {
+        super(message);
+        this.name = 'PromiseCancellationError';
+    }
 }
+exports.PromiseCancellationError = PromiseCancellationError;
+function sleep(arg) {
+    const { ms, cancelError } = parseSleepArg(arg);
+    let timeoutId;
+    let resolveFn;
+    let rejectFn;
+    const promise = new Promise((resolve, reject) => {
+        resolveFn = resolve;
+        rejectFn = reject;
+        timeoutId = setTimeout(resolve, ms);
+    });
+    promise.cancel = () => {
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+            timeoutId = undefined;
+        }
+        if (cancelError === null) {
+            resolveFn?.(undefined);
+        }
+        else {
+            let err;
+            if (typeof cancelError === 'string' && cancelError) {
+                err = new PromiseCancellationError(cancelError);
+            }
+            else if (cancelError instanceof Error) {
+                err = cancelError;
+            }
+            else {
+                err = new PromiseCancellationError();
+            }
+            rejectFn?.(err);
+        }
+        resolveFn = undefined;
+        rejectFn = undefined;
+    };
+    return promise;
+}
 /**
@@ -245,2 +282,22 @@ * Resolves with `promise` or rejects if it does not settle before `timeoutMs`.
 }
+/** Non-array object values (including class instances); excludes `null` and arrays. */
+function isSleepArgObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function parseSleepArg(arg) {
+    if (typeof arg === 'number') {
+        if (!Number.isFinite(arg)) {
+            throw new TypeError('sleep: expected a finite number or an object with ms');
+        }
+        return { ms: arg };
+    }
+    if (isSleepArgObject(arg)) {
+        const ms = arg.ms;
+        if (typeof ms !== 'number' || !Number.isFinite(ms)) {
+            throw new TypeError('sleep: options.ms must be a finite number');
+        }
+        return { ms, cancelError: arg.cancelError };
+    }
+    throw new TypeError('sleep: expected a finite number or an object with ms');
+}
 //# sourceMappingURL=asyncbox.js.map

build/lib/asyncbox.js.map

@@ -1,1 +0,1 @@
-{"version":3,"file":"asyncbox.js","sourceRoot":"","sources":["../../lib/asyncbox.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"asyncbox.js","sourceRoot":"","sources":["../../lib/asyncbox.ts"],"names":[],"mappings":"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"}

build/lib/types.d.ts

@@ -38,2 +38,28 @@ /**
 /**
+ * Object form of {@link sleep}'s argument: duration plus optional cancellation rejection override.
+ * Structural typing allows class instances; {@link sleep} accepts any non-array object with a finite `ms`.
+ */
+export interface SleepOptions {
+    /** Duration in milliseconds */
+    ms: number;
+    /**
+     * When {@link sleep}'s `cancel` runs: a non-empty string becomes {@link PromiseCancellationError}
+     * with that message; an `Error` rejects with that same instance; `null` resolves the promise
+     * instead of rejecting; omitted, `undefined`, or `''` use the default {@link PromiseCancellationError}.
+     */
+    cancelError?: string | Error | null;
+}
+/**
+ * Argument to {@link sleep}: either milliseconds or an options object (see {@link SleepOptions}).
+ */
+export type SleepArg = number | SleepOptions;
+/**
+ * A promise with a {@linkcode cancel} method (e.g. from {@link sleep}).
+ *
+ * @typeParam T - Resolved value type; {@link sleep} uses `void`.
+ */
+export type CancellablePromise<T = void> = Promise<T> & {
+    cancel: () => void;
+};
+/**
  * Options for {@link waitForCondition}
@@ -40,0 +66,0 @@ */

build/lib/types.d.ts.map

@@ -1,1 +0,1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../lib/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,QAAQ,EAAE,QAAQ,KAAK,IAAI,CAAC;AAE5D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,UAAU,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG;IAAC,WAAW,EAAE,MAAM,CAAA;CAAC,CAAC;AAE/D;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,MAAM,CAAC,EAAE;QACP,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;KACjC,CAAC;IACF;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;CACxB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../lib/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,QAAQ,EAAE,QAAQ,KAAK,IAAI,CAAC;AAE5D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,UAAU,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG;IAAC,WAAW,EAAE,MAAM,CAAA;CAAC,CAAC;AAE/D;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,+BAA+B;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,YAAY,CAAC;AAE7C;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,GAAG,IAAI,IAAI,OAAO,CAAC,CAAC,CAAC,GAAG;IACtD,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,MAAM,CAAC,EAAE;QACP,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;KACjC,CAAC;IACF;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;CACxB"}

lib/asyncbox.ts

 import {limitFunction} from 'p-limit';
-import type {LongSleepOptions, MapFilterOptions, WaitForConditionOptions} from './types.js';
+import type {
+  CancellablePromise,
+  LongSleepOptions,
+  MapFilterOptions,
+  SleepArg,
+  SleepOptions,
+  WaitForConditionOptions,
+} from './types.js';
 
@@ -14,8 +21,63 @@ const LONG_SLEEP_THRESHOLD = 5000; // anything over 5000ms will turn into a spin
 
+/** Thrown when a promise is cancelled via `cancel`. */
+export class PromiseCancellationError extends Error {
+  constructor(message: string = 'Promise cancelled') {
+    super(message);
+    this.name = 'PromiseCancellationError';
+  }
+}
+
 /**
- * An async/await version of setTimeout
- * @param ms - The number of milliseconds to wait
+ * An async/await version of `setTimeout`. The returned promise has a `cancel()` method that clears
+ * the timer and usually rejects with {@link PromiseCancellationError} unless you use the object form with
+ * `cancelError: null` to resolve on cancel.
+ *
+ * @param ms - Milliseconds to wait
+ * @returns A thenable you can `await`; call `.cancel()` to abort early.
  */
-export async function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+export function sleep(ms: number): CancellablePromise<void>;
+/**
+ * Object form: `ms` plus optional `cancelError` (non-empty string or `Error`, `null` to resolve on
+ * cancel, or omitted / `undefined` / `''` for default {@link PromiseCancellationError}). Any non-array
+ * object with a finite `ms` is accepted at runtime (including class instances), matching structural typing.
+ *
+ * @param options - Duration and optional cancellation behavior
+ * @returns A thenable you can `await`; call `.cancel()` to abort early.
+ */
+export function sleep(options: SleepOptions): CancellablePromise<void>;
+export function sleep(arg: SleepArg): CancellablePromise<void> {
+  const {ms, cancelError} = parseSleepArg(arg);
+  let timeoutId: NodeJS.Timeout | undefined;
+  let resolveFn: ((value: void) => void) | undefined;
+  let rejectFn: ((error: Error) => void) | undefined;
+
+  const promise = new Promise<void>((resolve, reject) => {
+    resolveFn = resolve;
+    rejectFn = reject;
+    timeoutId = setTimeout(resolve, ms);
+  }) as CancellablePromise<void>;
+
+  promise.cancel = () => {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+      timeoutId = undefined;
+    }
+    if (cancelError === null) {
+      resolveFn?.(undefined);
+    } else {
+      let err: Error;
+      if (typeof cancelError === 'string' && cancelError) {
+        err = new PromiseCancellationError(cancelError);
+      } else if (cancelError instanceof Error) {
+        err = cancelError;
+      } else {
+        err = new PromiseCancellationError();
+      }
+      rejectFn?.(err);
+    }
+    resolveFn = undefined;
+    rejectFn = undefined;
+  };
+
+  return promise;
 }
@@ -274,6 +336,31 @@
 export type {
+  CancellablePromise,
   Progress,
   ProgressCallback,
   LongSleepOptions,
+  SleepArg,
+  SleepOptions,
   WaitForConditionOptions,
 } from './types.js';
+
+/** Non-array object values (including class instances); excludes `null` and arrays. */
+function isSleepArgObject(value: unknown): value is Record<PropertyKey, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function parseSleepArg(arg: SleepArg): {ms: number; cancelError?: string | Error | null} {
+  if (typeof arg === 'number') {
+    if (!Number.isFinite(arg)) {
+      throw new TypeError('sleep: expected a finite number or an object with ms');
+    }
+    return {ms: arg};
+  }
+  if (isSleepArgObject(arg)) {
+    const ms = arg.ms;
+    if (typeof ms !== 'number' || !Number.isFinite(ms)) {
+      throw new TypeError('sleep: options.ms must be a finite number');
+    }
+    return {ms, cancelError: arg.cancelError as string | Error | null | undefined};
+  }
+  throw new TypeError('sleep: expected a finite number or an object with ms');
+}

lib/types.ts

@@ -40,2 +40,31 @@ /**
 /**
+ * Object form of {@link sleep}'s argument: duration plus optional cancellation rejection override.
+ * Structural typing allows class instances; {@link sleep} accepts any non-array object with a finite `ms`.
+ */
+export interface SleepOptions {
+  /** Duration in milliseconds */
+  ms: number;
+  /**
+   * When {@link sleep}'s `cancel` runs: a non-empty string becomes {@link PromiseCancellationError}
+   * with that message; an `Error` rejects with that same instance; `null` resolves the promise
+   * instead of rejecting; omitted, `undefined`, or `''` use the default {@link PromiseCancellationError}.
+   */
+  cancelError?: string | Error | null;
+}
+
+/**
+ * Argument to {@link sleep}: either milliseconds or an options object (see {@link SleepOptions}).
+ */
+export type SleepArg = number | SleepOptions;
+
+/**
+ * A promise with a {@linkcode cancel} method (e.g. from {@link sleep}).
+ *
+ * @typeParam T - Resolved value type; {@link sleep} uses `void`.
+ */
+export type CancellablePromise<T = void> = Promise<T> & {
+  cancel: () => void;
+};
+
+/**
  * Options for {@link waitForCondition}
@@ -42,0 +71,0 @@ */

package.json

@@ -9,3 +9,3 @@ {
   ],
-  "version": "6.2.0",
+  "version": "6.3.0",
   "author": "[e-mail]",
@@ -58,2 +58,4 @@ "license": "Apache-2.0",
     "@semantic-release/git": "^10.0.1",
+    "@types/chai": "^5.2.3",
+    "@types/chai-as-promised": "^8.0.2",
     "@types/mocha": "^10.0.10",
@@ -60,0 +62,0 @@ "@types/node": "^25.0.3",

No alert changes

Improved metrics

Total package byte prevSize

65461

18.97%

Lines of code

915

29.24%

Worsened metrics

Dev dependency count

18

12.5%

No dependency changes