archan

Archan

Array-like channels for co. Similar to chan except it keeps track of the number of pending callbacks and allows a coroutine to exit.

Example

var archan = require('archan')
var fs = require('fs')

// create a new channel
var ch = archan()

co(function* () {
  fs.readFile('file1.txt', ch.push())
  fs.readFile('file2.txt', ch.push())
  fs.readFile('file3.txt', ch.push())

  var text
  while (text = yield* ch.shift()) {
    // contents of one of the three text files
    console.log(text.toString('utf8'))
  }

  console.log('all done!')
  process.exit()
})()

API

var ch = archan()

Creates a new channel instance.

var cb = ch.push()

Returns a new callback you pass to asynchronous functions.

fs.readFile('file.txt', ch.push())
var buffer = yield ch.shift()
request('https://github.com', ch.push())
var result = yield ch.shift()

Note that each callback returned from ch.push() is single use only. If you use a callback more or less than once, things are going to go badly with your channel. For example, for emitters, you would want to do something like this:

var ch = archan()

var stream = fs.createWriteStream('file.txt')
var cb = ch.push()
stream.once('error', cb)
stream.once('finish', cb)
yield* ch.shift()

ch.push(val...)

Push a value to the channel synchronously. If you push any values, a callback will not be returned. Multiple arguments will be combined into a single array.

ch.push(1) // adds 1
ch.push(1, 2, 3) // adds [1, 2, 3]
ch.push(new Error()) // adds an error, will be thrown on next .shift()

var val = yield* ch.shift()

Returns the next value in the channel. The * is optional. If there are no more pending callbacks, it will return undefined.

var val = yield* ch.read()

An alias for ch.shift(). This alias demonstrates archan's synonymity with Readable Streams in object mode:

var stream = archan()
stream.push('first')
stream.push('second')
stream.push('third')
stream.push(null)

assert.equal('first', yield stream.read())
assert.equal('second', yield stream.read())
assert.equal('third', yield stream.read())
assert.equal(null, yield stream.read())

Note that unlike node's streams, order is not preserved, specifically with asynchronous functions.

ch.length

The number of values in the channel, both pending and ready. Note that if you ever return a falsey value in any of your callbacks, the while loop in the example will not work as expected. Instead, you should check ch.length:

var ch = archan()

setTimeout(ch.push(), 1)
setTimeout(ch.push(), 10)
setTimeout(ch.push(), 100)
setTimeout(ch.push(), 1000)

var count = 0
while (ch.length) {
  yield ch.shift()
  count++
}

assert.equal(count, 4)

var values = yield* ch.end()

Return all the pending values at once. At this point, the channel will be empty and you will be able to reuse it. This is a shortcut for:

var values = []
while (ch.length) {
  values.push(yield* ch.shift())
}

License

The MIT License (MIT)

Copyright (c) 2013 Jonathan Ong [e-mail]

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.