l0bsterssg

node.js static responsive blog post generator
Log | Files | Refs | README

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 ```