Streams convention

From the realtime streams discussion.

There are three generic possible types of streams, corresponding to notions of data source, data transform and data output. In different stream worlds they are called differently, in pull-streams that is source, through and sink; in classic streams that is Readable, Transform and Writable.

In audiojs we use plain function as a default package exports, with the signatures described below. Because we can wrap any of these functions easily to any stream interface.

Source/Readable:

// sync source
module.exports = function (options) {
  return function read (buffer|length?) {
    //if buffer is passed, it should be filled instead of created
    //if length is passed, a new buffer of that length should be created
    //return null to indicate end
    return buffer
  }
}

// async source
module.exports = function (options) {
  //pass null as a callback to indicate the end
  return function read (buffer|length?, cb) {
    //cb(null, null) to end
    //cb(error) to throw error
    cb(null, buffer)
  }
}

Through/map:

// sync through
module.exports = function (options) {
  return function transform (buffer) {
    //return null to end
    return buffer
  }
}

// async through
module.exports = function (options) {
  return function transform (buffer, cb) {
    //cb(null, null) to end
    //cb(error) to throw error
    cb(null, buffer)
  }
}

By coincidence, transform is very similar to read by signature.

Sink/destination/writable:

// sync sink
module.exports = function (options) {
  return function write (buffer) {
    // do stuff
    // throw error
    // if buffer is null - end writer
  }
}

// async sink
module.exports = function (options) {
  //do urgent end
  write.end = function () {}  

  return write;

  function write (buffer, cb) {
    // do stuff
    // if buffer is null - plan ending
    cb(err, data);
  }
}

Note that returned function may have end method defined to explicitly and urgently ❗ end stream. That is valid for all types of streams.