README.md (1772B)
1 # once 2 3 Only call a function once. 4 5 ## usage 6 7 ```javascript 8 var once = require('once') 9 10 function load (file, cb) { 11 cb = once(cb) 12 loader.load('file') 13 loader.once('load', cb) 14 loader.once('error', cb) 15 } 16 ``` 17 18 Or add to the Function.prototype in a responsible way: 19 20 ```javascript 21 // only has to be done once 22 require('once').proto() 23 24 function load (file, cb) { 25 cb = cb.once() 26 loader.load('file') 27 loader.once('load', cb) 28 loader.once('error', cb) 29 } 30 ``` 31 32 Ironically, the prototype feature makes this module twice as 33 complicated as necessary. 34 35 To check whether you function has been called, use `fn.called`. Once the 36 function is called for the first time the return value of the original 37 function is saved in `fn.value` and subsequent calls will continue to 38 return this value. 39 40 ```javascript 41 var once = require('once') 42 43 function 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 55 Throw an error if the function is called twice. 56 57 Some functions are expected to be called only once. Using `once` for them would 58 potentially hide logical errors. 59 60 In the example below, the `greet` function has to call the callback only once: 61 62 ```javascript 63 function greet (name, cb) { 64 // return is missing from the if statement 65 // when no name is passed, the callback is called twice 66 if (!name) cb('Hello anonymous') 67 cb('Hello ' + name) 68 } 69 70 function log (msg) { 71 console.log(msg) 72 } 73 74 // this will print 'Hello anonymous' but the logical error will be missed 75 greet(null, once(msg)) 76 77 // once.strict will print 'Hello anonymous' and throw an error when the callback will be called the second time 78 greet(null, once.strict(msg)) 79 ```