0
# Solid Primitives Scheduled
1
2
Solid Primitives Scheduled provides comprehensive SolidJS primitives for creating scheduled callbacks including debounce, throttle, leading edge schedulers, and idle-time scheduling capabilities. All functions integrate seamlessly with SolidJS's reactive system and lifecycle management, automatically clearing timeouts on root disposal.
3
4
## Package Information
5
6
- **Package Name**: @solid-primitives/scheduled
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @solid-primitives/scheduled`
10
11
## Core Imports
12
13
```typescript
14
import {
15
debounce,
16
throttle,
17
scheduleIdle,
18
leading,
19
leadingAndTrailing,
20
createScheduled,
21
type ScheduleCallback,
22
type Scheduled
23
} from "@solid-primitives/scheduled";
24
```
25
26
For individual imports:
27
28
```typescript
29
import { debounce } from "@solid-primitives/scheduled";
30
import { throttle } from "@solid-primitives/scheduled";
31
import { type Scheduled } from "@solid-primitives/scheduled";
32
```
33
34
## Basic Usage
35
36
```typescript
37
import { debounce, throttle, createScheduled } from "@solid-primitives/scheduled";
38
import { createEffect, createSignal } from "solid-js";
39
40
// Basic debouncing
41
const debouncedFn = debounce((message: string) => console.log(message), 250);
42
debouncedFn("Hello!");
43
debouncedFn.clear(); // Cancel pending execution
44
45
// Basic throttling
46
const throttledFn = throttle((value: number) => console.log(value), 100);
47
throttledFn(42);
48
throttledFn.clear(); // Cancel pending execution
49
50
// Reactive scheduling with createScheduled
51
const scheduled = createScheduled(fn => debounce(fn, 1000));
52
const [count, setCount] = createSignal(0);
53
54
createEffect(() => {
55
const value = count();
56
if (scheduled()) {
57
console.log("Debounced count:", value);
58
}
59
});
60
```
61
62
## Architecture
63
64
The package is built around several key concepts:
65
66
- **Scheduled Callbacks**: Core timing functions that wrap user callbacks with scheduling logic
67
- **SolidJS Integration**: Automatic cleanup via `onCleanup()` when reactive roots are disposed
68
- **Server-Side Compatibility**: Safe no-op implementations when running in server environments
69
- **Cross-Browser Support**: Graceful fallbacks for APIs not available in all browsers
70
- **Type Safety**: Full TypeScript generic support preserving callback argument types
71
- **Cancellation**: All scheduled functions provide `.clear()` methods for manual cancellation
72
73
## Capabilities
74
75
### Debounce
76
77
Creates a debounced callback that executes on the trailing edge after the specified delay.
78
79
```typescript { .api }
80
/**
81
* Creates a callback that is debounced and cancellable. The debounced callback is called on trailing edge.
82
* The timeout will be automatically cleared on root dispose.
83
*/
84
function debounce<Args extends unknown[]>(
85
callback: (...args: Args) => void,
86
wait?: number
87
): Scheduled<Args>;
88
```
89
90
**Usage Examples:**
91
92
```typescript
93
import { debounce } from "@solid-primitives/scheduled";
94
95
// Basic debouncing
96
const handleSearch = debounce((query: string) => {
97
console.log("Searching for:", query);
98
}, 300);
99
100
handleSearch("react");
101
handleSearch("solid"); // Only this will execute after 300ms
102
103
// Manual cancellation
104
handleSearch("typescript");
105
handleSearch.clear(); // Cancels the pending search
106
```
107
108
### Throttle
109
110
Creates a throttled callback that executes on the trailing edge at most once per interval.
111
112
```typescript { .api }
113
/**
114
* Creates a callback that is throttled and cancellable. The throttled callback is called on trailing edge.
115
* The timeout will be automatically cleared on root dispose.
116
*/
117
function throttle<Args extends unknown[]>(
118
callback: (...args: Args) => void,
119
wait?: number
120
): Scheduled<Args>;
121
```
122
123
**Usage Examples:**
124
125
```typescript
126
import { throttle } from "@solid-primitives/scheduled";
127
128
// Throttle scroll events
129
const handleScroll = throttle((event: Event) => {
130
console.log("Scroll position:", window.scrollY);
131
}, 100);
132
133
window.addEventListener("scroll", handleScroll);
134
135
// Manual cancellation
136
handleScroll.clear();
137
```
138
139
### Schedule Idle
140
141
Creates a callback throttled using `requestIdleCallback()` for browser idle-time execution. Falls back to `throttle` when `requestIdleCallback` is unavailable (Safari).
142
143
```typescript { .api }
144
/**
145
* Creates a callback throttled using `window.requestIdleCallback()`.
146
* The throttled callback is called on trailing edge.
147
* The timeout will be automatically cleared on root dispose.
148
*/
149
function scheduleIdle<Args extends unknown[]>(
150
callback: (...args: Args) => void,
151
maxWait?: number
152
): Scheduled<Args>;
153
```
154
155
**Usage Examples:**
156
157
```typescript
158
import { scheduleIdle } from "@solid-primitives/scheduled";
159
160
// Schedule non-critical work during idle time
161
const processAnalytics = scheduleIdle((data: AnalyticsData) => {
162
console.log("Processing analytics:", data);
163
}, 250); // Maximum 250ms wait
164
165
processAnalytics(userData);
166
processAnalytics.clear(); // Cancel pending work
167
```
168
169
### Leading Edge Execution
170
171
Creates a scheduled callback that executes on the leading edge (immediately on first call).
172
173
```typescript { .api }
174
/**
175
* Creates a scheduled and cancellable callback that will be called on leading edge.
176
* The timeout will be automatically cleared on root dispose.
177
*/
178
function leading<Args extends unknown[]>(
179
schedule: ScheduleCallback,
180
callback: (...args: Args) => void,
181
wait?: number
182
): Scheduled<Args>;
183
```
184
185
**Usage Examples:**
186
187
```typescript
188
import { leading, debounce, throttle } from "@solid-primitives/scheduled";
189
190
// Leading debounce - executes immediately, then waits
191
const leadingDebounce = leading(debounce, (message: string) => {
192
console.log("Immediate:", message);
193
}, 1000);
194
195
leadingDebounce("First"); // Executes immediately
196
leadingDebounce("Second"); // Ignored during wait period
197
198
// Leading throttle - executes immediately, then at intervals
199
const leadingThrottle = leading(throttle, (count: number) => {
200
console.log("Count:", count);
201
}, 500);
202
```
203
204
### Leading and Trailing Edge Execution
205
206
Creates a scheduled callback that executes on the leading edge for the first call and trailing edge for subsequent calls.
207
208
```typescript { .api }
209
/**
210
* Creates a scheduled and cancellable callback that will be called on the leading edge
211
* for the first call, and trailing edge thereafter.
212
* The timeout will be automatically cleared on root dispose.
213
*/
214
function leadingAndTrailing<Args extends unknown[]>(
215
schedule: ScheduleCallback,
216
callback: (...args: Args) => void,
217
wait?: number
218
): Scheduled<Args>;
219
```
220
221
**Usage Examples:**
222
223
```typescript
224
import { leadingAndTrailing, debounce } from "@solid-primitives/scheduled";
225
226
// Executes immediately on first call, then debounced
227
const smartSave = leadingAndTrailing(debounce, (data: FormData) => {
228
console.log("Saving:", data);
229
}, 2000);
230
231
smartSave(formData1); // Executes immediately (leading)
232
smartSave(formData2); // Waits for trailing edge
233
smartSave(formData3); // Waits for trailing edge (only final call executes)
234
```
235
236
### Reactive Scheduling
237
238
Creates a signal for scheduling execution of solid computations by tracking.
239
240
```typescript { .api }
241
/**
242
* Creates a signal used for scheduling execution of solid computations by tracking.
243
*/
244
function createScheduled(
245
schedule: (callback: VoidFunction) => VoidFunction
246
): Accessor<boolean>;
247
```
248
249
**Usage Examples:**
250
251
```typescript
252
import { createScheduled, debounce } from "@solid-primitives/scheduled";
253
import { createEffect, createSignal, createMemo } from "solid-js";
254
255
// With createEffect
256
const debouncedSignal = createScheduled(fn => debounce(fn, 500));
257
const [value, setValue] = createSignal(0);
258
259
createEffect(() => {
260
const currentValue = value();
261
if (debouncedSignal()) {
262
console.log("Debounced value:", currentValue);
263
}
264
});
265
266
// With createMemo for transformed values
267
const debouncedValue = createMemo((prev: number = 0) => {
268
const currentValue = value();
269
return debouncedSignal() ? currentValue : prev;
270
});
271
272
// With different schedulers
273
const throttledSignal = createScheduled(fn => throttle(fn, 100));
274
const leadingSignal = createScheduled(fn => leading(debounce, fn, 1000));
275
```
276
277
## Types
278
279
```typescript { .api }
280
/**
281
* Generic type for schedule callback functions
282
*/
283
type ScheduleCallback = <Args extends unknown[]>(
284
callback: (...args: Args) => void,
285
wait?: number
286
) => Scheduled<Args>;
287
288
/**
289
* Interface for scheduled callback functions with clear method
290
*/
291
interface Scheduled<Args extends unknown[]> {
292
/** The scheduled callback function */
293
(...args: Args): void;
294
/** Method to cancel pending timeout */
295
clear: VoidFunction;
296
}
297
```
298
299
## Server-Side Rendering
300
301
All functions provide safe server-side rendering support:
302
303
- Return no-op functions when `isServer` is true
304
- Maintain the same API surface for consistency
305
- Prevent server-side execution of browser-only APIs
306
307
## Browser Compatibility
308
309
- **`requestIdleCallback`**: `scheduleIdle` gracefully falls back to `throttle` in browsers without support (Safari)
310
- **`setTimeout`/`clearTimeout`**: Full support across all modern browsers
311
- **SolidJS Integration**: Requires SolidJS 1.6.12 or higher