{"id":16682583,"url":"https://github.com/jchip/xflight","last_synced_at":"2025-08-09T19:14:17.587Z","repository":{"id":57401348,"uuid":"164800328","full_name":"jchip/xflight","owner":"jchip","description":"Handle inflight promise to avoid async duplication","archived":false,"fork":false,"pushed_at":"2025-06-03T14:41:19.000Z","size":13,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-06-03T19:56:21.859Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jchip.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-01-09T06:13:31.000Z","updated_at":"2025-06-03T14:41:16.000Z","dependencies_parsed_at":"2022-09-19T10:43:15.905Z","dependency_job_id":null,"html_url":"https://github.com/jchip/xflight","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/jchip/xflight","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jchip%2Fxflight","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jchip%2Fxflight/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jchip%2Fxflight/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jchip%2Fxflight/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jchip","download_url":"https://codeload.github.com/jchip/xflight/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jchip%2Fxflight/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269625799,"owners_count":24449290,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-09T02:00:10.424Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-12T14:08:00.219Z","updated_at":"2025-08-09T19:14:16.568Z","avatar_url":"https://github.com/jchip.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# xflight\n\n**Avoid redundant async calls by sharing inflight promises for the same key.**\n\n## Description\n\n`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.\n\n## Features\n- Prevents duplicate async operations for the same key\n- Tracks start and check times for inflight items\n- Cleans up after promise resolution or rejection\n- 100% test coverage\n\n## Installation\n\n```bash\nnpm install xflight\n```\n\n## Requirements\n\nThis package requires **Node.js \u003e= 20**.\n\n## Usage\n\n```js\nconst Xflight = require(\"xflight\");\nconst xfl = new Xflight();\n\nfunction fetchData(url) {\n  return xfl.promise(url, () =\u003e fetch(url));\n}\n\n// Multiple calls with the same URL will share the same promise if still pending\nfetchData(\"https://api.example.com/data\").then(console.log);\nfetchData(\"https://api.example.com/data\").then(console.log);\n```\n\n## Usage in ESM and CommonJS\n\n### ESM (ECMAScript Modules)\n```ts\nimport Inflight from \"xflight\";\n\nconst inflight = new Inflight();\nconst key = \"resource-1\";\n\n// Deduplicate async calls\nconst resultPromise = inflight.promise(key, () =\u003e fetch(\"https://api.example.com/data\"));\n```\n\n### CommonJS\n```js\nconst Inflight = require(\"xflight\").default;\n\nconst inflight = new Inflight();\n// ... use as shown in examples above\n```\n\n## API\n\n### `new Xflight([PromiseImpl])`\n- `PromiseImpl` (optional): Custom Promise implementation (e.g., Bluebird, Aveazul, or native Promise).\n\n**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:\n\n```ts\nconst inflight = new Inflight(Promise);\n```\n\n### Methods\n\n#### `promise(key, promiseFactory)`\n- `key`: Unique identifier for the inflight operation.\n- `promiseFactory`: Function that returns a promise.\n- **Returns:** The promise from `promiseFactory`, or the existing inflight promise for the key.\n\n#### `add(key, value, [now])`\n- Manually add an inflight item. `value` should be a promise.\n\n#### `get(key)`\n- Get the current inflight promise for a key, or `undefined`.\n\n#### `remove(key)`\n- Remove an inflight item by key.\n\n#### `isEmpty`\n- Boolean: true if no inflight items.\n\n#### `count`\n- Number of inflight items.\n\n#### Timing Methods\n- `getStartTime(key)`: Get start time (ms since epoch) for a key.\n- `time(key, [now])` / `elapseTime(key, [now])`: Elapsed time since start.\n- `getCheckTime(key)`: Get last check time for a key.\n- `lastCheckTime(key, [now])` / `elapseCheckTime(key, [now])`: Elapsed time since last check.\n- `resetCheckTime(key, [now])`: Reset last check time to now.\n\n## Testing\n\nTo run tests:\n\n```bash\nnpm test\n```\n\nTest coverage is enforced at 100% using `nyc`.\n\n\n## Examples\n\n### Basic Usage with `promise`\n```ts\nimport Inflight from \"xflight\";\n\nconst inflight = new Inflight();\nconst key = \"resource-1\";\n\n// Deduplicate async calls\nconst resultPromise = inflight.promise(key, () =\u003e fetch(\"https://api.example.com/data\"));\n// or, for clarity:\nconst resultPromise2 = inflight.promise(key, function promiseFactory() {\n  return fetch(\"https://api.example.com/data\");\n});\n```\n\n### Manually Add and Get an Inflight Promise\n```ts\nconst promise = new Promise((resolve) =\u003e setTimeout(() =\u003e resolve(\"done\"), 100));\ninflight.add(\"manual-key\", promise);\nconst inflightPromise = inflight.get(\"manual-key\"); // Promise\u003cstring\u003e | undefined\n```\n\n### Remove an Inflight Item\n```ts\ninflight.remove(\"manual-key\");\n```\n\n### Check if Inflight is Empty and Get Count\n```ts\nconsole.log(inflight.isEmpty); // true or false\nconsole.log(inflight.count);   // number of inflight items\n```\n\n### Timing Methods\n```ts\ninflight.add(\"timed-key\", new Promise(() =\u003e {}));\nconst start = inflight.getStartTime(\"timed-key\");\nconst elapsed = inflight.time(\"timed-key\");\nconst elapsedAlias = inflight.elapseTime(\"timed-key\");\n```\n\n### Check Time Methods\n```ts\nconst check = inflight.getCheckTime(\"timed-key\");\nconst sinceLastCheck = inflight.lastCheckTime(\"timed-key\");\nconst sinceLastCheckAlias = inflight.elapseCheckTime(\"timed-key\");\n```\n\n### Reset Check Time\n```ts\n// Reset for a specific key\ninflight.resetCheckTime(\"timed-key\");\n// Reset for all inflight items\ninflight.resetCheckTime();\n```\n\n\n## License\n\nApache-2.0\n\n---\n\n© Joel Chen\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjchip%2Fxflight","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjchip%2Fxflight","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjchip%2Fxflight/lists"}