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