{"id":18338717,"url":"https://github.com/tableflip/postmsg-rpc","last_synced_at":"2025-04-06T05:31:50.348Z","repository":{"id":54741351,"uuid":"114113853","full_name":"tableflip/postmsg-rpc","owner":"tableflip","description":"Tiny RPC over window.postMessage library","archived":false,"fork":false,"pushed_at":"2021-02-01T13:02:00.000Z","size":96,"stargazers_count":28,"open_issues_count":2,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-18T12:15:16.790Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://npm.im/postmsg-rpc","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/tableflip.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":"2017-12-13T11:41:57.000Z","updated_at":"2025-02-06T08:27:18.000Z","dependencies_parsed_at":"2022-08-14T01:20:47.992Z","dependency_job_id":null,"html_url":"https://github.com/tableflip/postmsg-rpc","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tableflip%2Fpostmsg-rpc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tableflip%2Fpostmsg-rpc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tableflip%2Fpostmsg-rpc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tableflip%2Fpostmsg-rpc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tableflip","download_url":"https://codeload.github.com/tableflip/postmsg-rpc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247440346,"owners_count":20939221,"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":[],"created_at":"2024-11-05T20:14:56.526Z","updated_at":"2025-04-06T05:31:49.738Z","avatar_url":"https://github.com/tableflip.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# postmsg-rpc\n\n[![Build Status](https://travis-ci.org/tableflip/postmsg-rpc.svg?branch=master)](https://travis-ci.org/tableflip/postmsg-rpc) [![dependencies Status](https://david-dm.org/tableflip/postmsg-rpc/status.svg)](https://david-dm.org/tableflip/postmsg-rpc) [![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)\n\n\u003e Tiny RPC over [window.postMessage](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) library\n\n## Install\n\n```sh\nnpm install postmsg-rpc\n```\n\n## Usage\n\nIn the window you want to call to (**the \"server\"**):\n\n```js\nimport { expose } from 'postmsg-rpc'\n\nconst fruitService = {\n  getFruits: (/* arg0, arg1, ... */) =\u003e new Promise(/* ... */)\n}\n\n// Expose this function for RPC from other windows\nexpose('getFruits', fruitService.getFruits)\n```\n\nIn the other window (**the \"client\"**):\n\n```js\nimport { call } from 'postmsg-rpc'\n\n// Call the exposed function\nconst fruits = await call('getFruits'/*, arg0, arg1, ... */)\n```\n\n### Advanced usage\n\nUse `caller` to create a function that uses postMessage to call an exposed function in a different window. It also allows you to pass options (see docs below).\n\n```js\nimport { caller } from 'postmsg-rpc'\n\nconst getFruits = caller('getFruits'/*, options */)\n\n// Wait for the fruits to ripen\nconst fruits = await getFruits(/*, arg0, arg1, ... */)\n```\n\n## API\n\n#### `expose(funcName, func, options)`\n\nExpose `func` as `funcName` for RPC from other windows. Assumes that `func` returns a promise.\n\n* `funcName` - the name of the function called on the client\n* `func` - the function that should be called. Should be synchronous _or_ return a promise. For callbacks, pass `options.isCallback`\n* `options.targetOrigin` - passed to postMessage (see [postMessage docs](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) for more info)\n    * default `'*'`\n* `options.isCallback` - set to true if `func` takes a node style callback instead of returning a promise\n    * default `false`\n* `options.postMessage` - function that posts a message. It is passed two parameters, `data` and `options.targetOrigin`. e.g. `document.querySelector('iframe').contentWindow.postMessage` for exposing functions to an iframe or `window.parent.postMessage` for exposing functions from an iframe to a parent window\n    * default `window.postMessage`\n\nThe following options are for use with other similar messaging systems, for example when using [message passing in browser extensions](https://developer.chrome.com/extensions/messaging) or for testing:\n\n* `options.addListener` - function that adds a listener. It is passed two parameters, the event name (always \"message\") and a `handler` function\n    * default `window.addEventListener`\n* `options.removeListener` - function that removes a listener. It is passed two parameters, the event name (always \"message\") and a `handler` function\n    * default `window.removeEventListener`\n* `options.getMessageData` - a function that extracts data from the arguments passed to a `message` event handler\n    * default `(e) =\u003e e.data`\n\nReturns an object with a `close` method to stop the server from listening to messages.\n\n#### `call(funcName, \u003carg0\u003e, \u003carg1\u003e, ...)`\n\nCall an exposed function in a different window.\n\n* `funcName` - the name of the function to call\n\nReturns a `Promise`, so can be `await`ed or used in the usual way (`then`/`catch`). The `Promise` returned has an additional property `cancel` which can be called to cancel an in flight request e.g.\n\n```js\nconst fruitPromise = call('getFruits')\n\nfruitPromise.cancel()\n\ntry {\n  await fruitPromise\n} catch (err) {\n  if (err.isCanceled) {\n    console.log('function call canceled')\n  }\n}\n```\n\n#### `caller(funcName, options)`\n\nCreate a function that uses postMessage to call an exposed function in a different window.\n\n* `funcName` - the name of the function to call\n* `options.targetOrigin` - passed to postMessage (see [postMessage docs](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) for more info)\n    * default `'*'`\n* `options.postMessage` - function that posts a message. It is passed two parameters, `data` and `options.targetOrigin`. e.g. `document.querySelector('iframe').contentWindow.postMessage` for calling functions in an iframe or `window.parent.postMessage` for calling functions in a parent window from an iframe\n    * default `window.postMessage`\n\nThe following options are for use with other similar messaging systems, for example when using [message passing in browser extensions](https://developer.chrome.com/extensions/messaging) or for testing:\n\n* `options.addListener` - function that adds a listener. It is passed two parameters, the event name (always \"message\") and a `handler` function\n    * default `window.addEventListener`\n* `options.removeListener` - function that removes a listener. It is passed two parameters, the event name (always \"message\") and a `handler` function\n    * default `window.removeEventListener`\n* `options.getMessageData` - a function that extracts data from the arguments passed to a `message` event handler\n    * default `(e) =\u003e e.data`\n\n## Contribute\n\nFeel free to dive in! [Open an issue](https://github.com/tableflip/postmsg-rpc/issues/new) or submit PRs.\n\n## License\n\n[MIT](LICENSE) © Alan Shaw\n\n---\nA [(╯°□°）╯︵TABLEFLIP](https://tableflip.io) side project.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftableflip%2Fpostmsg-rpc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftableflip%2Fpostmsg-rpc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftableflip%2Fpostmsg-rpc/lists"}