npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

react-executor

v0.0.29

Published

Asynchronous task execution and state management for React.

Readme

Asynchronous task execution and state management for React.

npm install --save-prod react-executor

🔰 Introduction

📢 Events and lifecycle

🔌 Plugins

👁️ Observables

⚛️ React integration

🚀 Server-side rendering

⚙️ Devtools

🍪 Cookbook

🔎 Resources

Introduction

An executor runs a task, stores the execution result, and provides access to that result. Tasks are callbacks that return a value or throw an error.

An Executor is created and managed by an ExecutorManager, which controls the executor's lifecycle:

import { ExecutorManager } from 'react-executor';

const manager = new ExecutorManager();

const rookyExecutor = manager.getOrCreate('rooky');
// ⮕ Executor<any>

Each executor has a unique key within the manager's scope. In this example, we created a new executor with the key 'rooky'. The manager creates a new executor when you call getOrCreate with a previously unused key. Subsequent calls with the same key return the same executor instance.

If you want to retrieve an existing executor by its key and avoid creating a new one if it doesn't exist, use get:

manager.get('bobby');
// ⮕ undefined

manager.get('rooky');
// ⮕ Executor<any>

The executor we created is unsettled, meaning it stores neither a value nor a failure reason:

rookyExecutor.isSettled;
// ⮕ false

An executor can be created with an initial value:

const bobbyExecutor = manager.getOrCreate('bobby', 42);

bobbyExecutor.isSettled;
// ⮕ true

// The result stored in the executor is a value
bobbyExecutor.isFulfilled;
// ⮕ true

bobbyExecutor.value;
// ⮕ 42

An initial value may be a task callback (which will be executed), a promise (which the executor will await), or any other value that immediately fulfills the executor. Read more in the Execute a task and the Settle an executor sections.

When creating an executor, you can also provide an array of plugins:

import retryRejected from 'react-executor/plugin/retryRejected';

const rookyExecutor = manager.getOrCreate('rooky', 42, [retryRejected()]);

Plugins can subscribe to executor events or modify the executor instance. If plugins settle the executor or start a task, the initial value isn't applied. Read more about plugins in the Plugins section.

Executor keys

Anything can be an executor key: a string, a number, an object, etc. By default, keys are considered identical if their JSON-serialized form is identical:

const manager = new ExecutorManager();

const userExecutor = manager.getOrCreate(['user', 123]);

manager.get(['user', 123]);
// ⮕ userExecutor

Pass the keyIdGenerator option to the ExecutorManager constructor to change how key IDs are computed. Keys with the same ID refer to the same executor. A key ID can be anything: a string, an object, etc.

If you're using objects as executor keys, then you may want to use a stable serialized form of keys as key IDs (where object properties are sorted alphabetically). In this case, use any library that supports stable JSON serialization:

import JSONMarshal from 'json-marshal';

const manager = new ExecutorManager({
  keyIdGenerator: key => JSONMarshal.stringify(key, { isStable: true }),
});

const rookyExecutor = manager.getOrCreate({ id: 123, name: 'Rooky' });
// ⮕ Executor<any>

// 🟡 Key properties are listed in a different order
manager.get({ name: 'Rooky', id: 123 });
// ⮕ rookyExecutor

[!TIP]
With additional configuration, json-marshal can stringify and parse any data structure.

If you want to use object references as executor key IDs, provide an identity function:

const manager = new ExecutorManager({
  keyIdGenerator: key => key,
});

const rookyKey = { id: 123 };

const rookyExecutor = manager.getOrCreate(rookyKey);

// 🟡 Executors are different because different objects were used as keys
manager.get(rookyKey) !== manager.getOrCreate({ id: 123 });

Execute a task

Let's execute a new task:

import { ExecutorManager, ExecutorTaskCallback } from 'react-executor';

const manager = new ExecutorManager();

const rookyExecutor = manager.getOrCreate('rooky');

const helloTask: ExecutorTaskCallback = async (signal, executor) => 'Hello';

const helloPromise = rookyExecutor.execute(helloTask);
// ⮕ Promise<any>

helloTask receives an AbortSignal and rookyExecutor as arguments. The signal is aborted if the task is aborted or replaced.

While tasks can be synchronous or asynchronous, executors always handle them in an asynchronous fashion. The executor is marked as pending immediately after execute is called:

// The executor is waiting for the task to complete
rookyExecutor.isPending;
// ⮕ true

helloPromise is resolved when the task completes:

await helloPromise;

// The executor doesn't have a pending task anymore
rookyExecutor.isPending;
// ⮕ false

// The result stored in the executor is a value
rookyExecutor.isFulfilled;
// ⮕ true

rookyExecutor.value;
// ⮕ 'Hello'

The executor keeps track of the latest task it has executed:

rookyExecutor.task;
// ⮕ helloTask

If a task throws an error (or returns a promise that rejects with an error), then the promise returned by execute is rejected. Until then, the executor stays pending:

const ooopsPromise = rookyExecutor.execute(() => {
  throw new Error('Ooops!');
});

rookyExecutor.isPending;
// ⮕ true

The executor becomes rejected as well after ooopsPromise is settled:

rookyExecutor.isRejected;
// ⮕ true

// The reason of the task failure
rookyExecutor.reason;
// ⮕ Error('Ooops!')

Executors always preserve the latest value and the latest reason. So even when the executor isPending, you can access the previous value or failure reason. Use isFulfilled and isRejected to check how the executor was settled the last time. An executor cannot be both fulfilled and rejected at the same time.

// Execute a new task
const byePromise = rookyExecutor.execute(() => 'Bye');

// 1️⃣ The executor is waiting for the task to complete
rookyExecutor.isPending;
// ⮕ true

