Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/dbushell/carriageway
🦥 Run async functions with limited concurrency and optional rate limiting
https://github.com/dbushell/carriageway
async bun deno javascript nodejs promises typescript
Last synced: 2 months ago
JSON representation
🦥 Run async functions with limited concurrency and optional rate limiting
- Host: GitHub
- URL: https://github.com/dbushell/carriageway
- Owner: dbushell
- License: mit
- Created: 2023-10-23T13:11:32.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2024-08-28T12:06:15.000Z (5 months ago)
- Last Synced: 2024-09-30T15:50:51.847Z (4 months ago)
- Topics: async, bun, deno, javascript, nodejs, promises, typescript
- Language: TypeScript
- Homepage:
- Size: 28.3 KB
- Stars: 2
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 🦥 Carriageway
Run async and promise-returning functions with limited concurrency and optional rate limiting.
[](https://jsr.io/@dbushell/carriageway) [](https://www.npmjs.com/package/@dbushell/carriageway)
## Usage
Create a new queue:
```javascript
const queue = new Queue();
```
Append an item with a callback function:
```javascript
queue.append('task', (name) => {
console.log(`${name} complete`);
});
```
`append` returns a deferred promise that resolves the callback when the queued item is run. The item is passed to the callback as the first parameter.
```javascript
queue
.append('task', (name) => `${name} complete`)
.then((message) => console.log(message));
```
Callbacks can be functions, async functions, or promise-returning functions.
Items can be anything; primitive types, objects, instances, etc.
```javascript
queue.append({wait: 1000}, async ({wait}) => {
await new Promise((resolve) => setTimeout(resolve, wait));
console.log(`waited ${wait}ms`);
});
```
Other feature examples:
* [Handle errors](/examples/errors.ts)
* [Sort queued items](/examples/sort.ts)
* [Throttle / rate-limit](/examples/throttle.ts)
See the `examples` directory for full usage.
## Options
The `Queue` constructor accepts an options object. Options can also be changed with the instance setter methods.
```javascript
const queue = new Queue({ concurrency: 5 });
queue.concurrency = 10;
```
### concurrency
Maximum number of active items running at once (default: 1).
### throttle
Minimum number of milliseconds between start of each item (default: 0).
## API
### append(item, callback)
Add an item and callback to the end of the queue.
### prepend(item, callback)
Add an item and callback to the start of the queue.
### has(item)
Returns true if item is in the waiting queue.
### get(item)
Returns the deferred promise for the item.
### cancel(item)
Returns true if item was removed from the waiting queue.
### clear()
Empty the queue of waiting items. Deferred promises are rejected with a `QueueError`. Pending items are not cleared.
## Notes
Node may need the `--js-promise-withresolvers` flag.
Inspired by [plimit](https://github.com/sindresorhus/p-limit), [p-throttle](https://github.com/sindresorhus/p-throttle), and [p-queue](https://github.com/sindresorhus/p-queue).
* * *
[MIT License](/LICENSE) | Copyright © 2024 [David Bushell](https://dbushell.com)