www.aleph1.co.uk Git - yaffs-website/blob - node_modules/es5-shim/README.md

   1 #es5-shim <sup>[![Version Badge][npm-version-svg]][npm-url]</sup>
   2
   3 [![npm badge][npm-badge-png]][npm-url]
   4
   5 [![Build Status][travis-svg]][travis-url]
   6 [![dependency status][deps-svg]][deps-url]
   7 [![dev dependency status][dev-deps-svg]][dev-deps-url]
   8
   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.
  14
  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.
  22
  23
  24 ## Tests
  25
  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`.
  29
  30 ## Shims
  31
  32 ### Complete tests ###
  33
  34 * Array.prototype.every
  35 * Array.prototype.filter
  36 * Array.prototype.forEach
  37 * Array.prototype.indexOf
  38 * Array.prototype.lastIndexOf
  39 * Array.prototype.map
  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
  47 * Array.isArray
  48 * Date.now
  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
  58 * Object.keys
  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
  66 * parseInt
  67 * parseFloat
  68 * Error.prototype.toString
  69 * Error.prototype.name
  70 * Error.prototype.message
  71 * RegExp.prototype.toString
  72
  73 ## Shams
  74
  75 * :warning: Object.create
  76
  77     For the case of simply "begetting" an object that inherits
  78     prototypically from another, this should work fine across legacy
  79     engines.
  80
  81     :warning: The second argument is passed to Object.defineProperties
  82     which will probably fail either silently or with extreme prejudice.
  83
  84 * :warning: Object.getPrototypeOf
  85
  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
  90     work:
  91
  92         function Foo() {
  93         }
  94         Foo.prototype = {};
  95
  96     Because the prototype reassignment destroys the constructor
  97     property.
  98
  99     This will work for all objects that were created using
 100     `Object.create` implemented with this library.
 101
 102 * :warning: Object.getOwnPropertyNames
 103
 104     This method uses Object.keys, so it will not be accurate on legacy
 105     engines.
 106
 107 * Object.isSealed
 108
 109     Returns "false" in all legacy engines for all objects, which is
 110     conveniently guaranteed to be accurate.
 111
 112 * Object.isFrozen
 113
 114     Returns "false" in all legacy engines for all objects, which is
 115     conveniently guaranteed to be accurate.
 116
 117 * Object.isExtensible
 118
 119     Works like a charm, by trying very hard to extend the object then
 120     redacting the extension.
 121
 122 ### May fail
 123
 124 * :warning: Object.getOwnPropertyDescriptor
 125
 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.
 129
 130 * :warning: Object.defineProperty
 131
 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.
 136
 137     In slightly better circumstances, this method will silently fail to
 138     set "writable", "enumerable", and "configurable" properties.
 139
 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.
 143
 144     https://github.com/es-shims/es5-shim/issues#issue/5
 145
 146 * :warning: Object.defineProperties
 147
 148     This uses the Object.defineProperty shim.
 149
 150 * Object.seal
 151
 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.
 156
 157 * Object.freeze
 158
 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.
 163
 164 * Object.preventExtensions
 165
 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.
 170
 171 ### Example of applying ES compatability shims in a browser project
 172
 173 ```html
 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>
 181 ```
 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