// 2️⃣ The executor is still rejected after the previous task
rookyExecutor.isRejected;
// ⮕ true

rookyExecutor.reason;
// ⮕ Error('Ooops!')

// 3️⃣ The executor still holds the latest value, but it isn't fulfilled
rookyExecutor.isFulfilled;
// ⮕ false

rookyExecutor.value;
// ⮕ 'Hello'

The executor becomes fulfilled after byePromise settles:

await byePromise;

rookyExecutor.isFulfilled;
// ⮕ true

rookyExecutor.value;
// ⮕ 'Bye'

Abort a task

To abort a task prematurely, pass a signal to the execute method. Results of the aborted task are discarded, and the returned promise is rejected with the abort reason:

const abortController = new AbortController();

rookyExecutor.execute(async () => 'Hello', { signal: abortController.signal });

rookyExecutor.isPending;
// ⮕ true

abortController.abort();

rookyExecutor.isPending;
// ⮕ false

If the signal is already aborted, the task isn't executed.

You can also abort the pending task by aborting the executor itself:

rookyExecutor.abort();

If there's no pending task, then aborting an executor is a no-op.

When a task is aborted, the signal it received as an argument is aborted as well. Check the signal status to stop computations that are no longer needed.

For example, if you're fetching data from the server inside a task, you can pass the signal as a fetch option:

const byeTask: ExecutorTaskCallback = async (signal, executor) => {
  const response = await fetch('/bye', { signal });

  return response.json();
};

Replace a task

If a new task is executed while another task is pending, then the pending task is aborted and its results are discarded:

executor.execute(async signal => 'Pluto');

await executor.execute(async signal => 'Mars');

executor.value;
// ⮕ 'Mars'

Wait for a task to complete

In the Execute a task section we used the promise returned by Executor.execute to wait for a task to complete. While this approach lets you wait for a particular task to settle, usually you need to wait for the executor itself to become settled. The main point here is that the executor remains pending while multiple tasks replace one another.

getOrAwait waits until the executor is settled and has no pending task. Let's consider the scenario where a task is replaced with another task:

const planetExecutor = manager.getOrCreate('planet');

// The promise is resolved only when planetExecutor is settled
const planetPromise = planetExecutor.getOrAwait();

const marsPromise = planetExecutor.execute(async signal => 'Mars');

// 🟡 marsPromise is rejected, because the task was replaced
const venusPromise = planetExecutor.execute(async signal => 'Venus');

await planetPromise;
// ⮕ 'Venus'

In this example, marsPromise is rejected with an AbortError, and planetPromise is resolved only after the executor itself is settled and has no pending task.

Here's another example, where the executor waits to be settled:

const printerExecutor = manager.getOrCreate('printer');

printerExecutor.getOrAwait().then(value => {
  console.log(value);
});

// Prints "Hello" to console
printerExecutor.execute(() => 'Hello');

To stop waiting, pass a signal to getOrAwait. If the signal is aborted, the promise is rejected with the abort reason.

Retry the latest task

To retry the latest task, use retry:

const planets = ['Mars', 'Venus'];

await executor.execute(() => planets.shift());

executor.retry();

await executor.getOrAwait();

executor.value;
// ⮕ 'Venus'

If there's no latest task, or there's a pending task already, then calling retry is a no-op.

If you want to forcefully retry the latest task, then abort the executor first:

executor.abort();
executor.retry();

Settle an executor

While tasks are always handled in an asynchronous fashion, there are cases when an executor should be settled synchronously.

An executor can be synchronously fulfilled via resolve:

executor.resolve('Venus');

executor.isFulfilled;
// ⮕ true

executor.value;
// ⮕ 'Venus'

Or rejected via reject:

executor.reject(new Error('Ooops!'));

executor.isRejected;
// ⮕ true

executor.reason;
// ⮕ Error('Ooops!')

If there is a pending task then invoking resolve or reject will abort it.

If you pass a promise to resolve, the executor stays pending until the promise settles, and then stores its result:

const planetPromise = Promise.resolve('Mars');

executor.resolve(planetPromise);

// The executor is waiting for the promise to settle
executor.isPending;
// ⮕ true

await executor.getOrAwait();

executor.value;
// ⮕ 'Mars'

Clear an executor

After the executor becomes settled, it remains settled until it is cleared.

You can reset the executor back to its unsettled state using clear:

executor.clear();

Clearing an executor removes the stored value and reason, but doesn't affect the pending task execution and preserves the latest task that was executed.

Optimistic updates

Optimistic updates are a UX technique where the UI reflects the result of an action instantly, before the server has confirmed it. If the server succeeds, nothing changes visually. If the server fails, the UI rolls back to the value it showed before the action.

In React Executor, optimistic updates are first-class citizens and can be achieved by providing pendingValue in an executor task. When a task is submitted with a pendingValue, the executor is resolved with that value instantly, while the task is pending, and stores a checkpoint of the previous state.

const executor = useExecutor('meaningOfLife');

const handleClick = () => {
  executor.execute({
    callback: async signal => await getTheMeaningOfLife(signal),

    // 🟡 Executor is resolved with this value while the callback is pending
    pendingValue: 42,
  });
};

The UI reflects 42 the moment the button is clicked. What happens next depends on the outcome of the task:

  • If the task is fulfilled, then the executor is resolved with the task result.

  • If the task is rejected, then the checkpoint is restored and the executor is rejected with the task error, like after any other failed task. The value that the executor held before execute was called is still available as executor.value, so you can keep rendering it next to the error — no manual snapshot required.

  • If the task is aborted or replaced, then the checkpoint is restored as is: the executor gets back the value or the reason it held before, or becomes unsettled if it wasn't settled.

