diff options
Diffstat (limited to 'tools/addon-sdk-1.4/packages/api-utils/docs/es5.md')
-rw-r--r-- | tools/addon-sdk-1.4/packages/api-utils/docs/es5.md | 52 |
1 files changed, 52 insertions, 0 deletions
diff --git a/tools/addon-sdk-1.4/packages/api-utils/docs/es5.md b/tools/addon-sdk-1.4/packages/api-utils/docs/es5.md new file mode 100644 index 0000000..0906b0d --- /dev/null +++ b/tools/addon-sdk-1.4/packages/api-utils/docs/es5.md @@ -0,0 +1,52 @@ +The `es5` module provides shim layer to a versions of Firefox that do not yet +implement certain EcmaScript 5 features. + +For more information on EcmaScript 5: + +* The new APIs are described in the official [ES5 specification][]. +* A good [introduction][] to the new APIs by John Resig. +* A Google tech talk on [changes to JavaScript][]. + +**There is no need to `require` this module** since it gets preloaded into +all sandboxes automatically. + +Usage of new ES5 API's is encouraged, but since not everything can be +provided to all the versions of firefox, there are few things to be aware of: + +`Object.freeze`, `Object.seal`, `Object.preventExtensions` does not really +prevents any mutations. One thing it guarantees though, `Object.isFrozen`, +`Object.isSealed`, `Object.isExtensible` checks will behave as defined in +specification. + +`Object.defineProperty` is only partially compliant with the specification: + +- Non configurable properties will be created as configurable ones. + +- Instead of non-writable properties getters and setters will be defined, +but `Object.getOwnPropertyDescriptor` will still behave as expected +(will return property descriptor for non-writable property not a getter) + +- Defining properties using ES5 functions will break your + [custom iterators][] if you have any. Think twice before employing + custom iterators, because in most cases you can just make properties + non enumerable. If you really need to have a custom iterator, add it + after running ES5 functions and don't ignore previous iterators. + For example: + + let object = Object.create({}, { + myField: { value: 6 } + }); + object.__iterator__ = (function(original) { + return function myIterator() { + this.__iterator__ = original; + for (let key in this) { + // your logic here + } + this.__iterator__ = myIterator; + } + })(object.__iterator__); + +[custom iterators]:https://developer.mozilla.org/en/New_in_JavaScript_1.7#Iterators +[ES5 specification]:http://www.ecmascript.org/docs/tc39-2009-043.pdf +[introduction]:http://ejohn.org/blog/ecmascript-5-objects-and-properties/ +[changes to JavaScript]:http://www.youtube.com/watch?v=Kq4FpMe6cRs |