diff --git a/README.md b/README.md index 137ff84..e37caa9 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,12 @@ Convert an array into a `Readable` stream of its elements | --- | --- | --- | | `array` | `T[]` | Array of elements to stream | +```js +Mhysa.fromArray(["a", "b"]) + .pipe(process.stdout); +// ab is printed out +``` + ## map(mapper, options) Return a `ReadWrite` stream that maps streamed chunks @@ -28,6 +34,13 @@ Return a `ReadWrite` stream that maps streamed chunks | `options.readableObjectMode` | `boolean` | Whether this stream should behave as a readable stream of objects | | `options.writableObjectMode` | `boolean` | Whether this stream should behave as a writable stream of objects | +```js +Mhysa.fromArray(["a", "b"]) + .pipe(Mhysa.map(s => s.toUpperCase())) + .pipe(process.stdout); +// AB is printed out +``` + ## flatMap(mapper, options) Return a `ReadWrite` stream that flat maps streamed chunks @@ -39,6 +52,13 @@ Return a `ReadWrite` stream that flat maps streamed chunks | `options.readableObjectMode` | `boolean` | Whether this stream should behave as a readable stream of objects | | `options.writableObjectMode` | `boolean` | Whether this stream should behave as a writable stream of objects | +```js +Mhysa.fromArray(["a", "AA"]) + .pipe(Mhysa.flatMap(s => new Array(s.length).fill(s))) + .pipe(process.stdout); +// aAAAA is printed out +``` + ## filter(predicate, options) Return a `ReadWrite` stream that filters out streamed chunks for which the predicate does not hold @@ -49,6 +69,13 @@ Return a `ReadWrite` stream that filters out streamed chunks for which the predi | `options` | `object` | | | `options.objectMode` | `boolean` | `boolean` | Whether this stream should behave as a stream of objects | +```js +Mhysa.fromArray(["a", "b", "c"]) + .pipe(Mhysa.filter(s => s !== "b")) + .pipe(process.stdout); +// ac is printed out +``` + ## reduce(iteratee, initialValue, options) Return a `ReadWrite` stream that reduces streamed chunks down to a single value and yield that @@ -62,6 +89,14 @@ value | `options.readableObjectMode` | `boolean` | Whether this stream should behave as a readable stream of objects | | `options.writableObjectMode` | `boolean` | Whether this stream should behave as a writable stream of objects | +```js +Mhysa.fromArray(["a", "b", "cc"]) + .pipe(Mhysa.reduce((acc, s) => ({ ...acc, [s]: s.length }), {})) + .pipe(Mhysa.stringify()) + .pipe(process.stdout); +// {"a":1,"b":1","c":2} is printed out +``` + ## split(separator) Return a `ReadWrite` stream that splits streamed chunks using the given separator @@ -70,6 +105,14 @@ Return a `ReadWrite` stream that splits streamed chunks using the given separato | --- | --- | --- | | `separator` | `string` | Separator to split by, defaulting to `"\n"` | +```js +Mhysa.fromArray(["a,b", "c,d"]) + .pipe(Mhysa.split(",")) + .pipe(Mhysa.join("|")) + .pipe(process.stdout); +// a|b|c|d is printed out +``` + ## join(separator) Return a `ReadWrite` stream that joins streamed chunks using the given separator @@ -78,6 +121,13 @@ Return a `ReadWrite` stream that joins streamed chunks using the given separator | --- | --- | --- | | `separator` | `string` | Separator to join with | +```js +Mhysa.fromArray(["a", "b", "c"]) + .pipe(Mhysa.join(",")) + .pipe(process.stdout); +// a,b,c is printed out +``` + ## replace(searchValue, replaceValue) Return a `ReadWrite` stream that replaces occurrences of the given string or regular expression in @@ -88,13 +138,36 @@ the streamed chunks with the specified replacement string | `searchValue` | `string | RegExp` | Search string to use | | `replaceValue` | `string` | Replacement string to use | +```js +Mhysa.fromArray(["a1", "b22", "c333"]) + .pipe(Mhysa.replace(/b\d+/, "B")) + .pipe(process.stdout); +// a1Bc333 is printed out +``` + ## parse() Return a `ReadWrite` stream that parses the streamed chunks as JSON +```js +Mhysa.fromArray(['{ "a": "b" }']) + .pipe(Mhysa.parse()) + .once("data", object => console.log(object)); +// { a: 'b' } is printed out +``` + + ## stringify() Return a `ReadWrite` stream that stringifies the streamed chunks to JSON +```js +Mhysa.fromArray([{ a: "b" }]) + .pipe(Mhysa.stringify()) + .pipe(process.stdout); +// {"a":"b"} is printed out +``` + + ## collect(options) Return a `ReadWrite` stream that collects streamed chunks into an array or buffer @@ -103,6 +176,13 @@ Return a `ReadWrite` stream that collects streamed chunks into an array or buffe | `options` | `object` | | | `options.objectMode` | `boolean` | Whether this stream should behave as a stream of objects | +```js +Mhysa.fromArray(["a", "b", "c"]) + .pipe(Mhysa.collect({ objectMode: true })) + .once("data", object => console.log(object)); +// [ 'a', 'b', 'c' ] is printed out +``` + ## concat(streams) Return a `Readable` stream of readable streams concatenated together @@ -111,6 +191,19 @@ Return a `Readable` stream of readable streams concatenated together | --- | --- | --- | | `streams` | `...Readable[]` | Readable streams to concatenate | +```js +const source1 = new Readable(); +const source2 = new Readable(); +Mhysa.concat(source1, source2).pipe(process.stdout) +source1.push("a1 "); +source2.push("c3 "); +source1.push("b2 "); +source2.push("d4 "); +source1.push(null); +source2.push(null); +// a1 b2 c3 d4 is printed out +``` + ## merge(streams) Return a `Readable` stream of readable streams merged together in chunk arrival order @@ -119,6 +212,19 @@ Return a `Readable` stream of readable streams merged together in chunk arrival | --- | --- | --- | | `streams` | `...Readable[]` | Readable streams to merge | +```js +const source1 = new Readable({ read() {} }); +const source2 = new Readable({ read() {} }); +Mhysa.merge(source1, source2).pipe(process.stdout); +source1.push("a1 "); +setTimeout(() => source2.push("c3 "), 10); +setTimeout(() => source1.push("b2 "), 20); +setTimeout(() => source2.push("d4 "), 30); +setTimeout(() => source1.push(null), 40); +setTimeout(() => source2.push(null), 50); +// a1 c3 b2 d4 is printed out +``` + ## duplex(writable, readable) Return a `Duplex` stream from a writable stream that is assumed to somehow, when written to, @@ -129,6 +235,14 @@ cause the given readable stream to yield chunks | `writable` | `Writable` | Writable stream assumed to cause the readable stream to yield chunks when written to | | `readable` | `Readable` | Readable stream assumed to yield chunks when the writable stream is written to | +```js +const catProcess = require("child_process").exec("grep -o ab"); +Mhysa.fromArray(["a", "b", "c"]) + .pipe(Mhysa.duplex(catProcess.stdin, catProcess.stdout)) + .pipe(process.stdout); +// ab is printed out +``` + ## child(childProcess) Return a `Duplex` stream from a child process' stdin and stdout @@ -137,6 +251,14 @@ Return a `Duplex` stream from a child process' stdin and stdout | --- | --- | --- | | childProcess | `ChildProcess` | Child process from which to create duplex stream | +```js +const catProcess = require("child_process").exec("grep -o ab"); +Mhysa.fromArray(["a", "b", "c"]) + .pipe(Mhysa.child(catProcess)) + .pipe(process.stdout); +// ab is printed out +``` + ## last(readable) Return a `Promise` resolving to the last streamed chunk of the given readable stream, after it has @@ -145,3 +267,12 @@ ended | Param | Type | Description | | --- | --- | --- | | `readable` | `Readable` | Readable stream to wait on | + +```js +let f = async () => { + const source = Mhysa.fromArray(["a", "b", "c"]); + console.log(await Mhysa.last(source)); +}; +f(); +// c is printed out +``` diff --git a/samples/collect.js b/samples/collect.js new file mode 100644 index 0000000..0e48e9f --- /dev/null +++ b/samples/collect.js @@ -0,0 +1,5 @@ +const Mhysa = require("mhysa"); + +Mhysa.fromArray(["a", "b", "c"]) + .pipe(Mhysa.collect({ objectMode: true })) + .on("data", object => console.log(object)); diff --git a/samples/concat.js b/samples/concat.js index a3acd30..7295dcf 100644 --- a/samples/concat.js +++ b/samples/concat.js @@ -1,19 +1,15 @@ -const fs = require("fs"); -const path = require("path"); +const { Readable } = require("stream"); const Mhysa = require("mhysa"); -const sourceFile1 = path.join(process.cwd(), "package.json"); -const sourceFile2 = path.join(process.cwd(), "README.md"); -const outputDir = path.join(process.cwd(), "sample_output"); -const outputFile = path.join(outputDir, "concat_files.txt"); +const source1 = new Readable(); +const source2 = new Readable(); +const expectedElements = ["a", "b", "c", "d"]; +let i = 0; +Mhysa.concat(source1, source2).pipe(process.stdout); -if (!fs.existsSync(outputDir)) { - fs.mkdirSync(outputDir, { recursive: true }); -} - -// Concat two source files together into one -Mhysa.concat( - fs.createReadStream(sourceFile1), - Mhysa.fromArray(["\n"]), - fs.createReadStream(sourceFile2), -).pipe(process.stdout); +source1.push("a"); +source2.push("c"); +source1.push("b"); +source2.push("d"); +source1.push(null); +source2.push(null); diff --git a/samples/duplex.js b/samples/duplex.js new file mode 100644 index 0000000..363cd3a --- /dev/null +++ b/samples/duplex.js @@ -0,0 +1,5 @@ +const Mhysa = require("mhysa"); +const catProcess = require("child_process").exec("grep -o ab"); +Mhysa.fromArray(["a", "b", "c"]) + .pipe(Mhysa.duplex(catProcess.stdin, catProcess.stdout)) + .pipe(process.stdout); diff --git a/samples/last.js b/samples/last.js new file mode 100644 index 0000000..eb74c9c --- /dev/null +++ b/samples/last.js @@ -0,0 +1,7 @@ +const Mhysa = require("mhysa"); + +let f = async () => { + const source = Mhysa.fromArray(["a", "b", "c"]); + console.log(await Mhysa.last(source)); +}; +f(); diff --git a/samples/merge.js b/samples/merge.js new file mode 100644 index 0000000..bb7b1e9 --- /dev/null +++ b/samples/merge.js @@ -0,0 +1,12 @@ +const { Readable } = require("stream"); +const Mhysa = require("mhysa"); + +const source1 = new Readable({ read() {} }); +const source2 = new Readable({ read() {} }); +Mhysa.merge(source1, source2).pipe(process.stdout); +source1.push("a1 "); +setTimeout(() => source2.push("c3 "), 10); +setTimeout(() => source1.push("b2 "), 20); +setTimeout(() => source2.push("d4 "), 30); +setTimeout(() => source1.push(null), 40); +setTimeout(() => source2.push(null), 50); diff --git a/samples/parse.js b/samples/parse.js new file mode 100644 index 0000000..791ed56 --- /dev/null +++ b/samples/parse.js @@ -0,0 +1,5 @@ +const Mhysa = require("mhysa"); + +Mhysa.fromArray(['{ "a": "b" }']) + .pipe(Mhysa.parse()) + .on("data", object => console.log(object)); diff --git a/samples/replace.js b/samples/replace.js new file mode 100644 index 0000000..f0ab201 --- /dev/null +++ b/samples/replace.js @@ -0,0 +1,5 @@ +const Mhysa = require("mhysa"); + +Mhysa.fromArray(["a1", "b22", "c333"]) + .pipe(Mhysa.replace(/b\d+/, "B")) + .pipe(process.stdout); diff --git a/samples/stringify.js b/samples/stringify.js new file mode 100644 index 0000000..a3ae7be --- /dev/null +++ b/samples/stringify.js @@ -0,0 +1,5 @@ +const Mhysa = require("mhysa"); + +Mhysa.fromArray([{ a: "b" }]) + .pipe(Mhysa.stringify()) + .pipe(process.stdout);