eventque
Version:
A type-safe, async-friendly, queue-based event emitter for Node.js and TypeScript.
204 lines (143 loc) • 3.89 kB
Markdown
# EventQue
> A type-safe, async-friendly, queue-based event emitter for Node.js and TypeScript.
[](https://www.npmjs.com/package/eventque)
[](LICENSE)
[](https://IsamuSugi.github.io/eventque/)
**EventQue** is a fully type-safe, Promise-based event emitter designed for Node.js and TypeScript.
It supports queued event emission with ordered processing, parallel or sequential listener execution, timeout control, and AbortSignal cancellation.
## 🚀 Features
- ✅ Type-safe event and payload definitions
- ✅ Async emit with Promise results
- ✅ Queueing for ordered event handling
- ✅ Parallel or sequential listener execution
- ✅ Stop-on-error mode
- ✅ Per-listener timeout with AbortSignal support
- ✅ Per-event default configuration
- ✅ Fully compatible with Node.js EventEmitter API (`on`, `once`, `off`)
## 📚 Documentation
👉 **[Full API Docs (TypeDoc)](https://IsamuSugi.github.io/eventque/)**
Automatically generated using [TypeDoc](https://typedoc.org/).
## 📦 Installation
```bash
npm install eventque
```
## 🛠️ Basic Usage
### 1️⃣ Define your event map
```typescript
interface MyEvents {
log: [string]
compute: [number, number]
}
```
### 2️⃣ Create an EventQue instance
```typescript
import { EventQue } from 'eventque'
const emitter = new EventQue<MyEvents>({
defaultOptions: {
parallel: false,
timeoutMs: 2000,
},
perEventOptions: {
compute: {
parallel: true,
timeoutMs: 5000,
},
},
})
```
### 3️⃣ Register listeners
```typescript
emitter.on('log', (message, signal) => {
if (signal.aborted) return
console.log('Log:', message)
})
emitter.once('compute', async (a, b, signal) => {
if (signal.aborted) throw new Error('Cancelled')
await new Promise((res) => setTimeout(res, 1000))
return a + b
})
```
### 4️⃣ Emit events
```typescript
await emitter.emitAsync('log', 'Hello EventQue!')
const results = await emitter.emitAsync('compute', 5, 7)
console.log('Compute Results:', results)
```
## ⚙️ EmitOptions
| Option | Type | Description |
| ------------- | ------- | ---------------------------------------- |
| `parallel` | boolean | Whether to run all listeners in parallel |
| `stopOnError` | boolean | Stop execution on first error |
| `timeoutMs` | number | Per-listener timeout in milliseconds |
## 🧩 Example Project Structure
```
eventque/
├── src/
│ └── EventQue.ts
├── test/
│ └── EventQue.test.ts
├── docs/ ← Generated by TypeDoc
│ ├── index.html
│ └── ...
├── package.json
└── README.md
```
✅ Generate docs:
```bash
npm run docs
```
✅ Preview locally:
```bash
npx http-server ./docs
```
✅ GitHub Pages example:
```
https://IsamuSugi.github.io/eventque/
```
## 🤖 GitHub Actions CI/CD Example
Use `.github/workflows/gh-pages.yml`:
```yaml
name: Deploy Docs
on:
push:
branches:
- main
permissions:
contents: write
jobs:
build-and-deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
- run: npm install
- run: npm run docs
- uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./docs
```
## 📜 License
MIT
## 💡 Author
Isamu Sugiura / GitHub: [https://github.com/isamuSugi]
## 🙏 Contributing
Pull requests are welcome!
For major changes, please open an issue first to discuss what you would like to change.