0
# raf-schd
1

2
raf-schd is a throttle function that uses requestAnimationFrame to limit the rate at which a function is called. Unlike standard throttle functions that use fixed time intervals, raf-schd uses requestAnimationFrame for rate limiting, automatically adapting to the available browser resources and frame rate.
3

4
## Package Information
5

6
- **Package Name**: raf-schd
7
- **Package Type**: npm
8
- **Language**: JavaScript with Flow type annotations
9
- **Installation**: `npm install raf-schd`
10

11
## Core Imports
12

13
ES6 Module:
14

15
```javascript
16
import rafSchd from 'raf-schd';
17
```
18

19
CommonJS:
20

21
```javascript
22
const rafSchd = require('raf-schd').default;
23
```
24

25
## Basic Usage
26

27
```javascript
28
import rafSchd from 'raf-schd';
29

30
const expensiveFn = (arg) => {
31
  console.log(arg);
32
};
33

34
const schedule = rafSchd(expensiveFn);
35

36
schedule('foo');
37
schedule('bar');
38
schedule('baz');
39

40
// animation frame fires
41
// => 'baz'
42
```
43

44
## Capabilities
45

46
### Function Throttling
47

48
Creates a throttled version of any function that will execute on the next animation frame with the latest arguments provided.
49

50
```javascript { .api }
51
/**
52
 * Creates a throttled function using requestAnimationFrame
53
 * @param fn - Function to throttle (accepts any number of arguments)
54
 * @returns Wrapper function with cancel method
55
 */
56
function rafSchd<T: $ReadOnlyArray<any>>(fn: (...T) => void): WrapperFn<T>;
57

58
type WrapperFn<T> = {
59
  [[call]]: (...T) => void;
60
  cancel: () => void;
61
};
62
```
63

64
The returned wrapper function:
65
- **Throttles execution**: Multiple calls before the next animation frame are batched into a single execution
66
- **Uses latest arguments**: Always executes with the most recent arguments provided
67
- **Provides cancellation**: Includes a `.cancel()` method to prevent pending execution
68

69
**Usage Examples:**
70

71
```javascript
72
import rafSchd from 'raf-schd';
73

74
// Basic throttling
75
const doSomething = (value) => console.log(`Processing: ${value}`);
76
const schedule = rafSchd(doSomething);
77

78
schedule(1);
79
schedule(2);
80
schedule(3);
81
// Animation frame fires
82
// => Processing: 3
83

84
// Multiple arguments
85
const processUser = (name, age, email) => {
86
  console.log(`User: ${name}, Age: ${age}, Email: ${email}`);
87
};
88
const scheduleProcess = rafSchd(processUser);
89

90
scheduleProcess('Alice', 25, 'alice@example.com');
91
scheduleProcess('Bob', 30, 'bob@example.com');
92
// Animation frame fires
93
// => User: Bob, Age: 30, Email: bob@example.com
94

95
// Optimized scroll listener
96
const handleScroll = (scrollY) => {
97
  // Expensive scroll handling logic
98
  console.log(`Scroll position: ${scrollY}`);
99
};
100
const scheduledScroll = rafSchd(handleScroll);
101

102
window.addEventListener('scroll', () => {
103
  scheduledScroll(window.scrollY);
104
});
105
```
106

107
### Cancellation
108

109
Cancel a pending animation frame execution using the `.cancel()` method.
110

111
```javascript { .api }
112
/**
113
 * Cancel pending animation frame execution
114
 * Only cancels if the frame has not yet executed
115
 */
116
cancel(): void;
117
```
118

119
**Usage Example:**
120

121
```javascript
122
const schedule = rafSchd(doSomething);
123

124
schedule('foo');
125
schedule.cancel(); // Cancels the pending execution
126

127
// doSomething will not be executed in the next animation frame
128
```
129

130
## Types
131

132
```javascript { .api }
133
/**
134
 * Wrapper function type with callable interface and cancel method
135
 * T represents the argument types array for the wrapped function
136
 */
137
type WrapperFn<T> = {
138
  [[call]]: (...T) => void;
139
  cancel: () => void;
140
};
141
```
142

143
## Performance Benefits
144

145
- **Frame rate adaptation**: Automatically adjusts to browser capabilities (30fps, 60fps, etc.)
146
- **Resource awareness**: Browser reduces frame rate when resources are limited
147
- **Batch execution**: Multiple rapid calls are batched into single execution
148
- **Latest arguments**: Ensures most recent data is processed, avoiding stale operations
149

150
## Browser Compatibility
151

152
Requires `requestAnimationFrame` and `cancelAnimationFrame` APIs. Supported in all modern browsers.