1 | # es5-shim <sup>[![Version Badge][npm-version-svg]][package-url]</sup>
|
2 |
|
3 | [![github actions][actions-image]][actions-url]
|
4 | [![coverage][codecov-image]][codecov-url]
|
5 | [![dependency status][deps-svg]][deps-url]
|
6 | [![dev dependency status][dev-deps-svg]][dev-deps-url]
|
7 | [![License][license-image]][license-url]
|
8 | [![Downloads][downloads-image]][downloads-url]
|
9 |
|
10 | [![npm badge][npm-badge-png]][package-url]
|
11 |
|
12 | `es5-shim.js` and `es5-shim.min.js` monkey-patch a JavaScript context to
|
13 | contain all EcmaScript 5 methods that can be faithfully emulated with a
|
14 | legacy JavaScript engine.
|
15 | **Note:** As `es5-shim.js` is designed to patch the native Javascript
|
16 | engine, it should be the library that is loaded first.
|
17 |
|
18 | `es5-sham.js` and `es5-sham.min.js` monkey-patch other ES5 methods as
|
19 | closely as possible. For these methods, as closely as possible to ES5
|
20 | is not very close. Many of these shams are intended only to allow code
|
21 | to be written to ES5 without causing run-time errors in older engines.
|
22 | In many cases, this means that these shams cause many ES5 methods to
|
23 | silently fail. Decide carefully whether this is what you want.
|
24 | **Note:** `es5-sham.js` requires `es5-shim.js` to be able to work properly.
|
25 |
|
26 | ## Tests
|
27 |
|
28 | The tests are written with the Jasmine BDD test framework.
|
29 | To run the tests, navigate to <root-folder>/tests/ , or,
|
30 | simply `npm install` and `npm test`.
|
31 |
|
32 | ## Shims
|
33 |
|
34 | ### Complete tests ###
|
35 |
|
36 | * Array.prototype.every ([standalone shim](https://www.npmjs.com/package/array.prototype.every))
|
37 | * Array.prototype.filter
|
38 | * Array.prototype.forEach ([standalone shim](https://www.npmjs.com/package/array.prototype.foreach))
|
39 | * Array.prototype.indexOf ([standalone shim](https://www.npmjs.com/package/array.prototype.indexof))
|
40 | * Array.prototype.lastIndexOf ([standalone shim](https://www.npmjs.com/package/array.prototype.lastindexof))
|
41 | * Array.prototype.map ([standalone shim](https://www.npmjs.com/package/array.prototype.map))
|
42 | * Array.prototype.slice
|
43 | * Array.prototype.some ([standalone shim](https://www.npmjs.com/package/array.prototype.some))
|
44 | * Array.prototype.sort
|
45 | * Array.prototype.reduce ([standalone shim](https://www.npmjs.com/package/array.prototype.reduce))
|
46 | * Array.prototype.reduceRight ([standalone shim](https://www.npmjs.com/package/array.prototype.reduceright))
|
47 | * Array.prototype.push
|
48 | * Array.prototype.join
|
49 | * Array.isArray
|
50 | * Date.now
|
51 | * Date.prototype.toJSON
|
52 | * Function.prototype.bind
|
53 | * :warning: Caveat: the bound function has a prototype property.
|
54 | * :warning: Caveat: bound functions do not try too hard to keep you
|
55 | from manipulating their ``arguments`` and ``caller`` properties.
|
56 | * :warning: Caveat: bound functions don't have checks in ``call`` and
|
57 | ``apply`` to avoid executing as a constructor.
|
58 | * Number.prototype.toExponential ([standalone shim](https://www.npmjs.com/package/number.prototype.toexponential))
|
59 | * Number.prototype.toFixed
|
60 | * Number.prototype.toPrecision
|
61 | * Object.keys ([standalone shim](https://www.npmjs.com/package/object-keys))
|
62 | * String.prototype.split ([standalone shim](https://www.npmjs.com/package/string.prototype.split))
|
63 | * String.prototype.trim ([standalone shim](https://www.npmjs.com/package/string.prototype.trim))
|
64 | * String.prototype.lastIndexOf ([standalone shim](https://string.prototype.lastindexof))
|
65 | * String.prototype.replace
|
66 | * Firefox (through v29) natively handles capturing groups incorrectly.
|
67 | * Date.parse (for ISO parsing)
|
68 | * Date.prototype.toISOString
|
69 | * parseInt
|
70 | * parseFloat
|
71 | * Error.prototype.toString
|
72 | * Error.prototype.name
|
73 | * Error.prototype.message
|
74 | * RegExp.prototype.toString
|
75 |
|
76 | ## Shams
|
77 |
|
78 | * :warning: Object.create
|
79 |
|
80 | For the case of simply "begetting" an object that inherits
|
81 | prototypically from another, this should work fine across legacy
|
82 | engines.
|
83 |
|
84 | :warning: The second argument is passed to Object.defineProperties
|
85 | which will probably fail either silently or with extreme prejudice.
|
86 |
|
87 | * :warning: Object.getPrototypeOf
|
88 |
|
89 | This will return "undefined" in some cases. It uses `__proto__` if
|
90 | it's available. Failing that, it uses constructor.prototype, which
|
91 | depends on the constructor property of the object's prototype having
|
92 | not been replaced. If your object was created like this, it won't
|
93 | work:
|
94 |
|
95 | function Foo() {
|
96 | }
|
97 | Foo.prototype = {};
|
98 |
|
99 | Because the prototype reassignment destroys the constructor
|
100 | property.
|
101 |
|
102 | This will work for all objects that were created using
|
103 | `Object.create` implemented with this library.
|
104 |
|
105 | * :warning: Object.getOwnPropertyNames
|
106 |
|
107 | This method uses Object.keys, so it will not be accurate on legacy
|
108 | engines.
|
109 |
|
110 | * Object.isSealed
|
111 |
|
112 | Returns "false" in all legacy engines for all objects, which is
|
113 | conveniently guaranteed to be accurate.
|
114 |
|
115 | * Object.isFrozen
|
116 |
|
117 | Returns "false" in all legacy engines for all objects, which is
|
118 | conveniently guaranteed to be accurate.
|
119 |
|
120 | * Object.isExtensible
|
121 |
|
122 | Works like a charm, by trying very hard to extend the object then
|
123 | redacting the extension.
|
124 |
|
125 | ### May fail
|
126 |
|
127 | * :warning: Object.getOwnPropertyDescriptor
|
128 |
|
129 | The behavior of this shim does not conform to ES5. It should
|
130 | probably not be used at this time, until its behavior has been
|
131 | reviewed and been confirmed to be useful in legacy engines.
|
132 |
|
133 | * :warning: Object.defineProperty
|
134 |
|
135 | In the worst of circumstances, IE 8 provides a version of this
|
136 | method that only works on DOM objects. This sham will not be
|
137 | installed. The given version of `defineProperty` will throw an
|
138 | exception if used on non-DOM objects.
|
139 |
|
140 | In slightly better circumstances, this method will silently fail to
|
141 | set "writable", "enumerable", and "configurable" properties.
|
142 |
|
143 | Providing a getter or setter with "get" or "set" on a descriptor
|
144 | will silently fail on engines that lack "__defineGetter__" and
|
145 | "__defineSetter__", which include all versions of IE.
|
146 |
|
147 | https://github.com/es-shims/es5-shim/issues#issue/5
|
148 |
|
149 | * :warning: Object.defineProperties
|
150 |
|
151 | This uses the Object.defineProperty shim.
|
152 |
|
153 | * Object.seal
|
154 |
|
155 | Silently fails on all legacy engines. This should be
|
156 | fine unless you are depending on the safety and security
|
157 | provisions of this method, which you cannot possibly
|
158 | obtain in legacy engines.
|
159 |
|
160 | * Object.freeze
|
161 |
|
162 | Silently fails on all legacy engines. This should be
|
163 | fine unless you are depending on the safety and security
|
164 | provisions of this method, which you cannot possibly
|
165 | obtain in legacy engines.
|
166 |
|
167 | * Object.preventExtensions
|
168 |
|
169 | Silently fails on all legacy engines. This should be
|
170 | fine unless you are depending on the safety and security
|
171 | provisions of this method, which you cannot possibly
|
172 | obtain in legacy engines.
|
173 |
|
174 | ### Example of applying ES compatibility shims in a browser project
|
175 |
|
176 | ```html
|
177 | <script src="https://cdnjs.cloudflare.com/ajax/libs/es5-shim/4.5.14/es5-shim.min.js"></script>
|
178 | <script src="https://cdnjs.cloudflare.com/ajax/libs/es5-shim/4.5.14/es5-sham.min.js"></script>
|
179 | <script src="https://cdnjs.cloudflare.com/ajax/libs/json3/3.3.2/json3.min.js"></script>
|
180 | <script src="https://cdnjs.cloudflare.com/ajax/libs/es6-shim/0.35.5/es6-shim.min.js"></script>
|
181 | <script src="https://cdnjs.cloudflare.com/ajax/libs/es6-shim/0.35.5/es6-sham.min.js"></script>
|
182 | <script src="other-libs.js"></script>
|
183 | ```
|
184 |
|
185 | [package-url]: https://npmjs.org/package/es5-shim
|
186 | [npm-version-svg]: https://versionbadg.es/es-shims/es5-shim.svg
|
187 | [deps-svg]: https://david-dm.org/es-shims/es5-shim.svg
|
188 | [deps-url]: https://david-dm.org/es-shims/es5-shim
|
189 | [dev-deps-svg]: https://david-dm.org/es-shims/es5-shim/dev-status.svg
|
190 | [dev-deps-url]: https://david-dm.org/es-shims/es5-shim#info=devDependencies
|
191 | [npm-badge-png]: https://nodei.co/npm/es5-shim.png?downloads=true&stars=true
|
192 | [license-image]: https://img.shields.io/npm/l/es5-shim.svg
|
193 | [license-url]: LICENSE
|
194 | [downloads-image]: https://img.shields.io/npm/dm/es5-shim.svg
|
195 | [downloads-url]: https://npm-stat.com/charts.html?package=es5-shim
|
196 | [codecov-image]: https://codecov.io/gh/es-shims/es5-shim/branch/main/graphs/badge.svg
|
197 | [codecov-url]: https://app.codecov.io/gh/es-shims/es5-shim/
|
198 | [actions-image]: https://img.shields.io/endpoint?url=https://github-actions-badge-u3jn4tfpocch.runkit.sh/es-shims/es5-shim
|
199 | [actions-url]: https://github.com/es-shims/es5-shim/actions
|