es-shimses-shim API 
API Contract
For any given “es-shim API v3”-compliant package foo, the following invariants must hold:
- This package will run in an environment supporting the oldest JS version in which the spec’s semantics are achievable - ES3, ES5, and/or ES6. The package should indicate its minimum level of required environment support in its README.
- The package must attempt to support
node/io.js, all versions of all ES3-compliant browsers or later, Web Workers, andnode-webkit. Other environments are a plus, but not expected. require('foo')is a spec-compliant JS or native function. However, if the function’s behavior depends on a receiver (a “this” value), then the first argument to this function will be used as that receiver. The package should indicate if this is the case in its README.- In the case of static methods like
Promise.allthat depend on their receiver without a fallback, the index must ensure that receiverless invocation acts as if the static method was called on its original object, but must also allow.call/.bind/.applyto alter the receiver when relevant.
- In the case of static methods like
require('foo/implementation')is a spec-compliant JS function, that will depend on a receiver (a “this” value) as the spec requires.require('foo/polyfill')is a function that when invoked, will return the most compliant and performant function that it can - if a native version is available, and does not violate the spec, then the native function will be returned - otherwise, either theimplementation, or a custom, wrapped version of the native function, will be returned. This is also the result that will be used as the default export.require('foo/shim')is a function that when invoked, will callgetPolyfill, and if the polyfill doesn’t match the built-in value, will install it into the global environment.require('foo/auto')will automatically invoke theshimmethod.- The only place the package may modify the environment is within its
shimmethod. - Naturally,
npm testmust run the package’s tests. - In every way possible, the package must attempt to make itself robust against the environment being modified after it is
required.- For example,
require('foo'); delete Function.prototype.call;must not alter the behavior offoo. - The most useful technique for this is shown in this example:
var callBound = require('call-bound'); var slice = callBound('Array.prototype.slice'); slice([1], 1);— this technique works in ES3 environments, and will ensure that modifyingArray.prototypeorFunction.prototypewill not interfere with the package.
- For example,
Multi-shim Packages
If your package contains multiple shims, you can pass --multi to apply these invariants:
- The package's main export must be an array of directory names, with no additional properties.
- The entry points and respective invariants listed above apply to the subdirectories listed in the main export
- The root must contain
shimandautoentrypoints that match the same invariants described above. Theshimentry point must invoke theshimentry point in each of the subdirectories listed in the main export - The root must NOT contain an
implementationentry point.
Recommended dependencies
- Please use the es-abstract package to ensure spec-compliant behavior via the spec’s internal abstract operations.
- Please use the define-properties package to trivially define non-enumerable properties, where supported.
- Please use the call-bind package to cache references to all builtin methods, to be robust against later modification of the environment.
How to denote compliance
Prominently in the package’s README, please include the following markdown:
This package implements the [es-shim API](https://github.com/es-shims/api) interface. It works in an ES3-supported environment and complies with the [spec](https://www.ecma-international.org/ecma-262/6.0/).
Please modify “ES3” as needed to the level of support, and please update the spec link so it points directly to the most relevant section of the spec it complies with.
Binary
Very simple and shallow tests that a package follows the es-shim API.
Pass --bound to indicate that the function the package is implementing depends on having a receiver (a “this” value). In particular, this applies to something that is a prototype method, or a static method that depends on its receiver.
Example
es-shim-api object-assign
es-shim-api array-includes --bound
Tests
Simply clone the repo, npm install, and run npm test