This means pendingValue is safe to use regardless of whether the executor has ever successfully fetched data.

[!NOTE] An optimistic task becomes the latest task, so plugins that retry the latest task would run it again. If the task is a mutation, set preserveLatestTask to keep the previous task as the latest one:

executor.execute({
  callback: async signal => await saveTheMeaningOfLife(42, signal),
  pendingValue: 42,
  preserveLatestTask: true,
});

Events and lifecycle

Executors publish various events when their state changes. To subscribe to executor events, use the subscribe method:

const manager = new ExecutorManager();

const rookyExecutor = manager.getOrCreate('rooky');

const unsubscribe = rookyExecutor.subscribe(event => {
  if (event.type === 'fulfilled') {
    // Handle the event here
  }
});

unsubscribe();

You can subscribe to the executor manager to receive events from all executors. For example, you can automatically retry any invalidated executor:

manager.subscribe(event => {
  if (event.type === 'invalidated') {
    event.target.retry();
  }
});

Both executors and managers can have multiple subscribers, and each subscriber receives events of the following types:

The executor was created, plugins were applied to it, and it was attached to the manager. Read more about plugins in the Plugins section.

The executor was detached: it was removed from the manager and all of its subscribers were unsubscribed. Also published if a plugin throws while the executor is being created, so plugins that were already applied can release their resources. Read more in the Detach an executor section.

The executor was inactive and became active: a consumer started to observe its state. Read more in the Activate an executor section.

The executor was active and became inactive: the last consumer stopped observing its state. Read more in the Activate an executor section.

The executor started to execute a task. You can find the latest task in the Executor.task property.

The executor was fulfilled with a value.

The executor was rejected with a reason.

The pending task was aborted. If the executor is still pending when this event is published, the aborted task was replaced with a new one.

Calling Executor.execute when handling this event may lead to a stack overflow. If you need to do so, execute the new task asynchronously, for example with queueMicrotask.

The executor was cleared and isn't settled anymore.

The executor result was invalidated.

The annotations of the executor were changed.

The configuration of a plugin applied to the executor was changed.

Activate an executor

Executors have an active status that tells whether the executor is observed by a consumer.

const deactivate = executor.activate();

executor.isActive;
// ⮕ true

deactivate();

executor.isActive;
// ⮕ false

If there are multiple consumers and each of them calls the activate method, then the executor remains active until all of them call their deactivate callbacks.

By default, marking an executor as active has no additional effect. Plugins can check the executor active status to skip or defer excessive updates and keep executor results up-to-date lazily. For example, consider a plugin that retries the latest task if an active executor becomes rejected:

const retryPlugin: ExecutorPlugin = executor => {
  executor.subscribe(event => {
    switch (event.type) {
      case 'rejected':
      case 'activated':
        if (executor.isActive && executor.isRejected) {
          executor.retry();
        }
        break;
    }
  });
};

const executor = manager.getOrCreate('rooky', heavyTask, [retryPlugin]);

executor.activate();

Now an executor would automatically retry the heavyTask if it fails. Read more about plugins in the Plugins section.

Invalidate results

Invalidate results stored in the executor:

executor.invalidate();

executor.isInvalidated;
// ⮕ true

After the executor is fulfilled, rejected, or cleared, it becomes valid:

executor.resolve('Okay');

executor.isInvalidated;
// ⮕ false

By default, invalidating an executor has no effect except marking it as invalidated. If the executor isn't settled, invalidate is a no-op.

Detach an executor

By default, executors that a manager has created are preserved indefinitely and are always available through get. This isn't always optimal, and you may want to detach an executor when it isn't needed anymore. Use detach in this case:

const executor = manager.getOrCreate('test');

manager.detach(executor.key);
// ⮕ true

All executor subscribers are now unsubscribed, and the executor is removed from the manager.

If an executor is still active, then it isn't detached, and detach returns false.

[!NOTE]
A pending task isn't aborted when the executor is detached. Use the abortDeactivated plugin to abort the task of a deactivated executor.

Plugins

Plugins are callbacks that are invoked only once when the executor is created by the manager. For example, you can create a plugin that aborts the pending task and detaches an executor when it is deactivated:

const detachPlugin: ExecutorPlugin = executor => {
  executor.subscribe(event => {
    if (event.type === 'deactivated') {
      executor.abort();
      executor.manager.detach(executor.key);
    }
  });
};

To apply a plugin, pass it to the ExecutorManager.getOrCreate or to the useExecutor hook:

const executor = manager.getOrCreate('test', undefined, [detachPlugin]);

const deactivate = executor.activate();

// The executor is instantly detached by the plugin
deactivate();

manager.get('test');
// ⮕ undefined

Make the manager apply a plugin to all executors by default:

const manager = new ExecutorManager({
  plugins: [detachPlugin],
});

If a plugin throws, the executor isn't added to the manager, and the error is rethrown. The pending task of the executor is aborted, and the detached event is published, so plugins that were already applied can release their resources.

[!IMPORTANT] Plugins are applied in array order. When combining plugins that react to the same events, order matters. A good rule of thumb: plugins that read state (e.g. syncBrowserStorage) should come before plugins that act on it (e.g. invalidateAfter), and cleanup plugins (e.g. abortDeactivated) before lifecycle plugins (e.g. detachDeactivated).

abortDeactivated

Aborts the pending task after the delay if the executor is deactivated.

import abortDeactivated from 'react-executor/plugin/abortDeactivated';

const executor = useExecutor('test', heavyTask, [
  abortDeactivated({ delay: 2_000 }),
]);

const deactivate = executor.activate();

// Aborts heavyTask in 2 seconds
deactivate();

