Class CancellableToken

constructor

• new CancellableToken(signal: AbortSignal, name?: string): CancellableToken

  Creates a new CancellableToken instance.

  Parameters

  • signal: AbortSignal

    The AbortSignal to monitor for cancellation

  • Optionalname: string

    Optional name for this token, used for debugging

  Returns CancellableToken

[RETRY_ATTEMPT]

Optional Readonlyname

Readonlysignal

retryAttempt

• get retryAttempt(): number

  Gets the current retry attempt number. Returns 0 for the initial attempt, 1 for the first retry, and so on. This is useful for tracking retry progress when retry options are configured.

  Returns number

  The current retry attempt number (0-indexed)

delay

• delay(schedule: (done: () => void) => () => void): CancellableHandle<void>

  Creates a cancellable delay using a custom scheduling function. The scheduling function receives a callback to invoke when the delay completes, and must return a cleanup function to cancel the scheduled operation.

  The delay will stop when:

  • The parent token is cancelled
  • The returned handle is cancelled

  Parameters

  • schedule: (done: () => void) => () => void

    Function that schedules the delay and returns a cleanup function

  Returns CancellableHandle<void>

  A CancellableHandle that resolves when the delay completes, or can be cancelled independently of the parent token

  Example

  // Custom delay using setTimeout
  await token.delay((done) => {
    const timer = setTimeout(done, 1000);
    return () => clearTimeout(timer);
  });
  
  // Cancel independently
  const handle = token.delay((done) => {
    const timer = setTimeout(done, 5000);
    return () => clearTimeout(timer);
  });
  handle.cancel();
  Copy

frame

• frame(): CancellableHandle<void>

  Creates a cancellable animation frame. Uses requestAnimationFrame if available, otherwise falls back to setTimeout. The handle will be rejected if the token is cancelled before the frame callback.

  Returns CancellableHandle<void>

  A CancellableHandle that resolves on the next animation frame, or can be cancelled independently of the parent token

interval

• interval(
      fn: () => void | Promise<void>,
      interval: number,
  ): CancellableHandle<void>

  Executes a function repeatedly at a specified interval until cancelled. The function can be synchronous or asynchronous. Each execution waits for the previous one to complete before scheduling the next interval delay.

  The interval will stop when:

  • The parent token is cancelled
  • The returned handle is cancelled
  • The function throws an error (non-CancelError errors reject with the original error)

  Parameters

  • fn: () => void | Promise<void>

    The function to execute at each interval. Can return a Promise for async operations.

  • interval: number

    The interval in milliseconds to wait between executions (after each execution completes)

  Returns CancellableHandle<void>

  A CancellableHandle that can be used to cancel the interval independently of the parent token

  Example

  // Poll an API every 5 seconds
  const handle = token.interval(async () => {
    const data = await fetchData();
    processData(data);
  }, 5000);
  
  // Cancel the interval independently
  handle.cancel();
  Copy

isCancelled

• isCancelled(): boolean

  Checks if the token has been cancelled.

  Returns boolean

  True if the token has been cancelled, false otherwise

onCancel

• onCancel(callback: (error: CancelError) => void): () => void

  Registers a callback to be invoked when the token is cancelled. If the token is already cancelled, the callback is invoked immediately.

  Parameters

  • callback: (error: CancelError) => void

    Function to call when cancellation occurs, receives the CancelError

  Returns () => void

  A cleanup function to remove the callback listener

  Example

  const unsubscribe = token.onCancel((error) => {
    console.log('Task cancelled:', error.message);
  });
  // Later, to remove the listener:
  unsubscribe();
  Copy

sleep

• sleep(ms: number): CancellableHandle<void>

  Creates a cancellable sleep/delay. The handle will be rejected if the token is cancelled during the sleep period.

  Parameters

  • ms: number

    The number of milliseconds to sleep

  Returns CancellableHandle<void>

  A CancellableHandle that resolves after the specified delay, or can be cancelled independently of the parent token

throwIfCancelled

• throwIfCancelled(): void

  Throws a CancelError if the token has been cancelled. Useful for checking cancellation status at specific points in async operations.

  Returns void

  Throws

  If the token has been cancelled

wrap

• wrap<T>(p: CancellableHandle<T> | Promise<T>): Promise<T>

  Wraps a promise or CancellableHandle to respect the cancellation token. If the token is cancelled, the wrapped promise will be rejected with a CancelError.

  Type Parameters

  • T

    The type of the promise result

  Parameters

  • p: CancellableHandle<T> | Promise<T>

    The promise or CancellableHandle to wrap

  Returns Promise<T>

  A promise that respects the cancellation token