0
# object.assign
1

2
object.assign is an ES6 spec-compliant Object.assign shim that works in ES3-supported environments and properly handles Symbol properties in ES6 environments. It implements the es-shim API interface and provides multiple usage patterns including polyfill mode, shimming mode, and direct implementation access.
3

4
## Package Information
5

6
- **Package Name**: object.assign
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install object.assign`
10

11
## Core Imports
12

13
```javascript
14
var assign = require('object.assign');
15
```
16

17
For direct access to specific components:
18

19
```javascript
20
var assign = require('object.assign');
21
var getPolyfill = require('object.assign/polyfill');
22
var shim = require('object.assign/shim');
23
var implementation = require('object.assign/implementation');
24
```
25

26
Auto-shimming (installs Object.assign globally if needed):
27

28
```javascript
29
require('object.assign/auto');
30
```
31

32
## Basic Usage
33

34
```javascript
35
var assign = require('object.assign');
36

37
// Basic usage
38
var target = { a: true };
39
var source1 = { b: true };
40
var source2 = { c: true };
41

42
var result = assign(target, source1, source2);
43
// target is now { a: true, b: true, c: true }
44
// result === target (returns the target object)
45

46
// Using the polyfill (recommended)
47
var assign = require('object.assign').getPolyfill();
48
var result = assign({ a: 1 }, { b: 2 }, { c: 3 });
49
// result: { a: 1, b: 2, c: 3 }
50
```
51

52
## Capabilities
53

54
### Main Assignment Function
55

56
The primary bound function that implements Object.assign functionality with automatic polyfill selection.
57

58
```javascript { .api }
59
/**
60
 * Copies all enumerable own properties from one or more source objects to a target object
61
 * @param {any} target - The target object to copy properties to
62
 * @param {...any} sources - One or more source objects to copy properties from
63
 * @returns {Object} The target object with copied properties
64
 * @throws {TypeError} If target is null or undefined
65
 */
66
function assign(target, ...sources);
67
```
68

69
**Usage Examples:**
70

71
```javascript
72
var assign = require('object.assign');
73

74
// Multiple sources
75
var target = { a: true };
76
var source1 = { b: true };
77
var source2 = { c: true };
78
assign(target, source1, source2);
79
// target is now { a: true, b: true, c: true }
80

81
// Property overwriting
82
var target = { a: 1, b: 2 };
83
var source = { b: 3, c: 4 };
84
assign(target, source);
85
// target is now { a: 1, b: 3, c: 4 }
86

87
// Non-enumerable properties are ignored
88
var source = {};
89
Object.defineProperty(source, 'hidden', { value: 'secret', enumerable: false });
90
var result = assign({}, source);
91
// result: {} (hidden property not copied)
92
```
93

94
### Polyfill Detection
95

96
Returns the best available Object.assign implementation (native or shim).
97

98
```javascript { .api }
99
/**
100
 * Returns native Object.assign if compliant, otherwise returns the shim implementation
101
 * @returns {Function} The best available assign function
102
 */
103
assign.getPolyfill();
104
```
105

106
**Usage Examples:**
107

108
```javascript
109
var assign = require('object.assign').getPolyfill();
110
// Use the best available implementation
111
var result = assign({ a: 1 }, { b: 2 });
112

113
// Or access directly
114
var getPolyfill = require('object.assign/polyfill');
115
var assign = getPolyfill();
116
```
117

118
### Direct Implementation Access
119

120
Direct access to the ES6-compliant Object.assign implementation.
121

122
```javascript { .api }
123
/**
124
 * Direct access to the ES6-compliant Object.assign implementation
125
 * @param {any} target - The target object
126
 * @param {...any} sources - Source objects
127
 * @returns {Object} The target object with copied properties
128
 * @throws {TypeError} If target is null or undefined
129
 */
