{"id":13695695,"url":"https://github.com/sdgluck/msgr","last_synced_at":"2025-10-25T21:32:59.544Z","repository":{"id":57304132,"uuid":"61029352","full_name":"sdgluck/msgr","owner":"sdgluck","description":":mailbox_closed: Nifty service worker/client message utility","archived":false,"fork":false,"pushed_at":"2016-08-02T11:16:31.000Z","size":26,"stargazers_count":40,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-09-20T02:38:05.871Z","etag":null,"topics":["message-handler","service-worker"],"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/sdgluck.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-06-13T11:02:45.000Z","updated_at":"2022-03-24T13:42:49.000Z","dependencies_parsed_at":"2022-09-20T21:10:47.674Z","dependency_job_id":null,"html_url":"https://github.com/sdgluck/msgr","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sdgluck%2Fmsgr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sdgluck%2Fmsgr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sdgluck%2Fmsgr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sdgluck%2Fmsgr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sdgluck","download_url":"https://codeload.github.com/sdgluck/msgr/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224175776,"owners_count":17268389,"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":["message-handler","service-worker"],"created_at":"2024-08-02T18:00:32.446Z","updated_at":"2025-10-25T21:32:54.490Z","avatar_url":"https://github.com/sdgluck.png","language":"JavaScript","readme":"# msgr\n\n\u003e Nifty service worker/client message utility\n\nMade with ❤ at [@outlandish](http://www.twitter.com/outlandish)\n\n\u003ca href=\"http://badge.fury.io/js/msgr\"\u003e\u003cimg alt=\"npm version\" src=\"https://badge.fury.io/js/msgr.svg\"\u003e\u003c/a\u003e\n[![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg)](http://standardjs.com/)\n\nMakes communication between a client and service worker super easy...\n\n- Send messages from client to worker and vice-versa\n- Accommodates complex communications with a simple API\n- Easily respond to any message\n- Receive one-off responses to messages\n\n_To see it being used in the wild, check out the source code of [`fetch-sync`](https://github.com/sdgluck/fetch-sync)._\n\n## Table of Contents\n\n- [Import](#import)\n- [Initialise \u0026 Example](#initialise-\u0026-example)\n- [Sending Messages](#sending-messages)\n- [Receiving Messages](#receiving-messages)\n- [msgr API](#msgr-api)\n- [Channel API](#channel-api)\n- [Message API](#message-api)\n\n## Import\n\n__Client__\n\n```js\n// ES6\nimport msgr from 'msgr'\n\n// CommonJS\nvar msgr = require('msgr')\n\n// RequireJS\ndefine(['msgr'], function (msgr) {/*...*/})\n```\n\n```html\n\u003c!-- Script, available as `window.msgr` --\u003e\n\u003cscript src=\"/node_modules/msgr/index.js\"\u003e\u003c/script\u003e\n```\n\n__Worker__\n\nIf you are bundling your SW then you can use the Import methods above.\n\nOtherwise...\n\n```js\n// importScripts\nimportScripts('/node_modules/msgr/index.js')\n```\n\n## Initialise \u0026 Example\n\n__Client: `msgr.client()`__\n\nPass in reference to the worker and a collection of message handlers:\n\n```js\nconst recipient = navigator.serviceWorker.controller\n\nconst channel = msgr.client(recipient, {\n  // Predefined message handlers\n  SAY_HELLO: (data) =\u003e console.log('Hello, ' + data) //=\u003e 'Hello, World!'\n})\n\n// Send something \"unknown\" to the worker.\n// Notice it does not have a tag.\nchannel.send({\n  username: 'Flanders',\n  location: 'Springfield'\n})\n\n// Send a \"known\" message to the worker\nchannel.send('CACHE_ASSET', '/cat.gif').then(function (message) {\n  console.log(message) //=\u003e 'Caching complete!'\n})\n```\n\n__Worker: `msgr.worker()`__\n\nOn the worker you just pass in your message handlers:\n\n```js\nconst channel = msgr.worker({\n  CACHE_ASSET: (url, respond) =\u003e {\n    cache(url).then(function () {\n      respond('Caching complete!')\n    })\n  }\n})\n\nchannel.receive(function (data) {\n  // Do something with an \"unknown\" message\n  // that does not have a predefined handler.\n  console.log(data) //=\u003e { username: 'Flanders', ... }\n})\n\n// Send something \"known\" to the client using a tag.\nchannel.send('SAY_HELLO', 'World!')\n```\n\n## Sending Messages\n\n- Anonymous, data-only message:\n\n    ```js\n    channel.send({ requestId: '123' })\n    ```\n    \n- Type-only message:\n\n    ```js\n    channel.send('RE_CACHE')\n    ```\n\n- Typed message with data:\n\n    ```js\n    channel.send('RE_CACHE', { assetUrl: '/cat.gif' })\n    ```\n    \n## Receiving Messages\n\nThe API for receiving messages is the same for both the worker and client.\n\n- Anonymous, data-only message:\n\n    ```js\n    channel.receive((data) =\u003e {\n      console.log(data.requestId) //=\u003e '123'\n    })\n    ```\n    \n- Type-only message:\n\n    ```js\n    msgr.client({\n      RE_CACHE: (data, respond) =\u003e {\n        console.log(data) //=\u003e null\n      }\n    })\n    ```\n\n- Typed message with data:\n\n    ```js\n    \n    msgr.client({\n      RE_CACHE: (data, respond) =\u003e {\n        console.log(data.assetUrl) //=\u003e '/cat.gif'\n      }\n    })\n    ```\n\n## msgr API\n\n### `msgr.client(serviceWorker, handlers) : Channel`\n\nInitialise a `msgr` client.\n\n- __serviceWorker__ {ServiceWorkerRegistration} Worker that will receive messages sent via channel\n- __handlers__ {Object} An object of message type/handler mappings\n\nReturns a Channel. See the [Channel API Docs](#channel-api) for more details.\n\nExample:\n\n```js\nmsgr.client(navigator.serviceWorker.controller, {\n  NOTIFY: function (respond) {\n    new Notification('You have a notification!')\n    respond('GOT_THE_NOTIFICATION')\n  }\n})\n```\n\n### `msgr.worker(handlers) : Channel`\n\nInitialise a `msgr` worker.\n\n- __handlers__ {Object} An object of message type/handler mappings\n\nReturns a Channel. See the [Channel API Docs](#channel-api) for more details.\n\nExample:\n\n```js\nmsgr.worker({\n  NOTIFY: function (respond) {\n    new Notification('You have a notification!')\n    respond('GOT_THE_NOTIFICATION')\n  }\n})\n```\n\n## Channel API\n\n### `channel.ready(handler)`\n\nRegister a handler to be called when the channel is opened between client and worker.\n\n- __handler__ {Function} The ready handler\n\nAlthough you can register ready handlers, you can send messages before the channel is open using\n`channel.send()` and these will be queued and sent as soon as the channel is ready.\n\nExample:\n\n```js\nchannel.ready(function () {\n  application.start()\n})\n```\n\n### `channel.send([type,] data) : Promise`\n\nSend a message through the channel to the worker/client.\n\n- [__type__] {String} _(optional)_ The message type\n- __data__ {Any} The message data (it will be JSON.stringify'd)\n\nReturns a Message. See the [Message API Docs](#message-api) for more details.\n\nIf called before the channel is ready the message will be queued and sent as soon as the channel is open.\n\nExample:\n\n```js\n// Typed message, will invoke registered type handlers\nchannel.send('NOTIFY_USER')\n\n// Typed message with data, will invoke registered type handlers\nchannel.send('NOTIFY_USER', { message: 'Update complete' })\n\n// Anonymous, will invoke `receive` handlers\nchannel.send('This is the untagged data')\n```\n\n### `channel.receive(handler)`\n\nHandle an \"unknown\" message that is not tagged.\n\n- __handler__ {Function} The message handler\n\nThe handler receives two arguments: the `data` of the message and a `respond` function.\n\nExample:\n\n```js\nchannel.receive(function (data, respond) {\n  console.log('Got some unknown data: ' + data)\n})\n```\n\n## Message API\n\n### `message.then(handler)`\n\nRegister a handler to receive the response to a message.\n\n- __handler__ {Function} Response handler\n\nExample:\n\n```js\n// In client message handlers\nmsgr({\n  NOTIFY_USER: function (data, respond) {\n    new Notification('Job ' + data.id + ' was completed')\n    respond('From worker: job deleted') // ACK\n  }\n})\n\n// In worker\nchannel.send('NOTIFY_USER', { id: 1337 }).then((data) =\u003e {\n  console.log(data) //=\u003e 'From worker: job deleted'\n})\n```\n\n### `respond([data])`\n\nSend a response to a received message.\n\nThis function is passed as the second argument to both \"known\" and \"unknown\" message handlers.\n\n- [__data__] {Any} _(optional)_ The data to respond to the message with\n\n## Contributing\n\nAll pull requests and issues welcome!\n\nIf you're not sure how, check out Kent C. Dodds'\n[great video tutorials on egghead.io](https://egghead.io/lessons/javascript-identifying-how-to-contribute-to-an-open-source-project-on-github)!\n\n## Author \u0026 License\n\n`msgr` was created by [Sam Gluck](https://twitter.com/sdgluck) and is released under the MIT license.\n\n","funding_links":[],"categories":["Tools"],"sub_categories":["Service Worker Libraries"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsdgluck%2Fmsgr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsdgluck%2Fmsgr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsdgluck%2Fmsgr/lists"}