{"id":22733491,"url":"https://github.com/burdiuz/js-worker-event-dispatcher","last_synced_at":"2025-03-30T01:45:32.347Z","repository":{"id":46940244,"uuid":"51407549","full_name":"burdiuz/js-worker-event-dispatcher","owner":"burdiuz","description":"WorkerEventDispatcher adds one more layer to Worker API for better communication via events exchange","archived":false,"fork":false,"pushed_at":"2023-01-03T15:16:59.000Z","size":1600,"stargazers_count":1,"open_issues_count":15,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-17T19:48:50.952Z","etag":null,"topics":["communication","dispatch-events","event-dispatcher","fire-events","javascript","js","mirroring","sharedworker","webworkers","worker-script","workers"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/burdiuz.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":"2016-02-09T23:09:10.000Z","updated_at":"2021-05-26T19:34:11.000Z","dependencies_parsed_at":"2023-02-01T07:01:42.950Z","dependency_job_id":null,"html_url":"https://github.com/burdiuz/js-worker-event-dispatcher","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/burdiuz%2Fjs-worker-event-dispatcher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/burdiuz%2Fjs-worker-event-dispatcher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/burdiuz%2Fjs-worker-event-dispatcher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/burdiuz%2Fjs-worker-event-dispatcher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/burdiuz","download_url":"https://codeload.github.com/burdiuz/js-worker-event-dispatcher/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246266251,"owners_count":20749754,"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":["communication","dispatch-events","event-dispatcher","fire-events","javascript","js","mirroring","sharedworker","webworkers","worker-script","workers"],"created_at":"2024-12-10T20:14:47.052Z","updated_at":"2025-03-30T01:45:32.328Z","avatar_url":"https://github.com/burdiuz.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WorkerDispatcher\n\n[![Build Status](https://travis-ci.org/burdiuz/js-worker-event-dispatcher.svg?branch=master)](https://travis-ci.org/burdiuz/js-worker-event-dispatcher)\n[![Coverage Status](https://coveralls.io/repos/github/burdiuz/js-worker-event-dispatcher/badge.svg?branch=master)](https://coveralls.io/github/burdiuz/js-worker-event-dispatcher?branch=master)\n\nThis is extension of [MessagePortDispatcher](https://github.com/burdiuz/js-messageport-event-dispatcher) to work with Dedicated and Shared Workers. It makes possible two-way communication with Workers using custom events. So, instead of using `postMessage()` and catching `message` event all the time, you are free to send any type of events to and from worker.\n\n[Demo with dedicated and shared workers](http://burdiuz.github.io/js-worker-event-dispatcher/)\n\n## Installation\nEasy to install with [npm](https://www.npmjs.com/) package manager\n```javascript\nnpm install --save @actualwave/worker-dispatcher\n```\nwith [yarn](https://yarnpkg.com/) package manager\n```javascript\nyarn add @actualwave/worker-dispatcher\n```\n\n## Usage\n\u003e Note: WorkerDispatcher distribution package contains `dist/` folder with package wrapped into [UMD](https://github.com/umdjs/umd) wrapper, so it can be used with any AMD module loader, nodejs `require()` or without any.\n\n**WorkerDispatcher should be used on HTML page and in Worker script to properly handle communication.**\n\n#### Dedicated Worker\nWorkerDispatcher for Dedicated Worker can be created via `WorkerDispatcher.create()` factory function\n```javascript\nvar worker = new Worker('/workers/worker.js');\nvar dispatcher = WorkerDispatcher.create(worker);\n/* or you can explicitly specify worker type */\nvar dispatcher = WorkerDispatcher.create(worker, WorkerDispatcher.DEDICATED_WORKER);\n```\nWithin Worker script it can be created via `WorkerDispatcher.createForSelf()`, don't need to pass anything, it grabs Worker's global scope object to communicate.\n```javascript\nvar dispatcher = WorkerDispatcher.createForSelf();\n```\nWorkerDispatcher accepts Worker objects or string URL to JS file that should be launched in worker.\nHere Worker will be created from passed URL string:\n```javascript\nvar dispatcher = WorkerDispatcher.create('/workers/worker.js');\n```\n\n#### Shared Worker\nTo use WorkerDispatcher with Shared Worker, it should be created via `WorkerDispatcher.create()` factory method with specified Worker type.\n```javascript\n var worker = new SharedWorker('/workers/sharedworker.js');\n var dispatcher = WorkerDispatcher.create(worker, WorkerDispatcher.SHARED_WORKER);\n dispatcher.start();\n```\nWithin SharedWorker it can be created via `WorkerDispatcher.createForSelf()`. WorkerDispatcher's for client connections will be created automatically.\n```javascript\nvar dispatcher = WorkerDispatcher.createForSelf();\ndispatcher.addEventListener(WorkerDispatcher.WorkerEvent.CONNECT, function(event) {\n  var client = event.client;\n  client.addEventListener('data', function(event) {\n    console.log('new data from client', event.data);\n  });\n  client.start();\n  client.dispatchEvent('initialized');\n});\n```\n\n#### Sending and receiving messages\nTo send messages use `dispatchEvent()` event and to receive messages add event listeners. Sent events will not be fired for sender dispatcher, so you cannot listen for event you just sent\n```javascript\nvar dispatcher = WorkerDispatcher.create('/workers/worker.js');\ndispatcher.addEventListener('anyEvent', function(){\n\tconsole.log('Event received');\n});\ndispatcher.dispatchEvent('anyEvent');\n```\nIn this case event listener will not be called, but if other side will send `\"anyEvent\"` event, this listener will be called.\nOn HTML page:\n```javascript\nvar dispatcher = new WorkerDispatcher('/workers/worker.js');\ndispatcher.addEventListener('anyEvent', function(event) {\n\tconsole.log('Event received');\n});\n```\nWorker code:\n```javascript\nvar dispatcher = WorkerDispatcher.createForSelf();\ndispatcher.dispatchEvent('anyEvent');\n```\n\nProject contains `example` folder with examples for Dedicated and Shared workers communication built with WorkerDispatcher.\n\n## API\n#### WorkerDispatcher constructor arguments\n - **worker**:Worker|MessagePort|String - Worker instance or URL string for worker script.\n - **receiverEventPreprocessor**:Function - Optional, allows pre-processing of events and their data before firing event.\n - **senderEventPreprocessor**:Function - Optional, allows pre-processing of events and their data before passing them to `postMessage`.\n - *type?:String - argument used internally to generate type property in prototype.*\n\n#### WorkerDispatcher shared instance members\nWorkerDispatcher is a base class and it shares functionality across all types of WorkerDispatcher's. When WorkerDispatcher instantiated directly, it actually creates DedicatedWorkerDispatcher.\n\n - **type**:String  - type of the worker\nIncluding [all members of MessagePortDispatcher](https://github.com/burdiuz/js-messageport-event-dispatcher/blob/master/README.md#messageportdispatcher-instance-members), some most important:\n - **addEventListener**(eventType:String, listener:Function):void - add listener for incoming events. This method copied from `receiver`.\n - **hasEventListener**(eventType:String):Boolean - check if incoming event has listeners. This method copied from `receiver`.\n - **removeEventListener**(eventType:String, listener:Function):void - remove event listener for incoming event. This method copied from `receiver`.\n - **dispatchEvent**(event:Object):void - does not fire event, it sends event to `postMessage()`. Can be used with two arguments:\n  - dispatchEvent(eventType:String, data?:Object):void\n\n#### WorkerDispatcher static members\n\n - **CONNECT_EVENT**:String - Short of `WorkerEvent.CONNECT`. Event fired in Shared Worker script when new client is available.\n - **DEDICATED_WORKER**:String - Short of `WorkerType.DEDICATED_WORKER`\n - **SHARED_WORKER**:String - Short of `WorkerType.SHARED_WORKER`\n - **create**(target:String|Worker|SharedWorker, type?:String, receiverEventPreprocessor?:Function, senderEventPreprocessor?:Function):WorkerDispatcher - Creates WorkerDispatcher instance based on type. Currently supported types are `WorkerDispatcher.DEDICATED_WORKER` and `WorkerDispatcher.SHARED_WORKER`. By default will create dispatcher for Dedicated Worker.\n - **self**(receiverEventPreprocessor?:Function, senderEventPreprocessor?:Function):WorkerDispatcher - Can be used in Worker script, it checks what kind of worker is used and returns proper dispatcher object for WorkerGlobalScope. For Dedicated Worker returns instance of DedicatedWorkerDispatcher and for Shared Worker -- ServerEventDispatcher.\n\n - WorkerEvent:Object - Worker event types\n   - CONNECT:String - Mirroring connect event fired from WorkerGlobalScope, fired when new client connected. Event object contains field `client` with `ClientEventDispatcher` instance, to communicate with client.\n   - ERROR:String - Mirroring [error event](https://developer.mozilla.org/en-US/docs/Web/Events/error) fired from WorkerGlobalScope\n   - LANGUAGECHANGE:String -  Mirroring [languagechange event](https://developer.mozilla.org/en-US/docs/Web/Events/languagechange) fired from WorkerGlobalScope\n   - ONLINE:String - Mirroring [online event](https://developer.mozilla.org/en-US/docs/Web/Events/online) fired from WorkerGlobalScope\n   - OFFLINE:String - Mirroring [offline event](https://developer.mozilla.org/en-US/docs/Web/Events/offline) fired from WorkerGlobalScope\n - WorkerType:Object - Possible dispatcher types, used with `WorkerDispatcher.create()`\n   - DEDICATED_WORKER:String - Default type, will create DedicatedWorkerDispatcher\n   - SHARED_WORKER:String - Will create SharedWorkerDispatcher\n   - SHARED_WORKER_SERVER:String - For internal usage, will create ServerEventDispatcher\n   - SHARED_WORKER_CLIENT:String - For internal usage, will create ClientEventDispatcher\n - DedicatedWorker:Function - Constructor of DedicatedWorkerDispatcher\n - SharedWorker:Function - Constructor of SharedWorkerDispatcher\n - Server:Function - Constructor of ServerEventDispatcher\n - Client:Function - Constructor of ClientEventDispatcher\n\n\n#### DedicatedWorkerDispatcher\nCreated when `WorkerDispatcher.DEDICATED_WORKER` used, when `WorkerDispatcher.createForSelf()` called in Dedicated Worker or when WorkerDispatcher called with `new` operator.\n\n - **terminate**():void - close connection to worker, i.e. destroy worker.\n\n#### SharedWorkerDispatcher\nCreated when WorkerDispatcher.SHARED_WORKER used. When created using `WorkerDispatcher.create()`, worker's name will default to `null`, if you need to specify name, you can instantiate it with constructor.\n```javascript\nvar dispatcher = new WorkerDispatcher.SharedWorkerDispatcher('/workers/sharedworker.js', 'worker-name');\n```\n\n#### ServerEventDispatcher\nCreated when WorkerDispatcher.createForSelf() called in Shared Worker. It differs from other types of WorkerDispatcher's because **does not have `dispatchEvent()` method**, so it can only listen for events, like WorkerEvent.CONNECT to accept connections. Since it cannot send data, it does not have `sender` EventDispatcher either, only `receiver` available.\n\n#### ClientEventDispatcher\nCreated when Shared Worker gets new connection. to capture new connections, you shuld listen to WorkerEvent.CONNECT event.\n\n - **start**():void - Start communication with client\n - **close**():void - Close connection to client\n\n```javascript\nvar _clients = [];\n// Create ServerEventDispatcher\nvar dispatcher = WorkerDispatcher.createForSelf();\n// Listen to incoming connections\ndispatcher.addEventListener(WorkerDispatcher.WorkerEvent.CONNECT, function(event) {\n  // Get ClientEventDispatcher of new connection from event, save and start it\n  var client = event.client;\n  _clients.push(client);\n  client.start();\n  client.dispatchEvent('initialize');\n});\n```\n\n### Links\n[MDN - Using web workers](https://developer.mozilla.org/ru/docs/DOM/Using_web_workers)\n[https://www.w3.org/TR/workers/](https://www.w3.org/TR/workers/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fburdiuz%2Fjs-worker-event-dispatcher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fburdiuz%2Fjs-worker-event-dispatcher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fburdiuz%2Fjs-worker-event-dispatcher/lists"}