0
# Once
1
2
Once is a utility library that ensures any given function can only be executed once, returning the cached result of the first execution on subsequent calls. It provides both a regular 'once' wrapper that silently returns the cached value and a 'strict' variant that throws an error on repeated calls, helping developers catch logic errors where functions are accidentally called multiple times.
3
4
## Package Information
5
6
- **Package Name**: once
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install once`
10
11
## Core Imports
12
13
```javascript
14
var once = require('once');
15
```
16
17
**Note**: This package uses CommonJS format only. ES modules can import it using:
18
19
```javascript
20
import once from 'once';
21
```
22
23
However, the above may require bundler configuration or Node.js compatibility features.
24
25
## Basic Usage
26
27
```javascript
28
var once = require('once');
29
30
function load(file, cb) {
31
cb = once(cb);
32
loader.load('file');
33
loader.once('load', cb);
34
loader.once('error', cb);
35
}
36
```
37
38
## Capabilities
39
40
### Function Wrapping with Caching
41
42
Wraps a function to ensure it can only be called once, returning the cached result on subsequent calls.
43
44
```javascript { .api }
45
/**
46
* Wraps a function to ensure it can only be called once
47
* @param {Function} fn - The function to wrap
48
* @returns {Function} Wrapped function with caching behavior and state properties
49
*/
50
function once(fn);
51
```
52
53
The returned function has these properties:
54
- `called` (Boolean): Whether the function has been called (initially false)
55
- `value` (Any): Cached return value from first execution (undefined until called)
56
57
**Important:** The wrapped function preserves all original function properties and maintains the original function's `this` context when called.
58
59
**Usage Examples:**
60
61
```javascript
62
var once = require('once');
63
64
function expensiveOperation(data) {
65
console.log('Computing...');
66
return data * 2;
67
}
68
69
var cachedOperation = once(expensiveOperation);
70
71
console.log(cachedOperation(5)); // Logs "Computing..." then returns 10
72
console.log(cachedOperation(5)); // Returns 10 immediately (no logging)
73
console.log(cachedOperation.called); // true
74
console.log(cachedOperation.value); // 10
75
76
// Property and context preservation example
77
function Calculator(multiplier) {
78
this.multiplier = multiplier;
79
}
80
81
Calculator.prototype.compute = function(value) {
82
return value * this.multiplier;
83
};
84
85
Calculator.prototype.compute.customProperty = 'preserved';
86
87
var calc = new Calculator(3);
88
var onceCompute = once(calc.compute);
89
90
// Properties are preserved
91
console.log(onceCompute.customProperty); // 'preserved'
92
93
// Context is preserved when using call/apply
94
console.log(onceCompute.call(calc, 5)); // 15 (5 * 3)
95
console.log(onceCompute.call(calc, 10)); // 15 (cached result)
96
```
97
98
### Strict Function Wrapping
99
100
Strict variant that throws an error when called more than once, helping catch logic errors.
101
102
```javascript { .api }
103
/**
104
* Wraps a function to throw an error if called more than once
105
* @param {Function} fn - The function to wrap
106
* @returns {Function} Wrapped function that throws on subsequent calls
107
*/
108
once.strict(fn);
109
```
110
111
The returned function has these properties:
112
- `called` (Boolean): Whether the function has been called (initially false)
113
- `value` (Any): Return value from first execution
114
- `onceError` (String): Error message for multiple calls (can be customized)
115
116
**Important:** The wrapped function preserves all original function properties and maintains the original function's `this` context when called.
117
118
**Usage Examples:**
119
120
```javascript
121
var once = require('once');
122
123
function greet(name, cb) {
124
if (!name) return cb('Hello anonymous');
125
cb('Hello ' + name);
126
}
127
128
function log(msg) {
129
console.log(msg);
130
}
131
132
// Using strict mode to catch logic errors
133
greet(null, once.strict(log));
134
// First call: logs "Hello anonymous"
135
// Second call: throws Error: "log shouldn't be called more than once"
136
```
137
138
**Custom Error Messages:**
139
140
```javascript
141
var strictFn = once.strict(someFunction);
142
strictFn.onceError = 'Custom error message';
143
// Now throws: Error: "Custom error message"
144
```
145
146
### Prototype Extension
147
148
Extends Function.prototype with `once` and `onceStrict` methods for convenient usage.
149
150
```javascript { .api }
151
/**
152
* Extends Function.prototype with once and onceStrict methods
153
* @returns {undefined}
154
*/
155
once.proto();
156
```
157
158
After calling `once.proto()`, all functions gain these methods:
159
- `Function.prototype.once()`: Returns `once(this)`
160
- `Function.prototype.onceStrict()`: Returns `once.strict(this)`
161
162
**Usage Examples:**
163
164
```javascript
165
var once = require('once');
166
167
// Enable prototype extension (only needs to be done once)
168
once.proto();
169
170
function load(file, cb) {
171
cb = cb.once(); // Use prototype method instead of once(cb)
172
loader.load('file');
173
loader.once('load', cb);
174
loader.once('error', cb);
175
}
176
177
// Also works with strict mode
178
function criticalCallback() {
179
// Important logic here
180
}
181
182
var safeCriticalCallback = criticalCallback.onceStrict();
183
```
184
185
## State Inspection
186
187
All wrapped functions provide state inspection capabilities:
188
189
```javascript { .api }
190
// Properties available on wrapped functions:
191
interface WrappedFunction extends Function {
192
called: boolean; // Whether function has been executed
193
value: any; // Cached return value (once variant only)
194
onceError?: string; // Custom error message (strict variant only)
195
}
196
```
197
198
**Usage Examples:**
199
200
```javascript
201
var once = require('once');
202
203
function getData() {
204
return { data: 'important' };
205
}
206
207
var cachedGetData = once(getData);
208
209
// Check if function has been called
210
if (!cachedGetData.called) {
211
console.log('Function not yet called');
212
}
213
214
var result = cachedGetData();
215
console.log(cachedGetData.called); // true
216
console.log(cachedGetData.value); // { data: 'important' }
217
218
// Use in conditional logic
219
function processData(callback) {
220
callback = once(callback);
221
222
// Do async work...
223
224
// Only call callback if not already called
225
if (!callback.called) {
226
callback(processedData);
227
}
228
}
229
```
230
231
## Error Handling
232
233
### Standard Once Behavior
234
- No errors thrown on multiple calls
235
- Silently returns cached value
236
- Suitable for callbacks and event handlers
237
238
### Strict Mode Behavior
239
- Throws `Error` on second and subsequent calls
240
- Default error message: `"{functionName} shouldn't be called more than once"`
241
- For anonymous functions: `"Function wrapped with \`once\` shouldn't be called more than once"`
242
- Custom error messages supported via `onceError` property
243
244
```javascript
245
// Error handling example
246
try {
247
var strictFn = once.strict(myFunction);
248
strictFn(); // First call - OK
249
strictFn(); // Second call - throws Error
250
} catch (err) {
251
console.error('Function called multiple times:', err.message);
252
}
253
```
254
255
## Types
256
257
```javascript { .api }
258
/**
259
* Main once function type
260
*/
261
declare function once<T extends Function>(fn: T): T & {
262
called: boolean;
263
value: any;
264
};
265
266
/**
267
* Strict variant type
268
*/
269
declare function strict<T extends Function>(fn: T): T & {
270
called: boolean;
271
value: any;
272
onceError: string;
273
};
274
275
/**
276
* Prototype extension function type
277
*/
278
declare function proto(): void;
279
280
/**
281
* Extended Function prototype (after calling once.proto())
282
*/
283
interface Function {
284
once<T extends Function>(this: T): T & { called: boolean; value: any; };
285
onceStrict<T extends Function>(this: T): T & { called: boolean; value: any; onceError: string; };
286
}
287
```