0
# SetPrototypeOf
1

2
SetPrototypeOf is a lightweight polyfill library that provides a cross-platform implementation of Object.setPrototypeOf functionality. It automatically detects the best available method for setting object prototypes, ensuring compatibility across different JavaScript environments from modern browsers to legacy systems like IE8.
3

4
## Package Information
5

6
- **Package Name**: setprototypeof
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install setprototypeof`
10
- **TypeScript Support**: Included via index.d.ts
11

12
## Core Imports
13

14
```javascript
15
const setPrototypeOf = require('setprototypeof');
16
```
17

18
For TypeScript and modern environments:
19

20
```typescript
21
import setPrototypeOf from 'setprototypeof';
22
```
23

24
## Basic Usage
25

26
```javascript
27
const setPrototypeOf = require('setprototypeof');
28

29
// Create a base object with methods
30
const animal = {
31
  speak: function() {
32
    return 'Some sound';
33
  }
34
};
35

36
// Create an instance object
37
const dog = {
38
  name: 'Buddy'
39
};
40

41
// Set the prototype to establish inheritance
42
setPrototypeOf(dog, animal);
43

44
// Now dog can access methods from animal
45
console.log(dog.speak()); // "Some sound"
46
console.log(dog.name);    // "Buddy"
47
```
48

49
## Architecture
50

51
SetPrototypeOf implements an intelligent fallback strategy to ensure cross-platform compatibility:
52

53
1. **Native Method**: Uses `Object.setPrototypeOf` when available (modern browsers and Node.js)
54
2. **Proto Property**: Falls back to `__proto__` property assignment for environments that support it
55
3. **Property Mixing**: Final fallback that copies properties from prototype to object for legacy environments (IE8+)
56

57
The library automatically detects which method to use at runtime, providing seamless operation across all JavaScript environments.
58

59
## Capabilities
60

61
### Set Prototype
62

63
Sets the prototype of an object using the best available method for the current environment.
64

65
```javascript { .api }
66
/**
67
 * Sets the prototype of an object using cross-platform compatible method
68
 * @param o - The object whose prototype will be set
69
 * @param proto - The new prototype object or null
70
 * @returns The modified object (same reference as input o)
71
 */
72
function setPrototypeOf(o: any, proto: object | null): any;
73
```
74

75
**Parameters:**
76
- `o` (any): The target object whose prototype will be modified
77
- `proto` (object | null): The prototype object to set, or null to remove prototype
78

79
**Returns:**
80
- `any`: The same object reference that was passed in (modified in place)
81

82
**Implementation Details:**
83
- Uses native `Object.setPrototypeOf` when available
84
- Falls back to `__proto__` property assignment in compatible environments  
85
- Uses property copying for legacy browser support (IE8+)
86
- Automatically detects the best method at runtime
87

88
**Usage Examples:**
89

90
```javascript
91
const setPrototypeOf = require('setprototypeof');
92

93
// Basic prototype setting
94
const parent = { x: 10 };
95
const child = { y: 20 };
96
setPrototypeOf(child, parent);
97
console.log(child.x); // 10 (inherited from parent)
98

99
// Setting null prototype
100
const isolated = { data: 'value' };
101
setPrototypeOf(isolated, null);
102
console.log(Object.getPrototypeOf(isolated)); // null
103

104
// Chaining (returns the same object)
105
const result = setPrototypeOf({ a: 1 }, { b: 2 });
106
console.log(result.a); // 1
107
console.log(result.b); // 2
108
```
109

110
## Environment Compatibility
111

112
- **Modern Browsers**: Chrome 34+, Firefox 31+, Safari 9+, Edge (all versions)
113
- **Node.js**: All versions
114
- **Legacy Browsers**: Internet Explorer 8+, older mobile browsers
115
- **Fallback Behavior**: Gracefully degrades functionality while maintaining API compatibility
116

117
## Error Handling
118

119
The function follows the same error handling patterns as the native `Object.setPrototypeOf`:
120

121
- Throws `TypeError` if the object is not extensible (in strict environments)
122
- Throws `TypeError` if prototype would create a circular reference
123
- In legacy fallback mode, some errors may not be thrown but prototype setting will fail silently
124

125
## TypeScript Integration
126

127
Full TypeScript support is provided via included type definitions:
128

129
```typescript
130
import setPrototypeOf from 'setprototypeof';
131

132
interface Animal {
133
  speak(): string;
134
}
135

136
interface Dog extends Animal {
137
  name: string;
138
}
139

140
const animal: Animal = {
141
  speak: () => 'woof'
142
};
143

144
const dog = { name: 'Buddy' };
145
setPrototypeOf(dog, animal);
146

147
// TypeScript will properly infer the extended interface
148
const typedDog = dog as Dog;
149
console.log(typedDog.speak()); // "woof"
150
```