@rauschma/stringio

stringio: convert strings to Node.js streams and vice versa

npm install @rauschma/stringio

Strings ↔︎ streams

See line A and line B:

import * as assert from 'assert';
import { StringStream, readableToString } from '@rauschma/stringio';

test('From string to stream to string', async () => {
  const str = 'Hello!\nHow are you?\n';
  const stringStream = new StringStream(str); // (A)
  const result = await readableToString(stringStream); // (B)
  assert.strictEqual(result, str);
});

StringStream: from string to stream

declare class StringStream extends Readable {
  constructor(str: string);
}

Used in line A.

readableToString: from stream to string

declare function readableToString(readable: Readable, encoding?: string): Promise<string>;

Default encoding is 'utf-8'.

Used in line B.

Reading stdin into a string

async function readStdin() {
  const str = await readableToString(process.stdin);
  console.log('STR: '+str);
}

Related npm packages

• string-to-stream: Convert a string into a stream.
• get-stream: Get a stream as a string, buffer, or array.

Asynchronous iterables

chunksToLinesAsync: async iterable over chunks to async iterable over lines

declare function chunksToLinesAsync(chunks: AsyncIterable<string>): AsyncIterable<string>;

Each line includes the line break at the end (if any – the last line may not have one).

Example (starting with Node.js v.10, readable streams are asynchronous iterables):

const fs = require('fs');
const {chunksToLinesAsync} = require('@rauschma/stringio');

async function main() {
  const stream = fs.createReadStream(process.argv[2]);
    // Works, too: const stream = process.stdin;
  for await (const line of chunksToLinesAsync(stream)) {
    console.log(chomp(line));
  }
}
main();

Promisified writing to streams

declare function streamWrite(
  stream: Writable,
  chunk: string | Buffer | Uint8Array,
  encoding = 'utf8')
  : Promise<void>;

declare function streamEnd(
  stream: Writable)
  : Promise<void>;

Usage:

await streamWrite(someStream, 'abc');
await streamWrite(someStream, 'def');
await streamEnd(someStream);

onExit(childProcess): wait until a child process is finished

export declare function onExit(childProcess: ChildProcess): Promise<void>;

Usage:

const childProcess = child_process.spawn(···);
await onExit(childProcess);

Errors emitted by childProcess or a non-zero exit code reject the Promise returned by onExit().

String helper function

chomp: remove a line break at the end of a line

declare function chomp(line: string): string;

Further reading

The following 2ality blog posts use stringio:

• Reading streams via async iteration in Node.js
• Working with stdout and stdin of a child process in Node.js

Acknowledgements

• StringStream is inspired by: https://github.com/feross/string-to-stream/blob/master/index.js