xflight 1.0.0 → 2.0.0

package/README.md

@@ -1,9 +1,173 @@
 # 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
+
+```bash
+npm install xflight
+```
+
+## Usage
+
 ```js
 const Xflight = require("xflight");
 const xfl = new Xflight();
-xfl.promise(url, () => {
-  return fetch(url);
+
+function fetchData(url) {
+  return xfl.promise(url, () => fetch(url));
+}
+
+// Multiple calls with the same URL will share the same promise if still pending
+fetchData("https://api.example.com/data").then(console.log);
+fetchData("https://api.example.com/data").then(console.log);
+```
+
+## Usage in ESM and CommonJS
+
+### ESM (ECMAScript Modules)
+```ts
+import Inflight from "xflight";
+
+const inflight = new Inflight();
+const key = "resource-1";
+
+// Deduplicate async calls
+const resultPromise = inflight.promise(key, () => fetch("https://api.example.com/data"));
+```
+
+### CommonJS
+```js
+const Inflight = require("xflight").default;
+
+const inflight = new Inflight();
+// ... 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:
+
+```ts
+const 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:
+
+```bash
+npm test
+```
+
+Test coverage is enforced at 100% using `nyc`.
+
+
+## Examples
+
+### Basic Usage with `promise`
+```ts
+import Inflight from "xflight";
+
+const inflight = new Inflight();
+const key = "resource-1";
+
+// Deduplicate async calls
+const resultPromise = inflight.promise(key, () => fetch("https://api.example.com/data"));
+// or, for clarity:
+const resultPromise2 = inflight.promise(key, function promiseFactory() {
+  return fetch("https://api.example.com/data");
 });
 ```
+
+### Manually Add and Get an Inflight Promise
+```ts
+const promise = new Promise((resolve) => setTimeout(() => resolve("done"), 100));
+inflight.add("manual-key", promise);
+const inflightPromise = inflight.get("manual-key"); // Promise<string> | undefined
+```
+
+### Remove an Inflight Item
+```ts
+inflight.remove("manual-key");
+```
+
+### Check if Inflight is Empty and Get Count
+```ts
+console.log(inflight.isEmpty); // true or false
+console.log(inflight.count);   // number of inflight items
+```
+
+### Timing Methods
+```ts
+inflight.add("timed-key", new Promise(() => {}));
+const start = inflight.getStartTime("timed-key");
+const elapsed = inflight.time("timed-key");
+const elapsedAlias = inflight.elapseTime("timed-key");
+```
+
+### Check Time Methods
+```ts
+const check = inflight.getCheckTime("timed-key");
+const sinceLastCheck = inflight.lastCheckTime("timed-key");
+const sinceLastCheckAlias = inflight.elapseCheckTime("timed-key");
+```
+
+### Reset Check Time
+```ts
+// Reset for a specific key
+inflight.resetCheckTime("timed-key");
+// Reset for all inflight items
+inflight.resetCheckTime();
+```
+
+
+## License
+
+Apache-2.0
+
+---
+
+© Joel Chen

package/package.json

@@ -1,10 +1,19 @@
 {
   "name": "xflight",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "Handle inflight promise to avoid async duplication",
-  "main": "lib/index.js",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist-esm/esm/index.js",
+      "require": "./dist-cjs/cjs/index.cjs"
+    }
+  },
   "scripts": {
-    "test": "clap check"
+    "test": "vitest run",
+    "test:ui": "vitest --ui",
+    "coverage": "vitest run --coverage",
+    "build": "rm -rf dist-* && tsc --build tsconfig.esm.json && tsc --build tsconfig.cjs.json && ts2mjs --cjs --remove-source --skip-ts dist-cjs"
   },
   "repository": {
     "type": "git",
@@ -20,10 +29,16 @@
   "author": "Joel Chen",
   "license": "Apache-2.0",
   "devDependencies": {
-    "electrode-archetype-njs-module-dev": "^3.0.0"
+    "@types/node": "^22.15.29",
+    "@vitest/coverage-v8": "^3.2.0",
+    "@xarc/run": "^1.1.2",
+    "tsx": "^4.19.4",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.0",
+    "ts2mjs": "github:jchip/ts2mjs#main"
   },
   "dependencies": {
-    "optional-require": "^1.0.0"
+    "optional-require": "^2.0.1"
   },
   "nyc": {
     "all": true,

package/lib/index.js

@@ -1,113 +0,0 @@
-"use strict";
-
-const assert = require("assert");
-const Promise = require("optional-require")(require)("bluebird", { default: global.Promise });
-
-class Inflight {
-  constructor(xPromise) {
-    this._count = 0;
-    this._inflights = {};
-    this.Promise = xPromise || Promise;
-  }
-
-  promise(key, func) {
-    const f = this._inflights[key];
-    if (f) {
-      return f.value;
-    }
-
-    const remove = () => this.remove(key);
-
-    try {
-      const p = func();
-      assert(p && p.then, `xflight: func for key ${key} didn't return a promise`);
-      this.add(key, p).then(remove, remove);
-      return p;
-    } catch (err) {
-      return this.Promise.reject(err);
-    }
-  }
-
-  add(key, value, now) {
-    assert(this._inflights[key] === undefined, `xflight: item ${key} already exist`);
-    this._count++;
-    now = now || Date.now();
-    this._inflights[key] = { start: now, lastXTime: now, value };
-
-    return value;
-  }
-
-  get(key) {
-    const x = this._inflights[key];
-    return x && x.value;
-  }
-
-  remove(key) {
-    assert(this._inflights[key] !== undefined, `xflight: removing non-existing item ${key}`);
-    assert(
-      this._count > 0,
-      `xflight: removing item ${key} but list is empty - count ${this._count}`
-    );
-
-    this._count--;
-
-    if (this._count === 0) {
-      this._inflights = {};
-    } else {
-      this._inflights[key] = undefined;
-    }
-  }
-
-  get isEmpty() {
-    return this._count === 0;
-  }
-
-  get count() {
-    return this._count;
-  }
-
-  getStartTime(key) {
-    const x = this._inflights[key];
-    return x && x.start;
-  }
-
-  time(key, now) {
-    const x = this._inflights[key];
-    if (x) {
-      return (now || Date.now()) - x.start;
-    }
-    return -1;
-  }
-
-  elapseTime(key, now) {
-    return this.time(key, now);
-  }
-
-  getCheckTime(key) {
-    const x = this._inflights[key];
-    return x && x.lastXTime;
-  }
-
-  lastCheckTime(key, now) {
-    const x = this._inflights[key];
-    if (x) {
-      const t = (now || Date.now()) - x.lastXTime;
-      return t;
-    }
-    return -1;
-  }
-
-  elapseCheckTime(key, now) {
-    return this.lastCheckTime(key, now);
-  }
-
-  resetCheckTime(key, now) {
-    const x = this._inflights[key];
-    if (x) {
-      x.lastXTime = now || Date.now();
-    }
-    return this;
-  }
-}
-
-module.exports = Inflight;