If an executor is reactivated during this delay, the task won't be aborted. The executor must be activated at least once for this plugin to have an effect.

abortPendingAfter

Aborts the pending task with a TimeoutError if the task takes longer than the delay (in milliseconds).

import abortPendingAfter from 'react-executor/plugin/abortPendingAfter';

const executor = useExecutor('test', heavyTask, [
  abortPendingAfter(10_000),
]);

abortWhen

Aborts the pending task if the observable emits true.

For example, abort the pending task if the device is disconnected from the network for 5 seconds:

import abortWhen from 'react-executor/plugin/abortWhen';
import navigatorOffline from 'react-executor/observable/navigatorOffline';

const executor = useExecutor('test', heavyTask, [
  abortWhen(navigatorOffline, { delay: 5_000 }),
]);

By default, abortWhen only aborts the pending task. If isSustained is true, then after the delay has passed, every new task is aborted as soon as it starts, until the observable emits false:

const executor = useExecutor('test', heavyTask, [
  abortWhen(navigatorOffline, {
    delay: 5_000,

    // 🟡 Abort every newly executed task
    isSustained: true,
  }),
]);

Read more about observables in the Observables section.

detachDeactivated

Detaches the executor after the delay if the executor is deactivated.

import detachDeactivated from 'react-executor/plugin/detachDeactivated';

const executor = useExecutor('test', heavyTask, [
  detachDeactivated({ delay: 2_000 }),
]);

const deactivate = executor.activate();

// Executor is detached in 2 seconds
deactivate();

If an executor is reactivated during this delay, the executor won't be detached. The executor must be activated at least once for this plugin to have an effect.

This plugin doesn't abort the pending task when an executor is detached. Use abortDeactivated to do the job:

import abortDeactivated from 'react-executor/plugin/abortDeactivated';
import detachDeactivated from 'react-executor/plugin/detachDeactivated';

const executor = useExecutor('test', heavyTask, [
  abortDeactivated({ delay: 2_000 }),
  detachDeactivated({ delay: 2_000 }),
]);

const deactivate = executor.activate();

// The heavyTask is aborted and the executor is detached in 2 seconds
deactivate();

detachInactive

Detaches the executor after a delay if the executor is inactive.

Detach an executor if it wasn't activated during the first 5 seconds after being created:

import detachInactive from 'react-executor/plugin/detachInactive';

const executor = useExecutor('test', 42, [
  detachInactive({ delayBeforeActivated: 5_000 }),
]);

Detach an executor if it stays inactive for 5 seconds after being deactivated:

const executor = useExecutor('test', 42, [
  detachInactive({ delayAfterDeactivated: 5_000 }),
]);

const deactivate = executor.activate();

// The executor is detached in 5 seconds
deactivate();

invalidateAfter

Invalidates the executor result after a delay (in milliseconds).

import invalidateAfter from 'react-executor/plugin/invalidateAfter';

// The executor is invalidated in 2 seconds
const executor = useExecutor('test', 42, [
  invalidateAfter(2_000),
]);

The delay is counted from the moment the executor was settled, and restarts every time the executor is settled again.

invalidateByPeers

Invalidates the executor result if a peer executor is fulfilled or invalidated.

import invalidateByPeers from 'react-executor/plugin/invalidateByPeers';

const cheeseExecutor = useExecutor('cheese', 'Burrata', [
  invalidateByPeers(executor => executor.key === 'bread'),
]);

const breadExecutor = useExecutor('bread');

// cheeseExecutor is invalidated
breadExecutor.resolve('Ciabatta');

Provide an array of executors as peers:

const breadExecutor = useExecutor('bread');

const cheeseExecutor = useExecutor('cheese', 'Burrata', [
  invalidateByPeers([breadExecutor]),
]);

// cheeseExecutor is invalidated
breadExecutor.resolve('Ciabatta');

[!WARNING] Peers must not invalidate each other in a cycle, otherwise their tasks can re-run forever. Read more in Derived executors.

invalidatePeers

Invalidates peer executors if the executor is fulfilled or invalidated.

import invalidatePeers from 'react-executor/plugin/invalidatePeers';

const cheeseExecutor = useExecutor('cheese', 'Burrata', [
  invalidatePeers(executor => executor.key === 'bread'),
]);

const breadExecutor = useExecutor('bread', 'Focaccia');

// breadExecutor is invalidated
cheeseExecutor.resolve('Mozzarella');

Provide an array of executors as peers:

const breadExecutor = useExecutor('bread', 'Focaccia');

const cheeseExecutor = useExecutor('cheese', undefined, [
  invalidatePeers([breadExecutor]),
]);

// breadExecutor is invalidated
cheeseExecutor.resolve('Mozzarella');

[!WARNING] Peers must not invalidate each other in a cycle, otherwise their tasks can re-run forever. Read more in Derived executors.

invalidateWhen

Invalidates the executor result when the observable switches from false to true.

For example, if the device was offline for at least 5 seconds, then the executor is invalidated when the device goes back online:

import invalidateWhen from 'react-executor/plugin/invalidateWhen';
import navigatorOnline from 'react-executor/observable/navigatorOnline';

const executor = useExecutor('test', heavyTask, [
  invalidateWhen(navigatorOnline, { delay: 5_000 }),
]);

Combining multiple plugins, you can set up a complex executor behaviour. For example, let's create an executor that follows these requirements:

  1. Executes the task every 5 seconds.
  2. Aborts the pending task if the page is hidden for more than 10 seconds.
  3. Aborts instantly if the device goes offline.
  4. Resumes the periodic task execution if the page becomes visible or the device goes back online.
