xflight

Avoid redundant async calls by sharing inflight promises for the same key.

Description

xflight is a lightweight Node.js utility that manages inflight promises by key. It ensures that only one asynchronous operation per key is running at a time, returning the same promise for concurrent requests. This is useful for avoiding duplicate network or resource-intensive calls.

Features

• Prevents duplicate async operations for the same key
• Tracks start and check times for inflight items
• Cleans up after promise resolution or rejection
• 100% test coverage

Installation

1npm install xflight

Requirements

This package requires Node.js >= 20.

Usage

1const Xflight = require("xflight");
2const xfl = new Xflight();
3
4function fetchData(url) {
5  return xfl.promise(url, () => fetch(url));
6}
7
8// Multiple calls with the same URL will share the same promise if still pending
9fetchData("https://api.example.com/data").then(console.log);
10fetchData("https://api.example.com/data").then(console.log);

Usage in ESM and CommonJS

ESM (ECMAScript Modules)

1import Inflight from "xflight";
2
3const inflight = new Inflight();
4const key = "resource-1";
5
6// Deduplicate async calls
7const resultPromise = inflight.promise(key, () => fetch("https://api.example.com/data"));

CommonJS

1const Inflight = require("xflight").default;
2
3const inflight = new Inflight();
4// ... use as shown in examples above

API

new Xflight([PromiseImpl])

• PromiseImpl (optional): Custom Promise implementation (e.g., Bluebird, Aveazul, or native Promise).

Note: By default, the constructor will try to use Bluebird or Aveazul as the Promise implementation if they are available. If you want to always use the native Promise and skip these checks, pass the global Promise as the argument:

1const inflight = new Inflight(Promise);

Methods

promise(key, promiseFactory)

• key: Unique identifier for the inflight operation.
• promiseFactory: Function that returns a promise.
• Returns: The promise from promiseFactory, or the existing inflight promise for the key.

add(key, value, [now])

• Manually add an inflight item. value should be a promise.

get(key)

• Get the current inflight promise for a key, or undefined.

remove(key)

• Remove an inflight item by key.

isEmpty

• Boolean: true if no inflight items.

count

• Number of inflight items.

Timing Methods

• getStartTime(key): Get start time (ms since epoch) for a key.
• time(key, [now]) / elapseTime(key, [now]): Elapsed time since start.
• getCheckTime(key): Get last check time for a key.
• lastCheckTime(key, [now]) / elapseCheckTime(key, [now]): Elapsed time since last check.
• resetCheckTime(key, [now]): Reset last check time to now.

Testing

To run tests:

1npm test

Test coverage is enforced at 100% using nyc.

Examples

Basic Usage with promise

1import Inflight from "xflight";
2
3const inflight = new Inflight();
4const key = "resource-1";
5
6// Deduplicate async calls
7const resultPromise = inflight.promise(key, () => fetch("https://api.example.com/data"));
8// or, for clarity:
9const resultPromise2 = inflight.promise(key, function promiseFactory() {
10  return fetch("https://api.example.com/data");
11});

Manually Add and Get an Inflight Promise

1const promise = new Promise((resolve) => setTimeout(() => resolve("done"), 100));
2inflight.add("manual-key", promise);
3const inflightPromise = inflight.get("manual-key"); // Promise<string> | undefined

Remove an Inflight Item

1inflight.remove("manual-key");

Check if Inflight is Empty and Get Count

1console.log(inflight.isEmpty); // true or false
2console.log(inflight.count);   // number of inflight items

Timing Methods

1inflight.add("timed-key", new Promise(() => {}));
2const start = inflight.getStartTime("timed-key");
3const elapsed = inflight.time("timed-key");
4const elapsedAlias = inflight.elapseTime("timed-key");

Check Time Methods

1const check = inflight.getCheckTime("timed-key");
2const sinceLastCheck = inflight.lastCheckTime("timed-key");
3const sinceLastCheckAlias = inflight.elapseCheckTime("timed-key");

Reset Check Time

1// Reset for a specific key
2inflight.resetCheckTime("timed-key");
3// Reset for all inflight items
4inflight.resetCheckTime();

License

Apache-2.0

---

© Joel Chen