0
# Priority Management
1

2
Functions for executing code with specific priority contexts and managing priority levels in the scheduler.
3

4
## Capabilities
5

6
### Run With Priority
7

8
Executes a function with a specific priority level, temporarily changing the current priority context.
9

10
```javascript { .api }
11
/**
12
 * Execute a function with a specific priority level
13
 * @param priorityLevel - Priority level to use during execution
14
 * @param eventHandler - Function to execute with the given priority
15
 * @returns The return value of the eventHandler function
16
 */
17
function unstable_runWithPriority<T>(
18
  priorityLevel: PriorityLevel,
19
  eventHandler: () => T
20
): T;
21
```
22

23
**Usage Examples:**
24

25
```javascript
26
import { 
27
  unstable_runWithPriority,
28
  unstable_UserBlockingPriority,
29
  unstable_LowPriority,
30
  unstable_getCurrentPriorityLevel
31
} from "scheduler";
32

33
// Execute function with high priority
34
const result = unstable_runWithPriority(unstable_UserBlockingPriority, () => {
35
  console.log("Current priority:", unstable_getCurrentPriorityLevel()); // 2
36
  return "high priority result";
37
});
38

39
// Execute background work with low priority
40
unstable_runWithPriority(unstable_LowPriority, () => {
41
  // Process non-urgent data
42
  processAnalytics();
43
  updateCache();
44
});
45

46
// Nested priority contexts
47
unstable_runWithPriority(unstable_UserBlockingPriority, () => {
48
  console.log("Outer priority:", unstable_getCurrentPriorityLevel()); // 2
49
  
50
  unstable_runWithPriority(unstable_LowPriority, () => {
51
    console.log("Inner priority:", unstable_getCurrentPriorityLevel()); // 4
52
  });
53
  
54
  console.log("Restored priority:", unstable_getCurrentPriorityLevel()); // 2
55
});
56
```
57

58
### Next
59

60
Executes a function with lowered priority, shifting high-priority contexts down to Normal priority.
61

62
```javascript { .api }
63
/**
64
 * Execute a function with lowered priority
65
 * Immediate, UserBlocking, and Normal priorities shift down to Normal
66
 * Low and Idle priorities remain unchanged
67
 * @param eventHandler - Function to execute with lowered priority
68
 * @returns The return value of the eventHandler function
69
 */
70
function unstable_next<T>(eventHandler: () => T): T;
71
```
72

73
**Usage Examples:**
74

75
```javascript
76
import { 
77
  unstable_next,
78
  unstable_runWithPriority,
79
  unstable_UserBlockingPriority,
80
  unstable_getCurrentPriorityLevel
81
} from "scheduler";
82

83
// Lowering priority from UserBlocking to Normal
84
unstable_runWithPriority(unstable_UserBlockingPriority, () => {
85
  console.log("Current priority:", unstable_getCurrentPriorityLevel()); // 2 (UserBlocking)
86
  
87
  unstable_next(() => {
88
    console.log("Lowered priority:", unstable_getCurrentPriorityLevel()); // 3 (Normal)
89
    // Perform less urgent work
90
    updateSecondaryUI();
91
  });
92
  
93
  console.log("Restored priority:", unstable_getCurrentPriorityLevel()); // 2 (UserBlocking)
94
});
95

96
// Useful for deferring work within high-priority contexts
97
function handleUserClick() {
98
  unstable_runWithPriority(unstable_UserBlockingPriority, () => {
99
    // Critical UI updates
100
    updateButtonState();
101
    
102
    // Defer non-critical work
103
    unstable_next(() => {
104
      // This runs at Normal priority
105
      logAnalytics();
106
      updateRecommendations();
107
    });
108
  });
109
}
110
```
111

112
### Wrap Callback
113

114
Wraps a callback function to preserve the current priority context when the callback is executed later.
115

116
```javascript { .api }
117
/**
118
 * Wrap a callback to preserve current priority context
119
 * @param callback - Function to wrap with current priority context
120
 * @returns Wrapped function that will execute with preserved priority
121
 */
122
function unstable_wrapCallback<T>(callback: T): T;
123
```
124

125
**Usage Examples:**
126

127
```javascript
128
import { 
129
  unstable_wrapCallback,
130
  unstable_runWithPriority,
131
  unstable_UserBlockingPriority,
132
  unstable_getCurrentPriorityLevel
133
} from "scheduler";
134

135
// Preserve priority across async boundaries
136
function setupEventListener() {
137
  unstable_runWithPriority(unstable_UserBlockingPriority, () => {
138
    const wrappedHandler = unstable_wrapCallback(() => {
139
      console.log("Handler priority:", unstable_getCurrentPriorityLevel()); // 2 (UserBlocking)
140
      handleImportantEvent();
141
    });
142
    
143
    // Event will execute with UserBlocking priority even though
144
    // the current context when it fires might be different
145
    element.addEventListener("click", wrappedHandler);
146
  });
147
}
148

149
// Preserve priority in setTimeout
150
unstable_runWithPriority(unstable_UserBlockingPriority, () => {
151
  const wrappedCallback = unstable_wrapCallback(() => {
152
    console.log("setTimeout priority:", unstable_getCurrentPriorityLevel()); // 2 (UserBlocking)
153
    handleDelayedWork();
154
  });
155
  
156
  setTimeout(wrappedCallback, 1000);
157
});
158

159
// Preserve priority in Promise callbacks
160
function fetchUserData() {
161
  return unstable_runWithPriority(unstable_UserBlockingPriority, () => {
162
    return fetch("/api/user")
163
      .then(unstable_wrapCallback((response) => {
164
        console.log("Promise priority:", unstable_getCurrentPriorityLevel()); // 2 (UserBlocking)
165
        return response.json();
166
      }))
167
      .then(unstable_wrapCallback((userData) => {
168
        console.log("Second promise priority:", unstable_getCurrentPriorityLevel()); // 2 (UserBlocking)
169
        updateUI(userData);
170
      }));
171
  });
172
}
173
```
174

175
## Priority Context Behavior
176

177
The scheduler maintains a priority context that affects how tasks are scheduled and executed:
178

179
1. **Default Context**: Normal Priority (3) is the default context
180
2. **Context Inheritance**: Functions inherit the priority of their calling context
181
3. **Context Restoration**: Priority contexts are automatically restored after function execution
182
4. **Context Preservation**: `unstable_wrapCallback` preserves context across async boundaries
183

184
## Common Patterns
185

186
### Batching Updates by Priority
187

188
```javascript
189
// High-priority immediate updates
190
function handleUserInteraction() {
191
  unstable_runWithPriority(unstable_UserBlockingPriority, () => {
192
    updateButtonState();
193
    updateFormValidation();
194
  });
195
}
196

197
// Low-priority background updates
198
function performBackgroundWork() {
199
  unstable_runWithPriority(unstable_LowPriority, () => {
200
    updateAnalytics();
201
    preloadNextPage();
202
    optimizeCache();
203
  });
204
}
205
```
206

207
### Deferring Work Within Priority Contexts
208

209
```javascript
210
function processUserInput(input) {
211
  unstable_runWithPriority(unstable_UserBlockingPriority, () => {
212
    // Critical: Update UI immediately
213
    updateInputField(input);
214
    validateInput(input);
215
    
216
    // Non-critical: Defer to normal priority
217
    unstable_next(() => {
218
      updateSuggestions(input);
219
      logUserBehavior(input);
220
    });
221
  });
222
}
223
```