how does this compare to es5-shim?

[paulirish]

AKA do we need both projects?

just curious as I don't know which project to recommend.

Thank you :)

link: https://github.com/kriskowal/es5-shim/

[Raynos]

Augment.js

• implements only the fully shimmable subset of ES5
• has a single file for every shim method

ES5-shim.js

• implements the fully shimmable subset and the partially shimmable subset
• far more compliant to the ES5 spec
• has far more eyes on it. More likely to be battle proven.

I'm personally biased to ES5-shim because I use and commit to it.

Off hand I can see that augment fails the nonEnumerable bug in Object.keys and the fails the [[Construct]] on bind returning the the instance if the return value is not an object.

I would recommend ES5-shim.

[olivernn]

@paulirish I think the major difference is that Augment only provides shims for methods that can be fully (or as close to fully) shimmed in JavaScript. I see no benefit in adding shims that actually don't and can never behave like the native methods they are shimming.

I think Object.create & Object.defineProperties are good examples of this. Since the full functionality of these is not possible to shim with JavaScript, Augment does not add them. They are, however, present in ES5-Shim.

Code that relies on these methods cannot work properly in older browsers, and shimming them makes it harder for application code to detect their absence and work around accordingly. ES5-Shim itself notes that there are several shims that 'fail silently', if that is so I find there inclusion in the library odd.

@Raynos please create an issue for the specific bug(s) that you found. If there are specific places where Augment's implementations differ from the spec please also raise an issue as these are bugs and should and will be fixed!

[Raynos]

@olivernn Meh, read and understand the ES5-shim code, run the ES5-shim unit tests on augment.js. I'll add the two bugs I saw as issues though.

Also note there is value in adding things that fail silently. Even though full functionality is not possible, those methods have a subset which is fully possible to shim, that subset is useful and as long as you stick to that subset no harm occurs.

Of course this requires developers to know and understand the shimmable subset and to not go outside of it.

[Krinkle]

Note that es5-shim does distinguish between methods that can be fully shimmed and methods that can only be done partially shimmed or where the static restriction can't be emulated (called shims and shams respectively).

It distributes a es5-shim.js separate from the es5-sham.js for this purpose. Object.create and Object.defineProperties, for example, are not part of es5-shim.js for this reason.

Having said that, the subset es5-shim considers suitable for shimming does seem larger than Augment's.

At time of writing, comparing latest master of each:

• augment.js (17 methods):
  • Array.isArray
  • Array.prototype.every
  • Array.prototype.filter
  • Array.prototype.forEach
  • Array.prototype.indexOf
  • Array.prototype.lastIndexOf
  • Array.prototype.map
  • Array.prototype.reduce
  • Array.prototype.reduceRight
  • Array.prototype.some
  • Date.now
  • Date.prototype.toISOString
  • Date.prototype.toJSON
  • Function.prototype.bind
  • Object.getPrototypeOf
  • Object.keys
  • String.prototype.trim
• es5-shim.js (20 methods):
  • Array.isArray
  • Array.prototype.every
  • Array.prototype.filter
  • Array.prototype.forEach
  • Array.prototype.indexOf
  • Array.prototype.lastIndexOf
  • Array.prototype.map
  • Array.prototype.reduce
  • Array.prototype.reduceRight
  • Array.prototype.some
  • Date.now
  • Date.parse (for ISO parsing)
  • Date.prototype.toISOString
  • Date.prototype.toJSON
  • Function.prototype.bind (with warnings)
  • Number.prototype.toFixed
  • Object.keys
  • parseInt
  • String.prototype.split
  • String.prototype.trim

[olivernn]

Thanks for adding more data points to this issue, hopefully the information provided can help people who are trying to choose which library to use.

I think the list of extra shims in es5-shim gets to the main difference between these libraries. I hope its fair to say that es5-shim aims for close adherence to every detail in the specs, going so far as to fix bad implementations in browsers that do ship methods that differ from the spec. This was never the goal when I was creating augment, I just wanted to be able to use the array niceness from es5 in projects that had to support old versions of IE. Where possible augment follows the specs as closely as is reasonable but 100% compliance was never the goal.

It's interesting to me that es5-shim doesn't provide Object.getPrototypeOf since @Raynos opened #6 proposing its inclusion in augment, and he is a committer to es5-shim, was it moved into es5-sham?

Another datapoint is that it's possible to generate a custom build of augment with only the shims that you need, on the flip side each shim is self-contained meaning that there is some duplication between the shims that increases the overall file size of the library.

Just to add some more data to the discussion, I put together a simple (possibly naive?) benchmark on performance differences between augment and es5shim. I'm not convinced the differences matter for the vast majority of people, but thought it was worth including here. Please update that benchmark if its in anyway misleading or not testing things correctly, its certainly not my intention to skew the results in either libraries favour.

Undoubtedly es5-shim has more followers/stars on github, I'd say its a decent metric to gauge the number of users of the respective libraries, because of this issues are more likely to be found in es5-shim than in augment. That said I consider the implementations in augment reasonably solid.