{"id":13828933,"url":"https://github.com/sergeysova/emitting","last_synced_at":"2025-07-09T06:33:33.578Z","repository":{"id":35806608,"uuid":"219409799","full_name":"sergeysova/emitting","owner":"sergeysova","description":"EventEmitter designed for TypeScript and Promises","archived":true,"fork":false,"pushed_at":"2023-01-07T11:22:32.000Z","size":1337,"stargazers_count":38,"open_issues_count":24,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-10-01T21:48:32.204Z","etag":null,"topics":["event-emitter","nodejs","typescript"],"latest_commit_sha":null,"homepage":"https://npmjs.com/emitting","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sergeysova.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-11-04T03:28:35.000Z","updated_at":"2023-06-20T17:00:47.000Z","dependencies_parsed_at":"2023-01-16T06:49:03.052Z","dependency_job_id":null,"html_url":"https://github.com/sergeysova/emitting","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sergeysova%2Femitting","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sergeysova%2Femitting/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sergeysova%2Femitting/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sergeysova%2Femitting/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sergeysova","download_url":"https://codeload.github.com/sergeysova/emitting/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225489482,"owners_count":17482378,"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","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":["event-emitter","nodejs","typescript"],"created_at":"2024-08-04T09:03:21.248Z","updated_at":"2024-11-20T08:31:23.958Z","avatar_url":"https://github.com/sergeysova.png","language":"TypeScript","readme":"# Emitting\n\n[![Build Status](https://travis-ci.com/sergeysova/emitting.svg?branch=master)](https://travis-ci.com/sergeysova/emitting)\n[![Codecov](https://img.shields.io/codecov/c/github/sergeysova/emitting)](https://codecov.io/gh/sergeysova/emitting)\n[![Codacy](https://api.codacy.com/project/badge/Grade/3c6e3befee084c1d8e6ed87ef7b17327)](https://app.codacy.com/manual/sergeysova/emitting)\n[![dependencies Status](https://david-dm.org/sergeysova/emitting/status.svg)](https://david-dm.org/sergeysova/emitting)\n[![npm bundle size](https://img.shields.io/bundlephobia/min/emitting)](https://bundlephobia.com/result?p=emitting)\n\n[[Github](https://github.com/sergeysova/emitting) | [NPM](https://npmjs.com/package/emitting) | [Typedoc](https://emitting.sova.dev/)]\n\nEmitting is a simple event emitter designed for **TypeScript** and **Promises**. There are some differences from other emitters:\n\n- **Exactly typing** for event payloads `new EventEmitter\u003cEvents\u003e()`\n- **Waiting for event** with `.take(\"event\"): Promise\u003cPayload\u003e` and same\n- **Do not `throw`** an error when you emit an `error` event and nobody is listening\n- **Functional** — methods don't rely on `this`\n- **Small size**. No dependencies. [Size Limit](https://github.com/ai/size-limit) controls the size.\n\n## Table of contents\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n- [Installation](#installation)\n- [Polyfills](#polyfills)\n- [Usage](#usage)\n  - [JavaScript](#javascript)\n  - [TypeScript](#typescript)\n- [API](#api)\n  - [Constructor](#constructor)\n  - [`.on(eventName, handler)` — add event listener](#oneventname-handler--add-event-listener)\n  - [`.once(eventName, handler)` — listen event once](#onceeventname-handler--listen-event-once)\n  - [`.emit(eventName, payload)` — send event to listeners](#emiteventname-payload--send-event-to-listeners)\n  - [`.emitCallback(eventName)` — create emitter function](#emitcallbackeventname--create-emitter-function)\n  - [`.take(event): Promise` — wait for event](#takeevent-promise--wait-for-event)\n  - [`.takeTimeout(event, ms): Promise` — wait for event or reject](#taketimeoutevent-ms-promise--wait-for-event-or-reject)\n  - [`.takeEither(successEvent, failureEvent): Promise` — resolve or reject promise with events](#takeeithersuccessevent-failureevent-promise--resolve-or-reject-promise-with-events)\n  - [Unsubscribe from events](#unsubscribe-from-events)\n  - [`.off(eventName)` — remove all listeners](#offeventname--remove-all-listeners)\n- [Roadmap](#roadmap)\n- [License](#license)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## Installation\n\n```sh\n# NPM\nnpm instal --save emitting\n\n# Yarn\nyarn add emitting\n```\n\n## Polyfills\n\nModule built to ECMAScript 5.\n\nBe sure to add polyfills if neccessary for:\n\n- `Promise`\n- `Set`\n- `Map`\n\n## Usage\n\n### JavaScript\n\nAfter installation the only thing you need to do is require the module:\n\n```js\nconst { EventEmitter } = require(\"emitting\")\n\nconst emitter = new EventEmitter()\n```\n\n### TypeScript\n\nAfter installation you need to import module and define events:\n\n```ts\nimport { EventEmitter } from \"emitting\"\n\ntype Events = {\n  hello: { name: string }\n  bye: void\n}\n\nconst emitter = new EventEmitter\u003cEvents\u003e()\n// Now you have typed event emitter 🚀 yay!\n```\n\n## API\n\nDocumentation for API generated by TypeDOC — [emitting.sova.dev](https://emitting.sova.dev/)\n\n### Constructor\n\nReceives type parameter `Events` that should be object type or interface, where key is an event name and value is an payload as a single parameter type.\n\n```ts\ntype Events = {\n  eventName: PayloadType\n}\n```\n\nPass `Events` to constructor generic parameter:\n\n```ts\nimport { EventEmitter } from \"emitting\"\n\ntype Events = {\n  hello: { name: string }\n  bye: void\n}\n\nconst emitter = new EventEmitter\u003cEvents\u003e()\n```\n\nNow you can emit events and subscribe to.\n\n### `.on(eventName, handler)` — add event listener\n\n`.on()` receives an event name and an event handler.\u003cbr/\u003e\nEvent handler should be a function that receives a payload.\u003cbr/\u003e\n`.on()` returns `unsubscribe` function to remove created subscribtion.\n\n```ts\nfunction helloHandler(payload: { name: string }) {\n  console.log(payload.name)\n}\n\nfunction byeHandler() {\n  console.log(\"Goodbye!\")\n}\n\nemitter.on(\"hello\", helloHandler)\nemitter.on(\"bye\", byeHandler)\n```\n\n### `.once(eventName, handler)` — listen event once\n\nSubscribes to event, and when it received immediately unsubscribe.\u003cbr/\u003e\nSubscribtion can be canceled at any time.\n\n```ts\nconst cancel = emitter.on(\"hello\", helloHandler)\n\ncancel() // subscription cancelled\n```\n\n### `.emit(eventName, payload)` — send event to listeners\n\nExecutes all listeners with passed payload.\u003cbr/\u003e\nAccepts only one payload parameter. Use object type or tuple type to pass multiple payloads.\u003cbr/\u003e\nIf no listeners nothing happens.\n\n```ts\nemitter.emit(\"hello\", { name: \"world\" })\n```\n\n### `.emitCallback(eventName)` — create emitter function\n\nCreate function that emit event when called.\u003cbr/\u003e\nPayload should be passed to returned callback.\n\n```ts\nconst hello = emitter.emitCallback(\"hello\")\n\nhello({ name: \"world\" }) // emitted \"hello\" event\n```\n\n### `.take(event): Promise` — wait for event\n\nCreates promise that resolves when specified event is received. \u003cbr/\u003e\nReturns `Promise` resolved with payload of the passed event. \u003cbr/\u003e\nListeners removed after event is received.\n\n```ts\ntype Events = {\n  example: number\n}\nconst emitter = new EventEmitter\u003cEvents\u003e()\n\nemitter.take(\"example\").then((payload) =\u003e {\n  console.log(\"Received\", payload)\n})\n\nemitter.emit(\"example\", 10) // Received 10\n```\n\nWith `async/await`:\n\n```ts\nconst payload: number = await emitter.take(\"example\")\n```\n\n### `.takeTimeout(event, ms): Promise` — wait for event or reject\n\nCreates a promise that resolves when specified event is received.\u003cbr/\u003e\nPromise resolves with payload of the received event. \u003cbr/\u003e\nPromise is rejected when timeout is reached. \u003cbr/\u003e\nListeners removed after timeout is reached, and event is received.\n\n```ts\ntry {\n  const { name } = await emitter.takeTimeout(\"hello\", 300)\n} catch (_) {\n  console.info(\"Event `hello` is not emitted in 300 ms after subscribing to\")\n}\n```\n\n### `.takeEither(successEvent, failureEvent): Promise` — resolve or reject promise with events\n\nReturns promise that resolves when `successEvent` is emitted with the payload of event. \u003cbr/\u003e\nPromise rejected when `failureEvent` is emitted, as error passed payload of the `failureEvent`. \u003cbr/\u003e\nListeners removed when `successEvent` or `failureEvent` is received and promise resolves just once. \u003cbr/\u003e\n\n```ts\nemitter\n  .takeEither(\"success\", \"failure\")\n  .then((payload) =\u003e console.log(\"Yeeah\", payload))\n  .catch((error) =\u003e console.log(\"Noooo\", error))\n\nemitter.emit(\"success\", 500) // Yeeah 500\n// or\nemitter.emit(\"failure\", \"Vader is my father!\") // Noooo Vader is my father\n```\n\n### Unsubscribe from events\n\nThe `.on()`, `.once()` and same returns `unsubscribe` function, that can be called multiple times at any time.\n\n```ts\nconst unsubscribeHello = emitter.on(\"hello\", helloHandler)\nconst unsubscribeBye = emitter.on(\"bye\", helloHandler)\n\nunsubscribeHello() // now helloHandler will not be called when \"hello\" is emitted\n```\n\n### `.off(eventName)` — remove all listeners\n\n\u003e Note: destructive operation\n\nThe method removes all listeners from emitter. Use it with caution, if called `.take` methods, **promises will never be fullfilled**.\n\n```ts\nemitter.off(\"hello\") // all listeners removed\n```\n\n## Roadmap\n\n- [ ] Add `emitter.off(eventName, handler)`\n- [ ] Add `*` event to listen all events\n- [ ] Add `emitter.events(): string[]`\n- [ ] Add `emitting::listenerAdded`, `emitting::listenerRemoved`\n- [ ] Add support for reactive (`.subscribe`)\n- [ ] Add async iterators (`.iterate(eventName)`)\n- [ ] Add benchmarks\n- [ ] Add `.public(): PublicEmitter` and `.private(): PrivateEmitter`\n\n## License\n\n[MIT](https://github.com/sergeysova/emitting/blob/HEAD/LICENSE)\n","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsergeysova%2Femitting","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsergeysova%2Femitting","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsergeysova%2Femitting/lists"}