1 #es5-shim <sup>[![Version Badge][npm-version-svg]][npm-url]</sup>
3 [![npm badge][npm-badge-png]][npm-url]
5 [![Build Status][travis-svg]][travis-url]
6 [![dependency status][deps-svg]][deps-url]
7 [![dev dependency status][dev-deps-svg]][dev-deps-url]
9 `es5-shim.js` and `es5-shim.min.js` monkey-patch a JavaScript context to
10 contain all EcmaScript 5 methods that can be faithfully emulated with a
11 legacy JavaScript engine.
12 **Note:** As `es5-shim.js` is designed to patch the native Javascript
13 engine, it should be the library that is loaded first.
15 `es5-sham.js` and `es5-sham.min.js` monkey-patch other ES5 methods as
16 closely as possible. For these methods, as closely as possible to ES5
17 is not very close. Many of these shams are intended only to allow code
18 to be written to ES5 without causing run-time errors in older engines.
19 In many cases, this means that these shams cause many ES5 methods to
20 silently fail. Decide carefully whether this is what you want.
21 **Note:** `es5-sham.js` requires `es5-shim.js` to be able to work properly.
26 The tests are written with the Jasmine BDD test framework.
27 To run the tests, navigate to <root-folder>/tests/ , or,
28 simply `npm install` and `npm test`.
32 ### Complete tests ###
34 * Array.prototype.every
35 * Array.prototype.filter
36 * Array.prototype.forEach
37 * Array.prototype.indexOf
38 * Array.prototype.lastIndexOf
40 * Array.prototype.slice
41 * Array.prototype.some
42 * Array.prototype.sort
43 * Array.prototype.reduce
44 * Array.prototype.reduceRight
45 * Array.prototype.push
46 * Array.prototype.join
49 * Date.prototype.toJSON
50 * Function.prototype.bind
51 * :warning: Caveat: the bound function has a prototype property.
52 * :warning: Caveat: bound functions do not try too hard to keep you
53 from manipulating their ``arguments`` and ``caller`` properties.
54 * :warning: Caveat: bound functions don't have checks in ``call`` and
55 ``apply`` to avoid executing as a constructor.
56 * Number.prototype.toFixed
57 * Number.prototype.toPrecision
59 * String.prototype.split
60 * String.prototype.trim
61 * String.prototype.lastIndexOf
62 * String.prototype.replace
63 * Firefox (through v29) natively handles capturing groups incorrectly.
64 * Date.parse (for ISO parsing)
65 * Date.prototype.toISOString
68 * Error.prototype.toString
69 * Error.prototype.name
70 * Error.prototype.message
71 * RegExp.prototype.toString
75 * :warning: Object.create
77 For the case of simply "begetting" an object that inherits
78 prototypically from another, this should work fine across legacy
81 :warning: The second argument is passed to Object.defineProperties
82 which will probably fail either silently or with extreme prejudice.
84 * :warning: Object.getPrototypeOf
86 This will return "undefined" in some cases. It uses `__proto__` if
87 it's available. Failing that, it uses constructor.prototype, which
88 depends on the constructor property of the object's prototype having
89 not been replaced. If your object was created like this, it won't
96 Because the prototype reassignment destroys the constructor
99 This will work for all objects that were created using
100 `Object.create` implemented with this library.
102 * :warning: Object.getOwnPropertyNames
104 This method uses Object.keys, so it will not be accurate on legacy
109 Returns "false" in all legacy engines for all objects, which is
110 conveniently guaranteed to be accurate.
114 Returns "false" in all legacy engines for all objects, which is
115 conveniently guaranteed to be accurate.
117 * Object.isExtensible
119 Works like a charm, by trying very hard to extend the object then
120 redacting the extension.
124 * :warning: Object.getOwnPropertyDescriptor
126 The behavior of this shim does not conform to ES5. It should
127 probably not be used at this time, until its behavior has been
128 reviewed and been confirmed to be useful in legacy engines.
130 * :warning: Object.defineProperty
132 In the worst of circumstances, IE 8 provides a version of this
133 method that only works on DOM objects. This sham will not be
134 installed. The given version of `defineProperty` will throw an
135 exception if used on non-DOM objects.
137 In slightly better circumstances, this method will silently fail to
138 set "writable", "enumerable", and "configurable" properties.
140 Providing a getter or setter with "get" or "set" on a descriptor
141 will silently fail on engines that lack "__defineGetter__" and
142 "__defineSetter__", which include all versions of IE.
144 https://github.com/es-shims/es5-shim/issues#issue/5
146 * :warning: Object.defineProperties
148 This uses the Object.defineProperty shim.
152 Silently fails on all legacy engines. This should be
153 fine unless you are depending on the safety and security
154 provisions of this method, which you cannot possibly
155 obtain in legacy engines.
159 Silently fails on all legacy engines. This should be
160 fine unless you are depending on the safety and security
161 provisions of this method, which you cannot possibly
162 obtain in legacy engines.
164 * Object.preventExtensions
166 Silently fails on all legacy engines. This should be
167 fine unless you are depending on the safety and security
168 provisions of this method, which you cannot possibly
169 obtain in legacy engines.
171 ### Example of applying ES compatability shims in a browser project
174 <script src="https://cdnjs.cloudflare.com/ajax/libs/es5-shim/4.5.7/es5-shim.min.js"></script>
175 <script src="https://cdnjs.cloudflare.com/ajax/libs/es5-shim/4.5.7/es5-sham.min.js"></script>
176 <script src="https://cdnjs.cloudflare.com/ajax/libs/json3/3.3.2/json3.min.js"></script>
177 <script src="https://cdnjs.cloudflare.com/ajax/libs/es6-shim/0.34.2/es6-shim.min.js"></script>
178 <script src="https://cdnjs.cloudflare.com/ajax/libs/es6-shim/0.34.2/es6-sham.min.js"></script>
179 <script src="https://wzrd.in/standalone/es7-shim@latest"></script>
180 <script src="other-libs.js"></script>
182 [npm-url]: https://npmjs.org/package/es5-shim
183 [npm-version-svg]: http://versionbadg.es/es-shims/es5-shim.svg
184 [travis-svg]: https://travis-ci.org/es-shims/es5-shim.svg
185 [travis-url]: https://travis-ci.org/es-shims/es5-shim
186 [deps-svg]: https://david-dm.org/es-shims/es5-shim.svg
187 [deps-url]: https://david-dm.org/es-shims/es5-shim
188 [dev-deps-svg]: https://david-dm.org/es-shims/es5-shim/dev-status.svg
189 [dev-deps-url]: https://david-dm.org/es-shims/es5-shim#info=devDependencies
190 [npm-badge-png]: https://nodei.co/npm/es5-shim.png?downloads=true&stars=true