EventQue

A type-safe, async-friendly, queue-based event emitter for Node.js and TypeScript.

---

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)

Automatically generated using TypeDoc.

---

📦 Installation

npm install eventque
Copy

---

🛠️ Basic Usage

1️⃣ Define your event map

interface MyEvents {
  log: [string]
  compute: [number, number]
}
Copy

---

2️⃣ Create an EventQue instance

import { EventQue } from 'eventque'

const emitter = new EventQue<MyEvents>({
  defaultOptions: {
    parallel: false,
    timeoutMs: 2000,
  },
  perEventOptions: {
    compute: {
      parallel: true,
      timeoutMs: 5000,
    },
  },
})
Copy

---

3️⃣ Register listeners

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
})
Copy

---

4️⃣ Emit events

await emitter.emitAsync('log', 'Hello EventQue!')

const results = await emitter.emitAsync('compute', 5, 7)
console.log('Compute Results:', results)
Copy

---

⚙️ 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
Copy

✅ Generate docs:

npm run docs
Copy

✅ Preview locally:

npx http-server ./docs
Copy

✅ GitHub Pages example:

https://IsamuSugi.github.io/eventque/
Copy

---

🤖 GitHub Actions CI/CD Example

Use .github/workflows/gh-pages.yml:

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
Copy

---

📜 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.

---