{"id":22296434,"url":"https://github.com/knowledgecode/messenger","last_synced_at":"2025-03-25T22:37:19.512Z","repository":{"id":56899673,"uuid":"202886737","full_name":"knowledgecode/messenger","owner":"knowledgecode","description":"Req/Rep Pub/Sub library for iframes and workers","archived":false,"fork":false,"pushed_at":"2023-01-08T09:05:51.000Z","size":81,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-01T15:39:00.476Z","etag":null,"topics":["iframe","pub","pubsub","rep","req","sub","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/knowledgecode.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-08-17T13:51:01.000Z","updated_at":"2023-01-01T01:37:50.000Z","dependencies_parsed_at":"2023-02-08T05:31:20.514Z","dependency_job_id":null,"html_url":"https://github.com/knowledgecode/messenger","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knowledgecode%2Fmessenger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knowledgecode%2Fmessenger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knowledgecode%2Fmessenger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knowledgecode%2Fmessenger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/knowledgecode","download_url":"https://codeload.github.com/knowledgecode/messenger/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245556976,"owners_count":20634888,"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":["iframe","pub","pubsub","rep","req","sub","worker"],"created_at":"2024-12-03T17:45:35.291Z","updated_at":"2025-03-25T22:37:19.475Z","avatar_url":"https://github.com/knowledgecode.png","language":"JavaScript","readme":"# Messenger\n\nMessenger is a `Req/Rep` `Pub/Sub` library for iframes and workers.\n\n## Features\n\nAllows messages to be exchanged between ...\n\n- the main window and one or more iframes / workers.\n- multiple iframes.\n- multiple components.\n\n## Installation\n\nvia npm:\n\n```shell\nnpm i @knowledgecode/messenger\n```\n\n## Usage\n\n```javascript\nimport { MessengerClient, MessengerServer } from '@knowledgecode/messenger';\n```\n\nES Modules:\n\n```html\n\u003cscript type=\"module\"\u003e\n  import { MessengerClient, MessengerServer } from '/path/to/esm/messenger.js';\n\u003c/script\u003e\n```\n\nTraditional:\n\n```html\n\u003cscript src=\"/path/to/umd/messenger.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n  // It is provided with the global variable name \"messenger\".\n  const { MessengerClient, MessengerServer } = self.messenger;\n\u003c/script\u003e\n```\n\n## Simple Example\n\nmain.js\n```javascript\nimport { MessengerClient } from '/path/to/esm/messenger.js';\n\nconst messenger = new MessengerClient();\nconst worker = new Worker('/path/to/worker.js');\n\n(async () =\u003e {\n    await messenger.connect('example', worker);\n\n    const answer = await messenger.req('add', { x: 2, y: 3 });\n\n    console.log(answer);    // =\u003e 5\n\n    messenger.send('close');\n    messenger.disconnect();\n})();\n```\n\nworker.js\n```javascript\nimportScripts('/path/to/umd/messenger.js');\n\nconst { MessengerServer } = self.messenger;\nconst messenger = new MessengerServer('example', self);\n\nmessenger.bind('add', data =\u003e {\n    return data.x + data.y;\n});\n\nmessenger.bind('close', () =\u003e {\n    messenger.close();\n    // Close this worker.\n    self.close();\n});\n```\n\n## MessengerClient API\n\n### `constructor()`\n\n```javascript\nconst messenger = new MessengerClient();\n```\n\n### `connect(name, [endpoint[, options]])`\n\n- {**string**} name - unique name of the MessengerServer to connect to\n- {**Object**} [endpoint] - an object that actually executes the `postMessage()`\n- {**Object**} [options] - connection options\n\nThe `MessengerClient` must connect to a `MessengerServer` via `endpoint` before communication can begin. To identify the `MessengerServer` to connect to, pass the unique name of the `MessengerServer` as the first argument. The `endpoint` is the object that actually executes the `postMessage()`. If omitted, it is assumed that `self` is set. The `options` are connection options and members of this object are `targetOrigin` and `timeout` (msec). If the `timeout` is omitted, this method will wait forever for a successful connection.\n\n```javascript\n// To connect from the main window to a iframe.\nconst iframe = window.frames[0];\n\nawait messenger.connect('iframe', iframe, { targetOrigin: '*', timeout: 1000 })\n    .catch(e =\u003e console.log(e));\n```\n\n```javascript\n// To connect from the main window to a worker.\nconst worker = new Worker('/path/to/worker.js');\n\nawait messenger.connect('worker', worker, { timeout: 1000 })\n    .catch(e =\u003e console.log(e));\n```\n\n### `disconnect()`\n\nDisconnects from the server.\n\n```javascript\nmessenger.disconnect();\n```\n\n### `send(topic[, data])`\n\n- {**string**} topic - topic name\n- {**Object**} [data] - an object to send\n\nSends a message (some object) to a topic. This method does not wait for any reply. A `MessengerServer` can receive the message if it is bound to the same topic name in advance.\n\n```javascript\nmessenger.send('greeting', { hello: 'world' });\n```\n\n### `req(topic[, data[, timeout]])`\n\n- {**string**} topic - topic name\n- {**Object**} [data] - an object to send\n- {**number**} [timeout] - timeout (msec)\n\nSends a message (some object) to a topic. This method waits for some reply unlike `send()`. If `timeout` (msec) is omitted, this method waits forever for some reply.\n\n```javascript\nconst answer = await messenger.req('add', { x: 2, y: 3 })\n\nconsole.log(answer);\n```\n\n```javascript\nawait messenger.req('add', { x: 2, y: 3 }, 5000)\n    .catch(e =\u003e console.log(e));    // Catch timeout error.\n```\n\n### `subscribe(topic, listener)`\n\n- {**string**} topic - topic name\n- {**Function**} listener - a listener to receive published messages\n\nSubscribes to messages on a topic.\n\n```javascript\nmessenger.subscribe('news', data =\u003e console.log(data));\n```\n\n### `unsubscribe(topic[, listener])`\n\nUnsubscribes to messages on a topic. If listener is omitted, all listeners for the topic are cleared.\n\n- {**string**} topic - topic name\n- {**Function**} [listener] - a listener to receive published messages\n\n```javascript\nconst listener = data =\u003e console.log(data);\nmessenger.subscribe('news', listener);\n\nmessenger.unsubscribe('news', listener);\n```\n\n## MessengerServer API\n\n### `constructor(name, [endpoint])`\n\n- {**string**} name - unique name of the MessengerServer\n- {**Object**} [endpoint] - an object that actually executes the `postMessage()`\n\n```javascript\nconst messenger = new MessengerServer('server', self);\n```\n\nThe `name` is a unique name by which clients identify this MessengerServer. The `endpoint` is the object that actually executes the `postMessage()`. If omitted, it is assumed that `self` is set.\n\n### `bind(topic, listener)`\n\n- {**string**} topic - topic name\n- {**Function**} listener - a listener to receive messages\n\nBinds a listener to listen for messages on a topic. The topic names must be unique, no other listener than the first can bind on the same topic name. This method returns `true` or `false` as binding result.\n\n```javascript\nmessenger.bind('greeting', data =\u003e console.log(data));\n\nmessenger.bind('add', data =\u003e {\n    // Reply to client.\n    return data.x + data.y;\n});\n```\n\n### `publish(topic, data)`\n\n- {**string**} topic - topic name\n- {**Object**} data - an object to publish\n\nPublish a message (some object) to all subscribers on a topic. This method does not wait for reply from the subscribers, and also does not fail even there are no subscribers at all.\n\n```javascript\nmessenger.publish('notification', 'The process completed successfully.');\n```\n\n### `close()`\n\nCloses all connections and shuts down the server.\n\n```javascript\nmessenger.close();\n```\n\n## Browser support\n\nChrome, Safari, Firefox, Edge\n\n## License\n\nMIT\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknowledgecode%2Fmessenger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fknowledgecode%2Fmessenger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknowledgecode%2Fmessenger/lists"}