{"id":18656771,"url":"https://github.com/optimalbits/blackbird","last_synced_at":"2025-04-11T18:31:18.931Z","repository":{"id":15922180,"uuid":"18663964","full_name":"OptimalBits/blackbird","owner":"OptimalBits","description":"Confortable interfacing of event based transports","archived":false,"fork":false,"pushed_at":"2014-07-07T18:42:03.000Z","size":222,"stargazers_count":8,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-08T10:57:25.301Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OptimalBits.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-04-11T05:58:00.000Z","updated_at":"2020-04-29T04:23:50.000Z","dependencies_parsed_at":"2022-08-31T04:40:21.466Z","dependency_job_id":null,"html_url":"https://github.com/OptimalBits/blackbird","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OptimalBits%2Fblackbird","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OptimalBits%2Fblackbird/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OptimalBits%2Fblackbird/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OptimalBits%2Fblackbird/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OptimalBits","download_url":"https://codeload.github.com/OptimalBits/blackbird/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248458444,"owners_count":21107080,"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-07T07:25:16.446Z","updated_at":"2025-04-11T18:31:18.556Z","avatar_url":"https://github.com/OptimalBits.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"#Blackbird\n![blackbird](doc/img/blackbird.png)\n\nBlackbird provides easy-to-use proxy objects that let you call methods\nacross event based transports such as websockets, iframe postMessage channel\netc. Instead of manually emitting and listening to events, blackbird lets\nyou define interfaces that you can implement on one end point. On the\nother end point a proxy object is generated that you can call just as if\nit had been a local object. Any message based communication channel can\nbe used so only your imagination sets the limit.\n\n##Why?\nWithout blackbird the code for requesting data from one endpoint to the other could look something like this:\n\n    // Endpoint A\n    var name;\n    window.addEventListener('message', function(e) {\n      name = e.data;\n      console.log(name);\n    });\n    \n    window.postMessage('getName', '*');\n    \n    // Endpoint B\n    window.addEventListener('message', function(e) {\n      window.postMessage('Paul', '*');\n    });\n\nThis is not very generic and very error prone.\nNow compare it with the following blackbird code:\n\n    // Endpoint A\n    outbound.getName(function(err, name){\n      console.log(name);\n    });\n\n    // Endpoint B\n    inbound.getName = function(){\n      return Paul;\n    }\n\nblackbird abstracts away the underlying messaging and lets you concentrate\non your application logic instead. If you prefer promises over callback\nblackbird supports that too out of the box.\n\n    // Endpoint A\n    outbound.getName().then(function(name){\n      console.log(name);\n    });\n\n    // Endpoint B\n    inbound.getName = function(){\n      return Paul;\n    }\n\nBlackbird can be used in node, in the browser per script tag and as an AMD\nmodule.\n\nFollow [@AronKornhall](http://twitter.com/AronKornhall) for news and updates\nregarding this library.\n\n##Example (iframe postMessage)\n###Embedded iframe\nThe embedded iframe exposes a method getName\n\n    // Define a transport\n    var transport = blackbird.transports.iframe(window.parent);\n\n    // Inbound interface (will be called from remote)\n    var inbound = {\n      getName: function(){\n        return 'Paul';\n      }\n    };\n\n    // Setup blackbird\n    blackbird(inbound, {}, transport);\n\n###Embedding iframe\nThe embedding iframe calls getName on embedded iframe\n\n    var iframe = document.getElementById('iframe');\n\n    // Define transport\n    var transport = blackbird.transports.iframe(iframe.contentWindow);\n\n    // Outbound interface (will be proxied to remote end)\n    var outbound = {\n      getName: function(){ }\n    };\n\n    // Setup blackbird\n    blackbird({}, outbound, transport);\n\n    // Call getName on remote\n    outbound.getName(function(err, name){\n      alert(name);\n    });\n\nFor a complete running example see `examples/iframe/index.html`\n\n##Install\nNode\n\n    npm install blackbird\n\nBrowser\n\n    bower install blackbird\n    or download blackbird.js\n\n##Test\n    npm test\n\n##Reference\n\n    blackbird(inbound, outbound, transport)\n\nSetup blackbird with the inbound interface `inbound`, outbount interface `outbound`\nand transport `transport`.\n\n__Arguments__\n \n    inbound   {Object} inbound interface containing method implementations that will\n              be called by remote endpoint\n \n    outbound  {Object} outbound interface with functions that will be called on remote\n              endpoint. The functions shouldn't be implemented, only defined\n \n    transport {Object} transport interface that should implement the following functions:\n        send(data)\n            data {String} the data to be sent to the remote endpoint\n        listen(fn)\n            fn {Function} registers fn as a listener for remote messages. fn accepts\n                          a single {String} as input parameter\n\n---------\n\n    blackbird.transports.iframe(targetWindow, sourceWindow, domain)\n\nShorthand for creating an iframe transport from `sourceWindow` to\n`targetWindow`. `domain` is a domain mask that can be used to limit to\nwhich domains messages can be sent.\n\n__Arguments__\n \n    targetWindow   {Object} the window to which we should send outgoing messages. To send messages to an embedded iframe use iframe.contentWindow (where iframe is the dom iframe element). To send data to the embedding (host) window of an embedded iframe as a target, use window.parent\n \n    sourceWindow   {Object} the window on which we should listen for incoming messages. Defaults to the global window.\n \n    domain  {String} the domain mask. Can be used to limit to which domains messages are sent. Defaults to '*' meaning any domain.\n\n##License \n\n(The MIT License)\n\nCopyright (c) 2014 Aron Kornhall \u003caron@optimalbits.com\u003e\n\nPermission is hereby granted, free of charge, to any person obtaining\na copy of this software and associated documentation files (the\n'Software'), to deal in the Software without restriction, including\nwithout limitation the rights to use, copy, modify, merge, publish,\ndistribute, sublicense, and/or sell copies of the Software, and to\npermit persons to whom the Software is furnished to do so, subject to\nthe following conditions:\n\nThe above copyright notice and this permission notice shall be\nincluded in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,\nEXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\nMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.\nIN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY\nCLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,\nTORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE\nSOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foptimalbits%2Fblackbird","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foptimalbits%2Fblackbird","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foptimalbits%2Fblackbird/lists"}