www.aleph1.co.uk Git - yaffs-website/blob - node_modules/once/README.md

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