152 lines
3.7 KiB
Markdown
152 lines
3.7 KiB
Markdown
# Mhysa
|
|
|
|
**Streams and event emitter utils for Node.js**
|
|
|
|
## Installation
|
|
|
|
```sh
|
|
yarn add mhysa
|
|
```
|
|
|
|
## Basic Usage
|
|
|
|
The following snippet demonstrates most of Mhysa's current features without much explanation. More
|
|
will come!
|
|
|
|
```js
|
|
const {
|
|
utils: { sleep, delay, once },
|
|
...Mhysa
|
|
} = require("mhysa");
|
|
|
|
async function main() {
|
|
const collector = Mhysa.concat(
|
|
Mhysa.fromArray(["a\n", "b\n", "c\n"]),
|
|
Mhysa.fromArray(["d", "e"]).pipe(Mhysa.join("-")),
|
|
)
|
|
.pipe(Mhysa.split("\n"))
|
|
.pipe(
|
|
Mhysa.flatMap(async s => {
|
|
await sleep(100);
|
|
return delay([s, s.toUpperCase()], 100);
|
|
}),
|
|
)
|
|
.pipe(Mhysa.collect({ objectMode: true }));
|
|
|
|
const collected = await once(collector, "data");
|
|
console.log(collected); // [ 'a', 'A', 'b', 'B', 'c', 'C', 'd-e', 'D-E' ] (after 6 * 100 ms)
|
|
}
|
|
main();
|
|
```
|
|
|
|
## API
|
|
|
|
```ts
|
|
/**
|
|
* Convert an array into a readable stream of its elements
|
|
* @param array The array of elements to stream
|
|
*/
|
|
fromArray(array: any[]): NodeJS.ReadableStream;
|
|
|
|
/**
|
|
* Return a ReadWrite stream that maps streamed chunks
|
|
* @param mapper The mapper function, mapping each (chunk, encoding) to a new chunk (or a promise of such)
|
|
* @param options
|
|
* @param options.readableObjectMode Whether this stream should behave as a readable stream of objects
|
|
* @param options.writableObjectMode Whether this stream should behave as a writable stream of objects
|
|
*/
|
|
map<T, R>(
|
|
mapper: (chunk: T, encoding: string) => R,
|
|
options?: ThroughOptions,
|
|
): NodeJS.ReadWriteStream;
|
|
|
|
/**
|
|
* Return a ReadWrite stream that flat maps streamed chunks
|
|
* @param mapper The mapper function, mapping each (chunk, encoding) to an array of new chunks (or a promise of such)
|
|
* @param options
|
|
* @param options.readableObjectMode Whether this stream should behave as a readable stream of objects
|
|
* @param options.writableObjectMode Whether this stream should behave as a writable stream of objects
|
|
*/
|
|
flatMap<T, R>(
|
|
mapper:
|
|
| ((chunk: T, encoding: string) => R[])
|
|
| ((chunk: T, encoding: string) => Promise<R[]>),
|
|
options?: ThroughOptions,
|
|
): NodeJS.ReadWriteStream;
|
|
|
|
/**
|
|
* Return a ReadWrite stream that splits streamed chunks using the given separator
|
|
* @param separator The separator to split by, defaulting to "\n"
|
|
*/
|
|
split(
|
|
separator?: string | RegExp,
|
|
): NodeJS.ReadWriteStream;
|
|
|
|
/**
|
|
* Return a ReadWrite stream that joins streamed chunks using the given separator
|
|
* @param separator The separator to join with
|
|
*/
|
|
join(separator: string): NodeJS.ReadWriteStream;
|
|
|
|
/**
|
|
* Return a ReadWrite stream that collects streamed chunks into an array or buffer
|
|
* @param options
|
|
* @param options.objectMode Whether this stream should behave as a stream of objects
|
|
*/
|
|
collect(
|
|
options?: ReadableOptions,
|
|
): NodeJS.ReadWriteStream;
|
|
|
|
/**
|
|
* Return a stream of readable streams concatenated together
|
|
* @param streams The readable streams to concatenate
|
|
*/
|
|
concat(
|
|
...streams: NodeJS.ReadableStream[]
|
|
): NodeJS.ReadableStream;
|
|
|
|
```
|
|
|
|
### Interfaces
|
|
|
|
```ts
|
|
interface ReadableOptions {
|
|
objectMode?: boolean;
|
|
}
|
|
|
|
interface ThroughOptions {
|
|
readableObjectMode?: boolean;
|
|
writableObjectMode?: boolean;
|
|
}
|
|
```
|
|
|
|
### { utils }
|
|
|
|
```ts
|
|
/**
|
|
* Resolve after the given delay in milliseconds
|
|
*
|
|
* @param ms The number of milliseconds to wait
|
|
*/
|
|
sleep(ms: number): Promise<{}>;
|
|
|
|
/**
|
|
* Resolve a value after the given delay in milliseconds
|
|
*
|
|
* @param value Value to resolve
|
|
* @param ms Number of milliseconds to wait
|
|
*/
|
|
delay<T>(value: T, ms: number): Promise<T>;
|
|
|
|
/**
|
|
* Resolve once the given event emitter emits the specified event
|
|
*
|
|
* @param emitter Event emitter to watch
|
|
* @param event Event to watch
|
|
*/
|
|
once<T>(
|
|
emitter: NodeJS.EventEmitter,
|
|
event: string,
|
|
): Promise<T>;
|
|
```
|