0
# Object and Function Utilities
1

2
General-purpose utilities for object manipulation, function composition, and data processing. These utilities provide common functionality needed across React applications.
3

4
## Capabilities
5

6
### Object Manipulation
7

8
#### deepmerge
9

10
Deep merges objects with special handling for React elements, providing safe object combination.
11

12
```typescript { .api }
13
/**
14
 * Deep merges objects with React element handling
15
 * @param target - Target object to merge into
16
 * @param source - Source object to merge from
17
 * @param options - Merge options
18
 * @returns Merged object
19
 */
20
function deepmerge<T>(
21
  target: T,
22
  source: unknown,
23
  options?: DeepmergeOptions
24
): T;
25

26
interface DeepmergeOptions {
27
  /** Set to false to merge source directly into target without cloning */
28
  clone?: boolean;
29
}
30

31
/**
32
 * Checks if item is a plain object
33
 * @param item - Item to check
34
 * @returns True if item is plain object
35
 */
36
function isPlainObject(item: unknown): item is Record<keyof any, unknown>;
37
```
38

39
**Usage Example:**
40

41
```typescript
42
import { deepmerge, isPlainObject } from '@mui/utils';
43

44
// Basic merge
45
const merged = deepmerge(
46
  { styles: { color: 'blue' }, count: 1 },
47
  { styles: { fontSize: 16 }, enabled: true }
48
);
49
// Result: { styles: { color: 'blue', fontSize: 16 }, count: 1, enabled: true }
50

51
// Merge without cloning (modifies target)
52
const target = { a: 1 };
53
deepmerge(target, { b: 2 }, { clone: false });
54
// target is now { a: 1, b: 2 }
55

56
// Check if object is mergeable
57
if (isPlainObject(someValue)) {
58
  const result = deepmerge(defaults, someValue);
59
}
60
```
61

62
### Numeric Utilities
63

64
#### clamp
65

66
Clamps a number between minimum and maximum values.
67

68
```typescript { .api }
69
/**
70
 * Clamps number between min and max values
71
 * @param value - Number to clamp
72
 * @param min - Minimum value
73
 * @param max - Maximum value
74
 * @returns Clamped number
75
 */
76
function clamp(value: number, min: number, max: number): number;
77
```
78

79
**Usage Example:**
80

81
```typescript
82
import { clamp } from '@mui/utils';
83

84
const bounded = clamp(150, 0, 100); // 100
85
const withinRange = clamp(50, 0, 100); // 50
86
const aboveMin = clamp(-10, 0, 100); // 0
87
```
88

89
### Function Composition
90

91
#### createChainedFunction
92

93
Creates a function that calls multiple functions in sequence, useful for combining event handlers.
94

95
```typescript { .api }
96
/**
97
 * Creates function that calls multiple functions in sequence
98
 * @param funcs - Functions to chain (null/undefined are ignored)
99
 * @returns Combined function
100
 */
101
function unstable_createChainedFunction(
102
  ...funcs: Array<Function | null | undefined>
103
): Function;
104
```
105

106
**Usage Example:**
107

108
```typescript
109
import { unstable_createChainedFunction as createChainedFunction } from '@mui/utils';
110

111
const handleClick1 = (event) => console.log('First handler');
112
const handleClick2 = (event) => console.log('Second handler');
113

114
const combinedHandler = createChainedFunction(handleClick1, handleClick2);
115
// When called, both functions will execute in order
116
```
117

118
#### debounce
119

120
Debounces function calls, limiting execution rate for performance optimization.
121

122
```typescript { .api }
123
/**
124
 * Debounces function calls
125
 * @param func - Function to debounce
126
 * @param wait - Milliseconds to wait before execution
127
 * @param options - Debounce options
128
 * @returns Debounced function with clear and flush methods
129
 */
130
function unstable_debounce<T extends (...args: any[]) => any>(
131
  func: T,
132
  wait?: number,
133
  options?: DebounceOptions
134
): T & { clear: () => void; flush: () => void };
135

136
interface DebounceOptions {
137
  /** Execute on leading edge of timeout */
138
  leading?: boolean;
139
  /** Execute on trailing edge of timeout */
140
  trailing?: boolean;
141
}
142
```
143

144
**Usage Example:**
145

146
```typescript
147
import { unstable_debounce as debounce } from '@mui/utils';
148

149
const searchHandler = debounce((query: string) => {
150
  console.log('Searching for:', query);
151
}, 300);
152

153
// Usage in component
154
function SearchInput() {
155
  const [query, setQuery] = React.useState('');
156
  
157
  React.useEffect(() => {
158
    if (query) {
159
      searchHandler(query);
160
    }
161
  }, [query]);
162

163
  return <input value={query} onChange={(e) => setQuery(e.target.value)} />;
164
}
165
```
166

167
### Event Handler Utilities
168

169
#### extractEventHandlers
170

171
Extracts event handler functions from an object based on naming convention (functions starting with 'on').
172

173
```typescript { .api }
174
/**
175
 * Extracts event handlers from object
176
 * @param object - Object to extract handlers from
177
 * @param excludeKeys - Keys to exclude from extraction
178
 * @returns Object containing only event handlers
179
 */
180
function unstable_extractEventHandlers(
181
  object: Record<string, any>,
182
  excludeKeys?: string[]
183
): Record<string, React.EventHandler<any>>;
184
```
185

186

187
### Prop Resolution
188

189
#### resolveComponentProps
190

191
Resolves component props from functions or objects, handling dynamic prop resolution.
192

193
```typescript { .api }
194
/**
195
 * Resolves component props from functions or objects
196
 * @param componentProps - Props object or function returning props
197
 * @param ownerState - Owner state for function-based props
198
 * @param slotState - Optional slot state
199
 * @returns Resolved props object
200
 */
201
function unstable_resolveComponentProps<TProps>(
202
  componentProps: TProps | ((ownerState: any) => TProps) | undefined,
203
  ownerState: any,
204
  slotState?: any
205
): TProps | {};
206
```
207

208
#### resolveProps
209

210
Resolves props with defaults, merging default props with provided props.
211

212
```typescript { .api }
213
/**
214
 * Resolves props with defaults
215
 * @param defaultProps - Default props object
216
 * @param props - Provided props object
217
 * @returns Merged props with defaults applied
218
 */
219
function internal_resolveProps<TProps>(
220
  defaultProps: Partial<TProps>,
221
  props: TProps
222
): TProps;
223
```
224

225
**Usage Example:**
226

227
```typescript
228
import { 
229
  unstable_resolveComponentProps as resolveComponentProps,
230
  internal_resolveProps as resolveProps 
231
} from '@mui/utils';
232

233
// Function-based props
234
const dynamicProps = (ownerState) => ({
235
  className: `button-${ownerState.variant}`,
236
  'aria-pressed': ownerState.pressed
237
});
238

239
const resolved = resolveComponentProps(dynamicProps, { variant: 'primary', pressed: true });
240
// { className: 'button-primary', 'aria-pressed': true }
241

242
// Default props resolution
243
const defaults = { variant: 'contained', color: 'primary' };
244
const userProps = { color: 'secondary', disabled: true };
245
const finalProps = resolveProps(defaults, userProps);
246
// { variant: 'contained', color: 'secondary', disabled: true }
247
```