import { useExecutor } from 'react-executor';
import navigatorOffline from 'react-executor/observable/navigatorOffline';
import navigatorOnline from 'react-executor/observable/navigatorOnline';
import windowBlurred from 'react-executor/observable/windowBlurred';
import windowFocused from 'react-executor/observable/windowFocused';
import abortWhen from 'react-executor/plugin/abortWhen';
import invalidateWhen from 'react-executor/plugin/invalidateWhen';
import retryFulfilled from 'react-executor/plugin/retryFulfilled';
import retryInvalidated from 'react-executor/plugin/retryInvalidated';

useExecutor('test', heavyTask, [
  retryInvalidated(),

  // Retry the task every 5 seconds if it succeeds
  retryFulfilled({ delay: 5_000 }),

  // Abort the task if the page is hidden for at least 10 seconds
  abortWhen(windowBlurred, { delay: 10_000 }),

  // Abort the pending task if the device is disconnected from the network
  abortWhen(navigatorOffline),

  // Invalidate results when the page was hidden and then becomes visible
  invalidateWhen(windowFocused),

  // Invalidate results if the device was disconnected from the network
  // and then connects again
  invalidateWhen(navigatorOnline),
]);

lazyTask

Sets the latest task of an executor without executing it.

This plugin is useful when you have a static initial value and a task that can update this value later:

import lazyTask from 'react-executor/plugin/lazyTask';
import retryInvalidated from 'react-executor/plugin/retryInvalidated';

const executor = useExecutor('meaningOfLife', 42, [
  lazyTask(async () => await getTheMeaningOfLife()),
  retryInvalidated(),
]);

executor is created with the value set to 42. The getTheMeaningOfLife task isn't executed until the executor is invalidated (thanks to the retryInvalidated plugin):

executor.invalidate();

rejectPendingAfter

Aborts the pending task and rejects the executor with a TimeoutError if the task takes longer than the delay (in milliseconds).

import rejectPendingAfter from 'react-executor/plugin/rejectPendingAfter';

const executor = useExecutor('test', heavyTask, [
  rejectPendingAfter(10_000),
]);

resolveBy

Resolves the executor with values emitted by an Observable. If the observable emits a promise, the executor is resolved with its result.

import { Observable } from 'react-executor';
import resolveBy from 'react-executor/plugin/resolveBy';

const observable: Observable<string> = {
  subscribe(listener) {
    // Call the listener when value is changed
    const timer = setTimeout(listener, 1_000, 'Venus');

    return () => {
      // Unsubscribe the listener
      clearTimeout(timer);
    };
  },
};

const executor = useExecutor('planet', 'Mars', [
  resolveBy(observable),
]);

PubSub can be used to decouple the lazy data source from the executor:

import { PubSub } from 'parallel-universe';

const pubSub = new PubSub<string>();

const executor = useExecutor('planet', 'Mars', [
  resolveBy(pubSub),
]);

pubSub.publish('Venus');

executor.value; // ⮕ 'Venus'

retryActivated

Retries the latest task if the executor is activated.

import retryActivated from 'react-executor/plugin/retryActivated';

const executor = useExecutor('test', heavyTask, [
  retryActivated(),
]);

// Retries the task
executor.activate();

Set the minimum time (in milliseconds) that must pass after the executor was settled for an activation to retry the latest task:

const executor = useExecutor('test', heavyTask, [
  retryActivated({ delayAfterSettled: 5_000 }),
]);

// Doesn't retry the task if the executor was settled less than 5 seconds ago
executor.activate();

retryFulfilled

Retries the latest task after a delay every time the executor is fulfilled.

import retryFulfilled from 'react-executor/plugin/retryFulfilled';

const executor = useExecutor('test', heavyTask, [
  retryFulfilled(),
]);

If the task fails, is aborted, or if an executor is deactivated then the plugin stops the retry process.

With the default configuration, the plugin would infinitely retry the task of an active executor with a 5-second delay between retries. This is effectively a decent polling strategy that kicks in only if someone is actually using an executor.

Specify the number of times the task should be re-executed if it succeeds:

retryFulfilled({ count: 3 });

Specify the delay (in milliseconds) between retries:

retryFulfilled({ count: 3, delay: 5_000 });

Provide a function that returns the delay depending on the number of retries:

retryFulfilled({
  count: 5,
  delay: (index, executor) => 1000 * index,
});

By default, retryFulfilled doesn't retry inactive executors. The executor is retried only after it becomes active.

To retry the latest task regardless of the executor activation status:

retryFulfilled({ isEager: true });

Use retryFulfilled in conjunction with retryRejected to create a polling sequence. For example, this configuration would infinitely poll the heavyTask and would retry failed iterations with an exponential backoff and no more than 5 times in a row:

const executor = useExecutor('test', heavyTask, [
  retryFulfilled(),
  retryRejected({ count: 5 }),
]);

You can also use a combination of invalidateAfter and retryInvalidated to poll infinitely, regardless of the result of the previous iteration:

const executor = useExecutor('test', heavyTask, [
  invalidateAfter(5_000),
  retryInvalidated(),
]);

retryInvalidated

Retries the latest task if the executor is invalidated.

import retryInvalidated from 'react-executor/plugin/retryInvalidated';

const executor = useExecutor('test', heavyTask, [
  retryInvalidated(),
]);

executor.activate();

Combine this plugin with invalidateByPeers to automatically retry this executor when an executor that it depends on is fulfilled or invalidated:

import { ExecutorTaskCallback, useExecutor } from 'react-executor';
import invalidateByPeers from 'react-executor/plugin/invalidateByPeers';

