A library for canceling asynchronous requests that combines the Saborter library and React.

📚 Documentation

The documentation is divided into several sections:

• Installation
• Possibilities
• Quick Start
• API
• Usage Examples
• License

📦 Installation

npm install @saborter/react
# or
yarn add @saborter/react

📖 Possibilities

• The aborter field always has the same reference to the Aborter instance.
• Automatically abort the request when the component is unmounted.
• Automatically unsubscribe from all listeners when the component is unmounted.

🚀 Quick Start

Basic Usage

import { useAborter } from '@saborter/react';

const Component = () => {
  // Create an Aborter instance via the hook
  const { aborter } = useAborter();

  // Use for the request
  const fetchData = async () => {
    try {
      const data = await aborter.try((signal) => fetch('/api/data', { signal }));
      console.log('Data received:', data);
    } catch (error) {
      console.error('Request error:', error);
    }
  };
};

🔧 API

useAborter

Props

const { aborter } = new useAborter(props?: UseAborterProps);

Props Parameters

Parameter	Type	Description	Required
props	UseAborterProps	Aborter configuration options	No

UseAborterProps:

{
  /**
    Callback function for abort events.
    Associated with EventListener.onabort.
    It can be overridden via `aborter.listeners.onabort`
  */
  onAbort?: OnAbortCallback;

  /**
    A function called when the request state changes.
    It takes the new state as an argument.
    Can be overridden via `aborter.listeners.state.onstatechange`
  */
  onStateChange?: OnStateChangeCallback;

  /**
    A flag responsible for releasing resources.
    This includes unsubscribing, clearing fields, and removing references to passed callback functions.
    @default true
  */
  dispose?: boolean;
}

Properties

aborter: Aborter

Returns the Aborter instance.

const { aborter } = useAborter();

// Using signal in the request
fetch('/api/data', {
  signal: aborter.signal
});

requestState: RequestState

The current value of the request's state. May be undefined if the state has not yet been set.

The field is a react state associated with the aborter.listeners.state.value field.

Detailed documentation here

const { requestState } = useAborter();

console.log(requestState); // 'cancelled' / 'pending' / 'fulfilled' / 'rejected' / 'aborted'

useReusableAborter

Props

// The type can be found in `saborter/types`
const reusableAborter = new useReusableAborter(props?: ReusableAborterProps);

Props Parameters

Parameter	Type	Description	Required
props	ReusableAborterProps	ReusableAborter configuration options	No

ReusableAborterProps:

{
  /**
     * Determines which listeners are carried over when the abort signal is reset.
     * - If `true`, all listeners (both `onabort` and event listeners) are preserved.
     * - If `false`, no listeners are preserved.
     * - If an object, specific listener types can be enabled/disabled individually.
     */
    attractListeners?: boolean | AttractListeners;
}

Properties

signal: AbortSignal

Returns the AbortSignal associated with the current controller.

const reusableAborter = useReusableAborter();

// Using signal in the request
fetch('/api/data', {
  signal: reusableAborter.signal
});

Methods

abort(reason?): void

Parameters:

• reason?: any - the reason for aborting the request.

Immediately cancels the currently executing request.

Note

Can be called multiple times. Each call will restore the signal, and the aborted property will always be false.

🎯 Usage Examples

Basic Usage

import { useState } from 'react';
import { AbortError } from 'saborter';
import { useAborter } from '@saborter/react';

const Component = () => {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(false);

  // Create an Aborter instance via the hook
  const { aborter } = useAborter();

  // Use for the request
  const fetchData = async () => {
    try {
      setLoading(true);
      const user = await aborter.try((signal) => fetch('/api/user', { signal }));
      setUser(user);
    } catch (error) {
      if (error instanceof AbortError) {
        // An abort error will occur either when the `aborter.abort()` method is called or when the component is unmounted.
        console.error('Abort error:', error);
      }
      console.error('Request error:', error);
    } finally {
      setLoading(false);
    }
  };

  return <h1>{loading ? 'Loading...' : user.fullname}</h1>;
};

The AbortError initiator changed while unmounting the component

import { AbortError } from 'saborter';
import { useAborter } from '@saborter/react';

const Component = () => {
  const { aborter } = useAborter();

  const fetchData = async () => {
    try {
      const user = await aborter.try((signal) => fetch('/api/user', { signal }));
    } catch (error) {
      if (error instanceof AbortError) {
        console.error('Abort error initiator:', error.initiator); // 'component-unmounted';
      }
    }
  };
};

Using useReusableAborter

const aborter = new useReusableAborter();

// Get the current signal
const signal = aborter.signal;

// Attach listeners
signal.addEventListener('abort', () => console.log('Listener 1'));
signal.addEventListener('abort', () => console.log('Listener 2'), { once: true }); // won't be recovered

// Set onabort handler
signal.onabort = () => console.log('Onabort handler');

// First abort
aborter.abort('First reason');
// Output:
// Listener 1
// Listener 2 (once)
// Onabort handler

// The signal is now a fresh one, but the non‑once listeners and onabort are reattached
signal.addEventListener('abort', () => console.log('Listener 3')); // new listener, will survive next abort

// Second abort
aborter.abort('Second reason');
// Output:
// Listener 1
// Onabort handler
// Listener 3

📋 License

MIT License - see LICENSE for details.