tart-stream-adapter

Stability: 1 - Experimental

Tiny Actor Run-Time in JavaScript adapter for Node.js streams.

Contributors

@dalnefre, @tristanls

Overview

Tiny Actor Run-Time in JavaScript adapter for Node.js streams.

• Usage
• Tests
• Documentation
• Sources

Usage

To run the below example run:

npm run readme

"use strict";

var fs = require('fs');
var path = require('path');
var stream = require('stream');
var streams = require('../index.js');
var tart = require('tart');

var sponsor = tart.minimal();

var reader = fs.createReadStream(
    path.normalize(path.join(__dirname, 'files', 'readFromMe.txt')));

var readData = sponsor(function data(message) {
    console.log('==1', 'readSeq', message.readSeq)
    console.log(message.chunk);
});
var readEnd = sponsor(function end() {
    console.log('==1', 'done reading');
});

var readCapabilities = streams.adapt(reader, {
    data: readData, 
    end: readEnd,
    encoding: 'utf8'
});

var reader2 = fs.createReadStream(
    path.normalize(path.join(__dirname, 'files', 'readFromMe.txt')));

var readEnd2 = sponsor(function end2() {
    console.log('=2=', 'done reading');
});

var printer = sponsor(function printer(message) {
    if (message.chunk != null) {
        var readSeq = message.readSeq;
        console.log('=2=', 'readSeq', readSeq);
        console.log(message.chunk.toString('utf8'));
        // read from next (32 byte) chunk
        message.next({readSeq: ++readSeq, size: 32, ok: this.self});
    } else {
        console.log('=2=', 'readSeq', message.readSeq);
        console.log('~null chunk~');
        // wait for readable to be triggered again, or end to be emitted
    }
});

var read;

var readable = sponsor(function readable(readSeq) {
     // stream is readable, read to printer (in 32 byte chunks)
    read({readSeq: readSeq, size: 32, ok: printer});
});

var readCapabilities = streams.adapt(reader2, {
    end: readEnd2,
    readable: readable
});
read = sponsor(readCapabilities.readBeh);

// delete files/writtenTo.txt before writing
var writeFileName = path.normalize(path.join(__dirname, 'files', 'writtenTo.txt'));
if (fs.existsSync(writeFileName)) {
    fs.unlinkSync(writeFileName);
}

var writer = fs.createWriteStream(writeFileName);

var writeCapabilities = streams.adapt(writer);
var write = sponsor(writeCapabilities.writeBeh);
var writeEnd = sponsor(writeCapabilities.endBeh);

var writeFinished = sponsor(function writeFinished() {
    console.log('3==', 'write finished, look in "examples/writtenTo.txt"');
});

writeEnd({chunk: 'finished', encoding: 'utf8', writeSeq: 10, ok: writeFinished})
write({chunk: 'zeroth\n', encoding: 'utf8', writeSeq: 0});
write({chunk: 'sixth\n', encoding: 'utf8', writeSeq: 6});
write({chunk: 'first\n', encoding: 'utf8', writeSeq: 1});
write({chunk: 'third\n', encoding: 'utf8', writeSeq: 3});
write({chunk: 'eight\n', encoding: 'utf8', writeSeq: 8});
write({chunk: 'fourth\n', encoding: 'utf8', writeSeq: 4});
write({chunk: 'second\n', encoding: 'utf8', writeSeq: 2});
write({chunk: 'ninth\n', encoding: 'utf8', writeSeq: 9});
write({chunk: 'seventh\n', encoding: 'utf8', writeSeq: 7});
write({chunk: 'fifth\n', encoding: 'utf8', writeSeq: 5});

Tests

npm test

Documentation

Public API

• streams.adapt(stream, options)
• streams.adaptReadable(stream, options)
• streams.adaptWritable(stream, options)

streams.adapt(stream, options)

• stream: Stream Node.js Stream.
• options: Object (Default: {})
  • close: Function function () {} Actor to receive 'close' event.
  • data: Function function (message) {} Actor to receive 'data' events.
    • message.chunk Buffer|String Data from the stream.
    • message.readSeq Integer Sequence number to read next.
  • drain: Function function () {} Actor to receive 'drain' event.
  • encoding: String The encoding to use for Readable, Duplex, or Transform stream.
  • end: Function function () {} Actor to receive 'end' event.
  • fail: Function function (error) {} Actor to receive 'error' events.
  • finish: Function function () {} Actor to receive 'finish' event.
  • readable: Function function (message) {} Actor to receive 'readable' event notification.
    • message.readSeq: Integer Sequence number to read next.
• Return: Object Capabilities wrapping the stream.

Adapts the stream to Tart. Returned Capabilities are:

• endBeh: Function function (message) {} End capability.
• pauseBeh: Function function (message) {} Pause capability.
• readBeh: Function function (message) {} Read capability.
• resumeBeh: Function function (message) {} Resume capability.
• unshiftBeh: Function function (message) {} Unshift capability.
• writeBeh: Function function (message) {} Write capability.

streams.adaptReadable(stream, options)

• stream: Stream Node.js Stream.
• options: Object (Default: {})
  • close: Function function () {} Actor to receive 'close' event.
  • data: Function function (message) {} Actor to receive 'data' events.
    • message.chunk Buffer|String Data from the stream.
    • message.readSeq Integer Sequence number to read next.
  • encoding: String The encoding to use for Readable, Duplex, or Transform stream.
  • end: Function function () {} Actor to receive 'end' event.
  • fail: Function function (error) {} Actor to receive 'error' events.
  • readable: Function function (message) {} Actor to receive 'readable' event notification.
    • message.readSeq: Integer Sequence number to read next.
• Return: Object Capabilities wrapping the readable stream.

Adapts a readable stream. Returned Capabilities are:

• pauseBeh: Function function (message) {} Pause capability.
• readBeh: Function function (message) {} Read capability.
• resumeBeh: Function function (message) {} Resume capability.
• unshiftBeh: Function function (message) {} Unshift capability.

streams.adaptWritable(stream, options)

• stream: Stream Node.js Stream.
• options: Object (Default: {})
  • drain: Function function () {} Actor to receive 'drain' event.
  • fail: Function function (error) {} Actor to receive 'error' events.
  • finish: Function function () {} Actor to receive 'finish' event.
• Return: Object Capabilities wrapping the writable stream.

Adapts the writable stream to Tart. Returned Capabilities are:

• endBeh: Function function (message) {} End capability.
• writeBeh: Function function (message) {} Write capability.

Sources

• Tiny Actor Run-Time (JavaScript)