const fetchCheese: ExecutorTaskCallback = async (signal, executor) => {
  // Wait for the breadExecutor to be created
  const breadExecutor = await executor.manager.getOrAwait('bread', { signal });

  // Wait for the breadExecutor to be settled
  const bread = await breadExecutor.getOrAwait({ signal });

  // Choose the best cheese for this bread
  return bread === 'Ciabatta' ? 'Mozzarella' : 'Burrata';
};

const cheeseExecutor = useExecutor('cheese', fetchCheese, [
  invalidateByPeers(executor => executor.key === 'bread'),
  retryInvalidated(),
]);

const breadExecutor = useExecutor('bread');

// cheeseExecutor is fulfilled with 'Mozzarella'
breadExecutor.resolve('Ciabatta');

// 🟡 Later, cheeseExecutor is invalidated and re-fetches cheese
breadExecutor.resolve('Focaccia');

Read more about dependent tasks.

By default, retryInvalidated doesn't retry inactive executors. The executor is retried only after it becomes active.

To retry the latest task regardless of the executor activation status:

retryInvalidated({ isEager: true });

retryRejected

Retries the latest task after a delay if the executor is rejected.

import retryRejected from 'react-executor/plugin/retryRejected';

const executor = useExecutor('test', heavyTask, [
  retryRejected(),
]);

executor.activate();

If the task succeeds, is aborted, or if an executor is deactivated then the plugin stops the retry process.

With the default configuration, the plugin would retry the task 3 times with an exponential backoff between retries: 1000, 1800, and 3240 milliseconds.

Specify the number of times the task should be re-executed if it fails:

retryRejected({ count: 3 });

Specify the delay (in milliseconds) between retries:

retryRejected({ count: 3, delay: 5_000 });

Provide a function that returns the delay depending on the number of retries:

retryRejected({
  count: 5,
  delay: (index, executor) => 1000 * 1.8 ** index,
});

By default, retryRejected doesn't retry inactive executors. The executor is retried only after it becomes active.

To retry the latest task regardless of the executor activation status:

retryRejected({ isEager: true });

retryWhen

Retries the latest task when the observable switches from false to true.

For example, the executor would retry the heavyTask after the device has been back online for 5 seconds:

import retryWhen from 'react-executor/plugin/retryWhen';
import navigatorOnline from 'react-executor/observable/navigatorOnline';

const executor = useExecutor('test', heavyTask, [
  retryWhen(navigatorOnline, { delay: 5_000 }),
]);

syncBrowserStorage

Synchronizes the executor state with a localStorage or sessionStorage item. No-op in a non-browser environment.

import syncBrowserStorage from 'react-executor/plugin/syncBrowserStorage';

const executor = useExecutor('test', 42, [syncBrowserStorage()]);

With this plugin, you can synchronize the executor state across multiple browser tabs in just one line.

[!IMPORTANT]
If the executor is detached, then the corresponding item is removed from the storage.

By default, an executor state is serialized using JSON. If your executor stores a value that may contain circular references, or non-serializable data like BigInt, use a custom serializer.

Here's how you can enable serialization of objects with circular references:

import JSONMarshal from 'json-marshal';

const executor = useExecutor('test', 42, [
  syncBrowserStorage({
    serializer: JSONMarshal,
  }),
]);

[!TIP]
With additional configuration, json-marshal can stringify and parse any data structure.

By default, the syncBrowserStorage plugin uses the executor key ID as a storage key, which must be a string. You can provide a custom key via the storageKey option:

useExecutor('test', 42, [syncBrowserStorage({ storageKey: 'hello' })]);

syncExternalStore

Synchronizes the executor state with an external store. The store is updated when the executor state changes, and the executor is updated when the stored state changes.

Here's a minimal external store example:

import { useExecutor, ExecutorState } from 'react-executor';
import syncExternalStore, { ExternalStore } from 'react-executor/plugin/syncExternalStore';

let myStoredState: ExecutorState | null = null;

const myStore: ExternalStore<ExecutorState> = {
  get() {
    return myStoredState;
  },

  subscribe(listener) {
    // Place subscription logic here
    return () => {};
  },
};

const myExecutor = useExecutor('test', 42, [syncExternalStore(myStore)]);

When the executor is settled, cleared, invalidated or annotated, the plugin calls the ExternalStore.set method on the store.

When the executor is detached, the plugin calls the ExternalStore.delete method on the store.

Read-only stores, like the one above, can omit set and delete.

Prefer syncBrowserStorage if you want to persist the executor state in localStorage or sessionStorage.

Observables

Observables are values that can be passed to the abortWhen, invalidateWhen, retryWhen, and resolveBy plugins. They follow a minimal interface: a subscribe method that subscribes a listener to the values emitted by the observable, and returns a callback that unsubscribes the listener. You can pass any object matching this interface — including third-party reactive primitives — as an observable.

Four built-in observables are provided out of the box. Each of them emits the current state to a listener right after it subscribes.

navigatorOnline

Emits true when the device is connected to the network, and false when it is disconnected.

import navigatorOnline from 'react-executor/observable/navigatorOnline';
import retryWhen from 'react-executor/plugin/retryWhen';

const executor = useExecutor('test', heavyTask, [retryWhen(navigatorOnline)]);

navigatorOffline

The inverse of navigatorOnline. Emits true when the device is disconnected.

import navigatorOffline from 'react-executor/observable/navigatorOffline';
import abortWhen from 'react-executor/plugin/abortWhen';

const executor = useExecutor('test', heavyTask, [abortWhen(navigatorOffline)]);

windowFocused

Emits true when the page becomes visible or the window receives focus, and false when the page becomes hidden.

import windowFocused from 'react-executor/observable/windowFocused';
import retryWhen from 'react-executor/plugin/retryWhen';

const executor = useExecutor('test', heavyTask, [retryWhen(windowFocused)]);

