0
# Mixin Deep
1

2
Mixin Deep provides a lightweight utility for deeply mixing object properties into the first object without cloning. Unlike merge-deep, it modifies the target object in place and has zero dependencies, making it ideal for configuration merging, state updates, and object composition scenarios.
3

4
## Package Information
5

6
- **Package Name**: mixin-deep
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES6+)
9
- **Installation**: `npm install mixin-deep`
10

11
## Core Imports
12

13
```javascript
14
const mixinDeep = require("mixin-deep");
15
```
16

17
For ES modules (requires transpiler/bundler):
18

19
```javascript
20
import mixinDeep from "mixin-deep";
21
```
22

23
## Basic Usage
24

25
```javascript
26
const mixinDeep = require("mixin-deep");
27

28
// Basic object mixing
29
const target = { a: { foo: true } };
30
const source1 = { a: { bar: true } };
31
const source2 = { a: { baz: true } };
32

33
const result = mixinDeep(target, source1, source2);
34
console.log(result);
35
// => { a: { foo: true, bar: true, baz: true } }
36

37
// Configuration merging example
38
const defaultConfig = {
39
  server: { port: 3000, host: "localhost" },
40
  features: { auth: false }
41
};
42

43
const userConfig = {
44
  server: { port: 8080 },
45
  features: { auth: true, logging: true }
46
};
47

48
const finalConfig = mixinDeep({}, defaultConfig, userConfig);
49
console.log(finalConfig);
50
// => {
51
//   server: { port: 8080, host: "localhost" },
52
//   features: { auth: true, logging: true }
53
// }
54
```
55

56
## Capabilities
57

58
### Deep Object Mixing
59

60
Deeply mixes properties from multiple source objects into a target object, preserving nested structure and modifying the target in place.
61

62
```javascript { .api }
63
/**
64
 * Deeply mix the properties of objects into the first object
65
 * @param {Object|Function} target - The target object to mix properties into (objects and functions only)
66
 * @param {...(Object|Function|null|undefined)} sources - One or more source objects to mix from
67
 * @returns {Object|Function} The modified target object
68
 */
69
function mixinDeep(target, ...sources);
70
```
71

72
**Key Features:**
73

74
- **In-place modification**: The target object is modified directly, no cloning occurs
75
- **Deep merging**: Nested objects are recursively merged
76
- **Multiple sources**: Accepts any number of source objects as arguments
77
- **Property precedence**: Later sources override earlier ones for primitive values
78
- **Nested preservation**: Existing nested objects are preserved and extended
79
- **Security protection**: Built-in prototype pollution protection
80

81
**Behavior Details:**
82

83
- **Object handling**: Only plain objects and functions are deeply mixed
84
- **Array handling**: Arrays are treated as primitive values and completely replaced
85
- **Special objects**: RegExp, Date, and custom constructor objects are treated as primitives
86
- **Null/undefined sources**: Ignored gracefully without errors
87
- **Security filtering**: Dangerous keys (`__proto__`, `constructor`, `prototype`) are filtered out
88

89
**Usage Examples:**
90

91
```javascript
92
const mixinDeep = require("mixin-deep");
93

94
// Deep nested object mixing
95
const obj1 = { 
96
  config: { 
97
    database: { host: "localhost", port: 5432 },
98
    cache: { enabled: false }
99
  }
100
};
101

102
const obj2 = { 
103
  config: { 
104
    database: { port: 3306, ssl: true },
105
    cache: { enabled: true, ttl: 300 }
106
  }
107
};
108

109
const result = mixinDeep(obj1, obj2);
110
// obj1 is now:
111
// {
112
//   config: {
113
//     database: { host: "localhost", port: 3306, ssl: true },
114
//     cache: { enabled: true, ttl: 300 }
115
//   }
116
// }
117

118
// Using empty object to avoid modifying originals
119
const combined = mixinDeep({}, obj1, obj2);
120

121
// Handling arrays (replaced, not merged)
122
const withArrays = mixinDeep(
123
  { items: [1, 2, 3] },
124
  { items: [4, 5, 6] }
125
);
126
// Result: { items: [4, 5, 6] }
127

128
// Sparse object handling
129
const sparse = mixinDeep({}, undefined, { a: 1 }, null, { b: 2 });
130
// Result: { a: 1, b: 2 }
131
```
132

133
## Security Features
134

135
Mixin Deep includes built-in protection against prototype pollution attacks by filtering out dangerous property keys:
136

137
- `__proto__`
138
- `constructor` 
139
- `prototype`
140

141
This makes it safe to use with untrusted data sources while maintaining the convenience of deep object mixing.
142

143
## Common Use Cases
144

145
- **Configuration merging**: Combining default settings with user preferences
146
- **State management**: Updating nested application state objects
147
- **API response processing**: Merging data from multiple API endpoints
148
- **Template systems**: Combining template data with runtime values
149
- **Plugin systems**: Merging plugin configurations with base settings