strong-tie/inbound-calls

1# once2 3Only call a function once.4 5## usage6 7```javascript8var once = require('once')9 10function load (file, cb) {11  cb = once(cb)12  loader.load('file')13  loader.once('load', cb)14  loader.once('error', cb)15}16```17 18Or add to the Function.prototype in a responsible way:19 20```javascript21// only has to be done once22require('once').proto()23 24function load (file, cb) {25  cb = cb.once()26  loader.load('file')27  loader.once('load', cb)28  loader.once('error', cb)29}30```31 32Ironically, the prototype feature makes this module twice as33complicated as necessary.34 35To check whether you function has been called, use `fn.called`. Once the36function is called for the first time the return value of the original37function is saved in `fn.value` and subsequent calls will continue to38return this value.39 40```javascript41var once = require('once')42 43function load (cb) {44  cb = once(cb)45  var stream = createStream()46  stream.once('data', cb)47  stream.once('end', function () {48    if (!cb.called) cb(new Error('not found'))49  })50}51```52 53## `once.strict(func)`54 55Throw an error if the function is called twice.56 57Some functions are expected to be called only once. Using `once` for them would58potentially hide logical errors.59 60In the example below, the `greet` function has to call the callback only once:61 62```javascript63function greet (name, cb) {64  // return is missing from the if statement65  // when no name is passed, the callback is called twice66  if (!name) cb('Hello anonymous')67  cb('Hello ' + name)68}69 70function log (msg) {71  console.log(msg)72}73 74// this will print 'Hello anonymous' but the logical error will be missed75greet(null, once(msg))76 77// once.strict will print 'Hello anonymous' and throw an error when the callback will be called the second time78greet(null, once.strict(msg))79```80