windowBlurred

The inverse of windowFocused. Emits true when the page becomes hidden.

import windowBlurred from 'react-executor/observable/windowBlurred';
import abortWhen from 'react-executor/plugin/abortWhen';

const executor = useExecutor('test', heavyTask, [abortWhen(windowBlurred)]);

React integration

In the basic scenario, to use executors in your React app, you don't need any additional configuration, just use the useExecutor hook right away:

import { useExecutor } from 'react-executor';

function User(props: { userId: string }) {
  const executor = useExecutor(['user', props.userId], async signal => {
    // Fetch the user from the server
  });

  if (executor.isPending) {
    return 'Loading';
  }

  // Render the user from the executor.value
}

Every time the executor's state is changed, the component is re-rendered. The executor returned from the hook is activated after mount and deactivated before unmount.

The hook has the exact same signature as the ExecutorManager.getOrCreate method, described in the Introduction section.

[!TIP]
Check out the live example of the TODO app that employs React Executor.

You can use executors both inside and outside the rendering process. To do this, provide a custom ExecutorManager through the context:

import { ExecutorManager, ExecutorManagerProvider } from 'react-executor';

const manager = new ExecutorManager();

const App = () => (
  <ExecutorManagerProvider value={manager}>
    <User userId={'28'} />
  </ExecutorManagerProvider>
);

Now you can use manager to access all the same executors that are available through the useExecutor hook:

const executor = manager.get(['user', '28']);

If you want to have access to an executor in a component, but don't want to re-render the component when the executor's state is changed, use the useExecutorManager hook:

const accountExecutor = useExecutorManager().getOrCreate('account');

You can execute a task in response to a user action, for example when a user clicks a button:

const executor = useExecutor('test');

const handleClick = () => {
  executor.execute(async signal => {
    // Handle the task
  });
};

If you want the executor to run a task on the client only, then execute the task in an effect:

const executor = useExecutor('test');

useEffect(() => {
  executor.execute(async signal => {
    // Handle the task
  });
}, []);

Suspense

Executors support the fetch-as-you-render approach and can be integrated with React Suspense. To suspend rendering while an executor is pending, use the useExecutorSuspense hook:

import { useExecutor, useExecutorSuspense } from 'react-executor';

function Account() {
  const accountExecutor = useExecutor('account', signal => {
    // Fetch an account from a server
  });

  // Suspend rendering if accountExecutor is pending and isn't fulfilled
  const account = useExecutorSuspense(accountExecutor).get();
}

Now when the Account component is rendered, it would be suspended until the accountExecutor is settled:

import { Suspense } from 'react';

const App = () => (
  <Suspense fallback={'Loading'}>
    <Account />
  </Suspense>
);

Executors can run tasks in parallel and rendering is suspended until both of them are settled:

const cheeseExecutor = useExecutor('cheese', buyCheeseTask);
const breadExecutor = useExecutor('bread', bakeBreadTask);

const cheese = useExecutorSuspense(cheeseExecutor).get();
const bread = useExecutorSuspense(breadExecutor).get();

External executors

You can use executors created outside the rendering process in your components, and re-render or suspend your components when such executors are updated:

const manager = new ExecutorManager();

// 1️⃣ Create an executor
const accountExecutor = manager.getOrCreate('account', signal => {
  // Fetch an account from a server
});

function Account() {
  // 2️⃣ Re-render a component when accountExecutor is updated
  useExecutorSubscription(accountExecutor);

  // 3️⃣ Suspend rendering if accountExecutor is pending and isn't fulfilled
  const account = useExecutorSuspense(accountExecutor).get();
}

Server-side rendering

[!TIP]
Check out the live example of streaming SSR with React Executor.

Executors can be hydrated on the client after being settled on the server.

To enable hydration on the client, create the executor manager and provide it through a context:

import { hydrateRoot } from 'react-dom/client';
import { hydrateExecutorManager, ExecutorManager, ExecutorManagerProvider } from 'react-executor';

const manager = new ExecutorManager();

// 🟡 Hydrates executors on the client with the server data
hydrateExecutorManager(manager);

hydrateRoot(
  document,
  <ExecutorManagerProvider value={manager}>
    <App />
  </ExecutorManagerProvider>
);

Here, App is the component that renders your application. Inside the App you can use useExecutor and useExecutorSuspense to load your data.

hydrateExecutorManager applies the executor states sent by the server to executors of the given manager. Only one manager can be hydrated on a page: call hydrateExecutorManager only once on the client-side, otherwise it throws an error.

On the server-side, you can either render your app contents as a string and send it to the client in one go, or stream the contents.

Render to string

Use SSRExecutorManager to render your app as an HTML string:

import { createServer } from 'node:http';
import { renderToString } from 'react-dom/server';
import { ExecutorManagerProvider } from 'react-executor';
import { SSRExecutorManager } from 'react-executor/ssr';

const server = createServer(async (request, response) => {
  // 1️⃣ Create a new manager for each request
  const manager = new SSRExecutorManager();

  // 2️⃣ Re-render until there are no more changes
  let html;
  do {
    html = renderToString(
      <ExecutorManagerProvider value={manager}>
        <App />
      </ExecutorManagerProvider>
    );
  } while (await manager.hasChanges());

  // 3️⃣ Inject the hydration script
  html = html.replace('</body>', manager.nextHydrationChunk() + '</body>');

  response.setHeader('Content-Type', 'text/html');
  response.end(html);
});

server.listen(8080);

A new executor manager must be created for each request, so the results that are stored in executors are served in response to a particular request.

hasChanges waits until no executors are pending, and resolves with true if the state of any executor has changed while it waited, or false otherwise.

