{"id":15547289,"url":"https://github.com/uhop/stream-join","last_synced_at":"2025-04-23T18:23:44.194Z","repository":{"id":57372007,"uuid":"142500049","full_name":"uhop/stream-join","owner":"uhop","description":"stream-join is the micro-module to join values of multiple streams together.","archived":false,"fork":false,"pushed_at":"2020-07-11T05:01:14.000Z","size":19,"stargazers_count":7,"open_issues_count":2,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-21T06:09:28.361Z","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/uhop.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":"2018-07-26T22:25:52.000Z","updated_at":"2024-02-29T20:30:48.000Z","dependencies_parsed_at":"2022-09-15T17:01:22.979Z","dependency_job_id":null,"html_url":"https://github.com/uhop/stream-join","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uhop%2Fstream-join","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uhop%2Fstream-join/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uhop%2Fstream-join/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uhop%2Fstream-join/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uhop","download_url":"https://codeload.github.com/uhop/stream-join/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250488363,"owners_count":21438770,"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-10-02T13:08:32.787Z","updated_at":"2025-04-23T18:23:44.172Z","avatar_url":"https://github.com/uhop.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# stream-join [![NPM version][npm-img]][npm-url]\n\n[npm-img]: https://img.shields.io/npm/v/stream-join.svg\n[npm-url]: https://npmjs.org/package/stream-join\n\n`stream-join` is a function, which takes an array of object mode [Readable](https://nodejs.org/api/stream.html#stream_readable_streams) streams and returns a combined object mode `Readable` stream, which pack together corresponding values from input streams, while properly handling [backpressure](https://nodejs.org/en/docs/guides/backpressuring-in-streams/).\n\nOriginally `stream-join` was used with [stream-json](https://www.npmjs.com/package/stream-json) to create and eventually join side-channels but can be used stand-alone.\n\n`stream-join` is a lightweight, no-dependencies micro-package. It is distributed under New BSD license.\n\n## Intro\n\nBy default `stream-join` creates a stream of arrays of values. The first array contains the first values of all streams and the `N`th array value comes from the `N`th stream. Their respective order doesn't matter. The second array will contain the second values of all streams. And so on. If the corresponding stream has ended, `null` is going to be used as its value (object mode streams cannot use `null` values because it indicates the end-of-stream). The resulting stream will end when all streams have ended.\n\n```js\nconst join = require('stream-join');\n\nconst {PassThrough} = require('stream-join/tests/helpers');\n\nconst s1 = new PassThrough(), s2 = new PassThrough(),\n  result = join([s1, s2]);\n\nresult.on('data', data =\u003e console.log(data));\n\n// all streams are written asynchronously\ns2.write('a');\ns1.write(1);\ns1.write(2);\ns2.write('b');\ns1.write(3);\ns2.end();\ns1.write(4);\ns1.end();\n\n// prints:\n// [1, 'a']\n// [2, 'b']\n// [3, null] // s2 has ended\n// [4, null]\n```\n\nThe output can be controlled by a custom joining function. Given the setup above:\n\n```js\nconst s1 = new PassThrough(), s2 = new PassThrough(),\n  result = join([s1, s2], {\n    joinItems(output, items) {\n      // a variable number of values is pushed out\n      items.forEach(item =\u003e {\n        // we should push only non-null values\n        if (item !== null) output.push(item);\n      });\n    }\n  });\n\nresult.on('data', data =\u003e console.log(data));\n\n// all streams are written asynchronously\ns2.write('a');\ns1.write(1);\ns1.write(2);\ns2.write('b');\ns1.write(3);\ns2.end();\ns1.write(4);\ns1.end();\n\n// now we normalized the order of values\n// prints: 1, 'a', 2, 'b', 3, 4\n```\n\n## Installation\n\n```bash\nnpm i --save stream-join\n# or: yarn add stream-join\n```\n\n## Documentation\n\nThe module returns a function, whose prototype is:\n\n```js\nconst join = require('stream-join');\n\nconst result = join(streams[, options]);\n```\n\nWhere:\n\n* `streams` is an array of object mode [Readable](https://nodejs.org/api/stream.html#stream_readable_streams) streams.\n* `options` is an optional object detailed in the [Node's documentation](https://nodejs.org/api/stream.html#stream_new_stream_readable_options) used to create `result`.\n  * The following properties are always overridden:\n    * `objectMode` is always `true`.\n    * `read()` is replaced with an internal implementation.\n  * The following custom properties are recognized:\n    * `skipEvents` is an optional flag. If it is falsy (the default), `'error'` events from all streams are forwarded to `result`. If it is truthy, no event forwarding is made. A user can always do so manually.\n    * `joinItems(output, items)` is an optional function. It can be used to combine individual values together. It may push to the output 0 or more values. It returns no value and takes two arguments:\n      * `output` is a `result` object described below. It can be used to push values with a method `push()`.\n        * *Warning:* never push out `null` values because they indicate that a stream has been finished and should be closed.\n      * `items` is an array of values. It has the same length as `streams` and contains values from corresponding streams. If a corresponding stream has ended, `null` is going to be used as a value.\n* `result` is an object mode [Readable](https://nodejs.org/api/stream.html#stream_readable_streams) stream, which produces combined values.\n\nSee the Introduction above for examples of how to use `stream-join`.\n\n## Release History\n\n- 1.0.1 *technical release, no need to upgrade.*\n- 1.0.0 *the initial release.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuhop%2Fstream-join","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuhop%2Fstream-join","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuhop%2Fstream-join/lists"}