0
# @next/polyfill-module
1

2
A standard library polyfill for ES Modules supporting browsers (Edge 16+, Firefox 60+, Chrome 61+, Safari 10.1+) that provides implementations of modern JavaScript methods missing in older browser versions.
3

4
## Package Information
5

6
- **Package Name**: @next/polyfill-module
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install @next/polyfill-module` (typically bundled, not installed directly)
10
- **Distribution**: IIFE (Immediately Invoked Function Expression) bundle
11

12
## Core Imports
13

14
This package is designed to be loaded as an IIFE bundle that automatically applies polyfills to global prototypes. It does not provide traditional import/export functionality.
15

16
```html
17
<script src="node_modules/@next/polyfill-module/dist/polyfill-module.js"></script>
18
```
19

20
Or in a build system that processes the main entry point:
21

22
```javascript
23
// This will execute the polyfills automatically
24
require('@next/polyfill-module');
25
```
26

27
## Basic Usage
28

29
The polyfills are applied automatically when the script is loaded. After loading, you can use the polyfilled methods directly on native prototypes:
30

31
```javascript
32
// After loading the polyfill module, these methods are available
33
const text = "  hello world  ";
34
console.log(text.trimStart()); // "hello world  "
35
console.log(text.trimEnd());   // "  hello world"
36

37
const sym = Symbol('description');
38
console.log(sym.description); // "description" 
39

40
const nested = [1, [2, [3, 4]]];
41
console.log(nested.flat(2)); // [1, 2, 3, 4]
42

43
const promise = Promise.resolve(42);
44
promise.finally(() => console.log('cleanup'));
45

46
const entries = [['a', 1], ['b', 2]];
47
const obj = Object.fromEntries(entries); // { a: 1, b: 2 }
48

49
const arr = [1, 2, 3];
50
console.log(arr.at(-1)); // 3
51

52
console.log(Object.hasOwn(obj, 'a')); // true
53

54
console.log(URL.canParse('https://example.com')); // true
55
```
56

57
## Architecture
58

59
This package implements feature detection for each polyfill, only extending native prototypes when the methods are not already available. Each polyfill includes detailed browser compatibility information and implements standard behavior as defined by ECMAScript specifications.
60

61
The polyfills are designed to:
62
- Only apply when native implementations are missing
63
- Follow ECMAScript specification behavior exactly
64
- Provide compatibility for browsers that support ES modules but lack specific methods
65
- Extend native prototypes and objects directly
66

67
## Capabilities
68

69
### String Prototype Extensions
70

71
Polyfills for string trimming methods that remove whitespace from the beginning or end of strings.
72

73
```javascript { .api }
74
/**
75
 * Removes whitespace from the beginning of a string
76
 * Available in: Edge (never), Firefox 61+, Chrome 66+, Safari 12+
77
 */
78
String.prototype.trimStart(): string;
79

80
/**
81
 * Removes whitespace from the end of a string  
82
 * Available in: Edge (never), Firefox 61+, Chrome 66+, Safari 12+
83
 */
84
String.prototype.trimEnd(): string;
85
```
86

87
### Symbol Prototype Extensions
88

89
Polyfill for accessing symbol descriptions.
90

91
```javascript { .api }
92
/**
93
 * Gets the description of a Symbol
94
 * Available in: Edge (never), Firefox 63+, Chrome 70+, Safari 12.1+
95
 */
96
Symbol.prototype.description: string | undefined;
97
```
98

99
### Array Prototype Extensions
100

101
Polyfills for array flattening and element access methods.
102

103
```javascript { .api }
104
/**
105
 * Flattens nested arrays to specified depth
106
 * Available in: Edge (never), Firefox 62+, Chrome 69+, Safari 12+
107
 * @param depth - Maximum depth to flatten (default: 1)
108
 */
109
Array.prototype.flat(depth?: number): any[];
110

111
/**
112
 * Maps each element using a function and flattens the result
113
 * Available in: Edge (never), Firefox 62+, Chrome 69+, Safari 12+
114
 * @param callback - Function to execute on each element
115
 * @param thisArg - Value to use as 'this' when executing callback
116
 */
117
Array.prototype.flatMap<U>(
118
  callback: (value: any, index: number, array: any[]) => U | U[],
119
  thisArg?: any
120
): U[];
121

122
/**
123
 * Accesses array element by index with support for negative indexing
124
 * Available in: Edge 92+, Firefox 90+, Chrome 92+, Safari 15.4+
125
 * @param index - Index to access (negative indices count from end)
126
 */
127
Array.prototype.at(index: number): any;
128
```
129

130
### Promise Prototype Extensions
131

132
Polyfill for promise cleanup functionality.
133

134
```javascript { .api }
135
/**
136
 * Returns a promise that executes callback when settled (resolved or rejected)
137
 * Available in: Edge 18+, Firefox 58+, Chrome 63+, Safari 11.1+
138
 * @param callback - Function to execute when promise settles
139
 */
140
Promise.prototype.finally(callback: () => void): Promise<any>;
141
```
142

143
### Object Static Method Extensions
144

145
Polyfills for object utility methods.
146

147
```javascript { .api }
148
/**
149
 * Creates an object from key-value pairs
150
 * Available in: Edge (never), Firefox 63+, Chrome 73+, Safari 12.1+
151
 * @param iterable - Iterable of key-value pairs
152
 * @throws TypeError if iterable entries don't have numeric indices
153
 */
154
Object.fromEntries(iterable: Iterable<readonly [PropertyKey, any]>): any;
155

156
/**
157
 * Checks if object has specified property as own property
158
 * Available in: Edge 93+, Firefox 92+, Chrome 93+, Safari 15.4+
159
 * @param object - Object to check
160
 * @param property - Property name to check for
161
 * @throws TypeError if object is null or undefined
162
 */
163
Object.hasOwn(object: any, property: PropertyKey): boolean;
164
```
165

166
### URL Static Method Extensions
167

168
Polyfill for URL validation utility.
169

170
```javascript { .api }
171
/**
172
 * Checks if a URL string can be parsed
173
 * Available in: Edge 120+, Firefox 115+, Chrome 120+, Safari 17.0+
174
 * @param url - URL string to validate
175
 * @param base - Optional base URL for relative URL resolution
176
 */
177
URL.canParse(url: string, base?: string): boolean;
178
```
179

180
## Browser Compatibility
181

182
This package specifically targets browsers that support ES modules but are missing certain standard methods:
183

184
- **Edge 16+**: Missing trimStart/End, description, flat/flatMap, fromEntries, at, hasOwn, canParse
185
- **Firefox 60+**: Missing some methods in earlier versions within the range
186
- **Chrome 61+**: Missing some methods in earlier versions within the range  
187
- **Safari 10.1+**: Missing some methods in earlier versions within the range
188

189
Each polyfill includes detailed compatibility information and only applies when the native implementation is not available.
190

191
## Error Handling
192

193
The polyfills implement standard ECMAScript error behavior:
194

195
- `Object.hasOwn()` throws `TypeError` if the first argument is null or undefined
196
- `URL.canParse()` returns `false` for invalid URLs instead of throwing
197
- Other methods follow their respective specification error handling
198

199
## Implementation Notes
200

201
- All polyfills check for existing native implementations before applying
202
- Implementations follow ECMAScript specifications exactly
203
- Source code includes detailed browser compatibility comments
204
- Built as IIFE bundle for immediate execution in browser environments
205
- No external dependencies or imports required