[!WARNING] If a plugin keeps re-executing tasks during SSR, the promise returned by hasChanges is rejected after maxRetries attempts (10 by default). Avoid such plugins in SSR. If your data is loaded in many sequential steps, pass a greater maxRetries, for example manager.hasChanges(20).

nextHydrationChunk returns a <script> tag that sends the client the states of executors that have changed since they were last sent, or an empty string if there are no such changes. On the client, these states are applied to the manager passed to hydrateExecutorManager.

Streaming SSR

React can stream parts of your app while it is being rendered. You can inject React Executor hydration chunks into the React stream.

import { createServer } from 'node:http';
import { Writable } from 'node:stream';
import { renderToReadableStream } from 'react-dom/server';
import { ExecutorManagerProvider } from 'react-executor';
import { SSRExecutorManager } from 'react-executor/ssr';

const server = createServer(async (request, response) => {
  // 1️⃣ Create a new manager for each request
  const manager = new SSRExecutorManager();

  const stream = await renderToReadableStream(
    <ExecutorManagerProvider value={manager}>
      <App />
    </ExecutorManagerProvider>
  );

  const hydrator = new TransformStream({
    transform(chunk, controller) {
      controller.enqueue(chunk);
      controller.enqueue(manager.nextHydrationChunk());
    },
  });

  response.setHeader('Content-Type', 'text/html');

  // 2️⃣ Inject the hydration chunks into the react stream
  await stream.pipeThrough(hydrator).pipeTo(Writable.toWeb(response));

  response.end();
});

server.listen(8080);

hydrator injects React Executor hydration chunks into the React stream.

In the App component, use the combination of <Suspense>, useExecutor and useExecutorSuspense to suspend rendering while executors process their tasks:

function App() {
  return (
    <html>
      <head />
      <body>
        <Suspense fallback={'Loading'}>
          <Hello />
        </Suspense>
      </body>
    </html>
  );
}

function Hello() {
  const helloExecutor = useExecutor('hello', async () => {
    // Asynchronously return the result
    return 'Hello, Paul!';
  });

  // 🟡 Suspend rendering until helloExecutor is settled
  useExecutorSuspense(helloExecutor);

  return helloExecutor.get();
}

If the App is rendered in streaming mode, it would first show "Loading" and after the executor is settled, it would update to "Hello, Paul!". In the meantime helloExecutor on the client would be hydrated with the data from the server.

State serialization

By default, executor keys and states are serialized using JSON, which has quite a few limitations. If your executor stores a value that may contain circular references, or non-serializable data like BigInt, then a custom state serializer must be provided.

On the server, pass a serializer option to SSRExecutorManager:

import JSONMarshal from 'json-marshal';
import { SSRExecutorManager } from 'react-executor/ssr';

const manager = new SSRExecutorManager({ serializer: JSONMarshal });

On the client, pass the same serializer to hydrateExecutorManager:

import JSONMarshal from 'json-marshal';
import { hydrateRoot } from 'react-dom/client';
import { hydrateExecutorManager, ExecutorManager, ExecutorManagerProvider } from 'react-executor';

const manager = new ExecutorManager();

hydrateExecutorManager(manager, { serializer: JSONMarshal });

hydrateRoot(
  document,
  <ExecutorManagerProvider value={manager}>
    <App />
  </ExecutorManagerProvider>
);

[!TIP]
With additional configuration, json-marshal can stringify and parse any data structure.

Content-Security-Policy support

By default, nextHydrationChunk returns an inline <script> tag without any attributes. To allow hydration scripts under the script-src directive of the Content-Security-Policy header, provide the nonce option to SSRExecutorManager:

const manager = new SSRExecutorManager({ nonce: '2726c7f26c' });

Send the header with this nonce in the server response:

Content-Security-Policy: script-src 'nonce-2726c7f26c'

Next.js integration

[!TIP]
Check out the live example of the Next.js app that showcases streaming SSR with React Executor.

To enable client hydration in Next.js, use the @react-executor/next package.

First, provide an ExecutorManager:

// providers.tsx
'use client';

import { ExecutorHydrator } from '@react-executor/next';
import { ReactNode } from 'react';
import { hydrateExecutorManager, ExecutorManager, ExecutorManagerProvider } from 'react-executor';
import { SSRExecutorManager } from 'react-executor/ssr';

let manager: ExecutorManager | undefined;

if (typeof window !== 'undefined') {
  manager = new ExecutorManager();
  hydrateExecutorManager(manager);
}

export function Providers(props: { children: ReactNode }) {
  return (
    <ExecutorManagerProvider value={manager || new SSRExecutorManager()}>
      <ExecutorHydrator>{props.children}</ExecutorHydrator>
    </ExecutorManagerProvider>
  );
}

ExecutorHydrator propagates server-rendered executor state to the client. You can configure how dehydrated state is serialized on the server and deserialized on the client. By default, JSON is used.

Enable providers in the root layout:

// layout.tsx
import { ReactNode } from 'react';
import { Providers } from './providers';

export default function (props: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Providers>{props.children}</Providers>
      </body>
    </html>
  );
}

Devtools

To inspect the current state of executors in your app, install the React Executor Devtools browser extension and open its panel in the Chrome Developer Tools:

The devtools extension doesn't require any additional configuration and lets you inspect all executors on the page, regardless of whether they were rendered through React or created outside of the rendering process.

To disable devtools, create a custom ExecutorManager:

import { ExecutorManager } from 'react-executor';

const opaqueExecutorManager = new ExecutorManager({
  devtools: false,
});

Executors created by the opaqueExecutorManager won't be visible in the React Executor Devtools extension. It is recommended to use this setting in production.

The extension source can be fo