130
assign.implementation;
131
```
132

133
**Usage Examples:**
134

135
```javascript
136
var implementation = require('object.assign').implementation;
137
// or
138
var implementation = require('object.assign/implementation');
139

140
var result = implementation({ a: 1 }, { b: 2 });
141
```
142

143
### Shimming Functionality
144

145
Installs the polyfill as Object.assign if not present or if the native version is faulty.
146

147
```javascript { .api }
148
/**
149
 * Conditionally installs Object.assign polyfill
150
 * @returns {Function} The installed polyfill function
151
 */
152
assign.shim();
153
```
154

155
**Usage Examples:**
156

157
```javascript
158
// Install the shim
159
var shimmedAssign = require('object.assign').shim();
160
// Object.assign is now available globally (if it wasn't compliant before)
161

162
// Or use directly
163
var shim = require('object.assign/shim');
164
var assign = shim();
165

166
// Example showing shimming behavior
167
delete Object.assign; // Remove native implementation
168
var shimmedAssign = require('object.assign').shim();
169
console.log(Object.assign === shimmedAssign); // true
170

171
// With compliant native implementation
172
var shimmedAssign = require('object.assign').shim();
173
console.log(Object.assign === shimmedAssign); // true (uses native)
174
```
175

176

177
## Advanced Usage Patterns
178

179
### ES6 Environments with Symbols
180

181
```javascript
182
var assign = require('object.assign').getPolyfill();
183

184
// Symbol properties are properly handled
185
var sym1 = Symbol('prop1');
186
var sym2 = Symbol('prop2');
187

188
var source = {
189
  normalProp: 'value',
190
  [sym1]: 'symbol value 1',
191
  [sym2]: 'symbol value 2'
192
};
193

194
var target = assign({}, source);
195
// target has all properties, including Symbol properties
196
```
197

198
### Polyfill vs Shim vs Implementation
199

200
```javascript
201
// Polyfill: Returns best available (native or shim)
202
var polyfill = require('object.assign').getPolyfill();
203

204
// Shim: Installs globally if needed, returns function
205
var shim = require('object.assign').shim();
206

207
// Implementation: Always uses the shim implementation
208
var implementation = require('object.assign').implementation;
209

210
// Auto: Automatically shims globally on require
211
require('object.assign/auto'); // Object.assign is now available
212
```
213

214
### Browser Compatibility
215

216
The package works in all browser environments. For maximum compatibility, use the polyfill pattern:
217

218
```javascript
219
var assign = require('object.assign').getPolyfill();
220
// This automatically uses native Object.assign if available and compliant
221
```
222

223
## Error Handling
224

225
The assign function throws TypeError in specific cases:
226

227
```javascript
228
var assign = require('object.assign');
229

230
try {
231
  assign(null, { a: 1 }); // Throws TypeError
232
} catch (e) {
233
  console.log(e.message); // "target must be an object"
234
}
235

236
try {
237
  assign(undefined, { a: 1 }); // Throws TypeError  
238
} catch (e) {
239
  console.log(e.message); // "target must be an object"
240
}
241

242
// Non-object targets are coerced to objects (no error)
243
var result = assign(true, { a: 1 });
244
console.log(typeof result); // "object"
245
console.log(Boolean.prototype.valueOf.call(result)); // true
246
console.log(result.a); // 1
247
```
248

249
## Type Definitions
250

251
```javascript { .api }
252
/**
253
 * Main assign function signature
254
 */
255
interface AssignFunction {
256
  (target: any, ...sources: any[]): any;
257
  getPolyfill(): AssignFunction;
258
  implementation: AssignFunction;
259
  shim(): AssignFunction;
260
}
261

262
/**
263
 * Polyfill getter function
264
 */
265
interface GetPolyfillFunction {
266
  (): AssignFunction;
267
}
268

269
/**
270
 * Shim installer function  
271
 */
272
interface ShimFunction {
273
  (): AssignFunction;
274
}
275
276
```