0
# next-tick
1

2
next-tick is an environment-agnostic nextTick polyfill that enables developers to schedule callback functions to execute asynchronously in the next iteration of the event loop. It intelligently detects and uses the most appropriate asynchronous execution mechanism available in the current environment for maximum compatibility and performance across Node.js, browsers, and other JavaScript environments.
3

4
## Package Information
5

6
- **Package Name**: next-tick
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install next-tick`
10

11
## Core Imports
12

13
```javascript
14
const nextTick = require("next-tick");
15
// nextTick is either a function or null depending on environment support
16
```
17

18
For environments that support ES modules:
19

20
```javascript
21
import nextTick from "next-tick";
22
// nextTick is either a function or null depending on environment support
23
```
24

25
## Basic Usage
26

27
```javascript
28
const nextTick = require("next-tick");
29

30
// Check if nextTick is supported before using
31
if (nextTick !== null) {
32
  // Schedule callback for next tick
33
  nextTick(() => {
34
    console.log("This runs in the next tick");
35
  });
36
} else {
37
  console.log("nextTick not supported in this environment");
38
}
39

40
console.log("This runs immediately");
41

42
// Output (in supported environments):
43
// This runs immediately
44
// This runs in the next tick
45
```
46

47
## Architecture
48

49
next-tick uses intelligent environment detection to select the optimal asynchronous execution mechanism:
50

51
1. **Node.js**: Uses native `process.nextTick` for maximum performance
52
2. **Modern Engines**: Uses `queueMicrotask` for microtask queue scheduling
53
3. **Browser Fallback**: Uses `MutationObserver` for efficient DOM-based scheduling
54
4. **Legacy Browsers**: Uses `WebKitMutationObserver` for older WebKit browsers
55
5. **Alternative Environments**: Uses `setImmediate` when available
56
6. **Universal Fallback**: Uses `setTimeout(callback, 0)` as last resort
57
7. **Unsupported**: Returns `null` if no mechanisms are available
58

59
## Capabilities
60

61
### Asynchronous Callback Scheduling
62

63
Schedules a callback function to execute in the next iteration of the event loop using the most appropriate mechanism for the current environment. In unsupported environments, the module exports `null` instead of a function.
64

65
```javascript { .api }
66
/**
67
 * Environment agnostic nextTick polyfill - can be null in unsupported environments
68
 * @type {Function|null}
69
 */
70
const nextTick = require("next-tick");
71

72
/**
73
 * Schedules callback for next tick execution (when nextTick is not null)
74
 * @param {Function} callback - The function to execute in the next tick
75
 * @returns {undefined} Returns undefined
76
 * @throws {TypeError} Throws TypeError if callback is not a function
77
 */
78
nextTick(callback);
79
```
80

81
**Parameters:**
82
- `callback` (Function): The function to be executed asynchronously in the next tick. Must be a callable function.
83

84
**Return Value:**
85
- Returns `undefined`
86

87
**Error Handling:**
88
- Throws `TypeError` if the provided callback is not a function
89
- Error message format varies by environment:
90
  - Node.js: Uses `process.nextTick` error format
91
  - Other environments: `"[value] is not a function"`
92

93
**Behavior:**
94
- **Environment Detection**: The module exports `null` in unsupported environments instead of a function
95
- **Validation**: When not null, validates that the callback is a function before scheduling
96
- **Execution Order**: Executes callbacks in FIFO (first-in, first-out) order when multiple callbacks are scheduled
97
- **Asynchronous**: Does not execute the callback immediately (asynchronous execution)
98
- **Performance**: Uses the most performant available mechanism for the current environment
99

100
**Usage Examples:**
101

102
```javascript
103
const nextTick = require("next-tick");
104

105
// Basic usage
106
nextTick(() => {
107
  console.log("Executed in next tick");
108
});
109

110
// Multiple callbacks execute in order
111
nextTick(() => console.log("First"));
112
nextTick(() => console.log("Second"));
113
nextTick(() => console.log("Third"));
114
// Output: First, Second, Third
115

116
// Error handling
117
try {
118
  nextTick("not a function");
119
} catch (error) {
120
  console.log(error.message); // "not a function is not a function"
121
}
122

123
// Environment compatibility
124
if (nextTick === null) {
125
  console.log("No nextTick mechanism available in this environment");
126
} else {
127
  nextTick(() => console.log("Supported environment"));
128
}
129
```
130

131
## Environment Compatibility
132

133
- **Node.js**: Full support using `process.nextTick`
134
- **Modern Browsers**: Full support using `queueMicrotask`
135
- **Legacy Browsers**: Full support using `MutationObserver`/`WebKitMutationObserver`
136
- **Alternative JavaScript Engines**: Support using `setImmediate` or `setTimeout`
137
- **Unsupported Environments**: Returns `null` instead of a function