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