{"id":17228519,"url":"https://github.com/simshaun/ts-event-dispatcher","last_synced_at":"2025-04-14T01:23:55.384Z","repository":{"id":42787585,"uuid":"273811091","full_name":"simshaun/ts-event-dispatcher","owner":"simshaun","description":"A simple JS event dispatcher written in TypeScript.","archived":false,"fork":false,"pushed_at":"2024-08-16T09:48:52.000Z","size":1967,"stargazers_count":3,"open_issues_count":15,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-27T15:21:54.484Z","etag":null,"topics":["event-dispatcher","event-emitter","javascript","typescript"],"latest_commit_sha":null,"homepage":null,"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/simshaun.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-06-21T01:08:40.000Z","updated_at":"2024-12-27T20:57:18.000Z","dependencies_parsed_at":"2024-08-16T10:10:53.402Z","dependency_job_id":null,"html_url":"https://github.com/simshaun/ts-event-dispatcher","commit_stats":null,"previous_names":["simshaun/ts-event-dispatcher"],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simshaun%2Fts-event-dispatcher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simshaun%2Fts-event-dispatcher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simshaun%2Fts-event-dispatcher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simshaun%2Fts-event-dispatcher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simshaun","download_url":"https://codeload.github.com/simshaun/ts-event-dispatcher/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248574897,"owners_count":21127085,"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-dispatcher","event-emitter","javascript","typescript"],"created_at":"2024-10-15T04:44:22.380Z","updated_at":"2025-04-14T01:23:55.340Z","avatar_url":"https://github.com/simshaun.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ts-event-dispatcher\n\n![Version](https://img.shields.io/npm/v/@libshaun/ts-event-dispatcher)\n![CI](https://github.com/simshaun/ts-event-dispatcher/workflows/CI/badge.svg?branch=master)\n![License](https://img.shields.io/github/license/simshaun/ts-event-dispatcher)\n[![Coverage](https://coveralls.io/repos/github/simshaun/ts-event-dispatcher/badge.svg?branch=master)](https://coveralls.io/github/simshaun/ts-event-dispatcher?branch=master)\n\nThis is a simple library that allows your application components to communicate\nwith each other by dispatching events and listening to them.\n\n\n## Installation\n\n```\nnpm i @libshaun/ts-event-dispatcher\n```\n\n\n## Usage\n\nEvents are identified by a unique name of your choosing. Any number of\nlisteners might be listening for them. When an event is dispatched, data about\nthat specific event is passed to listeners so that they have the information they need.\n\n\n### The EventDispatcher\n\nGenerally, you would create a single dispatcher and share it throughout your\napplication. It maintains a registry of listeners. When an event is dispatched\nvia the dispatcher, it notifies all listeners registered with that event.\n\n```ts\nimport { EventDispatcher } from '@libshaun/ts-event-dispatcher'\n\nconst dispatcher = new EventDispatcher()\n```\n\n\n### Dispatching an Event\n\nSuppose you want to trigger an event when a user signs up on your website.\nYour event name might be `user.created`. When dispatching the event, you'll\npass a User object to the listeners.\n\n```ts\ndispatcher.dispatch('user.created', { user, timestamp: 12345 })\n```\n\n\n### Event Listeners\n\nEvent listeners are simple, callable functions that you register with the event\ndispatcher. The EventDispatcher passes your app-specific event data and a\nspecial context object (more on that later) to listeners when their event is\ndispatched.\n\n```ts\ndispatcher.addListener('user.created', (data) =\u003e {\n  // ... do something ...\n})\n```\n\nThe `addListener()` method takes two or three arguments:\n1. An event name.\n2. A callable function to execute when the event is dispatched.\n3. An optional priority (defaults to `0`), defined as a positive or negative\n   integer. The higher the number, the earlier the listener is called. If two\n   listeners have the same priority, they are executed in the order they were\n   added to the dispatcher.\n\n\n### Async Event Listeners\n\nEvent listeners can be asynchronous. The dispatcher will call listeners\nin the intended order and await each one.\n\n```ts\ndispatcher.addListener('user.created', async ({ user }) =\u003e {\n  await post('http://an-important-service', { user })\n})\n\nawait dispatcher.dispatch('user.created', { user })\n```\n\n\n### Stopping Event Propagation\n\nSometimes it may make sense for a listener to prevent the next listeners from\nbeing called. This can be accomplished with the special context object\nmentioned earlier. It's passed to event listeners as the second argument and\ncan be used to stop event propagation.\n\n```ts\nconst listener = (data, ev) =\u003e {\n  // ... do something ...\n  // Stop further propagation:\n  ev.stopPropagation()\n}\n```\n\nIf you need to detect if propagation is stopped, the dispatcher returns the\ncontext object from `dispatch()`.\n\n```ts\nconst context = await dispatcher.dispatch('user.created', data)\nconsole.log(context.isPropagationStopped)\n```\n\n## Full Example\n\n```ts\nimport { EventDispatcher } from '@libshaun/ts-event-dispatcher'\n\nconst dispatcher = new EventDispatcher()\n\n// Set up an event listener\ndispatcher.addListener('user.created', (data, ev) =\u003e {\n  // ... do something ...\n  sendWelcomeEmail(data.user)\n\n  // Optionally, stop next listeners from being called.\n  ev.stopPropagation()\n})\n\n// Dispatch the event\ndispatcher.dispatch('user.created', { user })\n```\n\n## TypeScript Example\n\n```ts\nimport { EventDispatcher } from '@libshaun/ts-event-dispatcher'\n\ninterface User { name: string }\ninterface UserEvent { user: User }\n\n// Provide a map of event names and data expectations.\nconst dispatcher = new EventDispatcher\u003c{\n  'user.created': UserEvent\n}\u003e()\n\n// TypeScript will check both the event name and the listener signature.\ndispatcher.addListener('user.created', (data, ev) =\u003e {\n  // ... do something ...\n  sendWelcomeEmail(data.user)\n\n  // Optionally, stop next listeners from being called.\n  ev.stopPropagation()\n})\n\n// TypeScript will check both the event name and the data signature.\ndispatcher.dispatch('user.created', {\n  user: 'John',           // causes TypeScript error\n  user: { name: 'Sue' },  // good\n  additionalProp: 123,    // causes TypeScript error\n})\n```\n\n\n-----\n\n## TSDX Bootstrap\n\nThis project was bootstrapped with [TSDX](https://github.com/jaredpalmer/tsdx).\n\nCommands:\n\n```\nnpm start\nnpm run build\nnpm test\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimshaun%2Fts-event-dispatcher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimshaun%2Fts-event-dispatcher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimshaun%2Fts-event-dispatcher/lists"}