domenic / especially

Abstract operations and other functions drawn from the ECMAScript specification

ECMAScript Spec Operations, in ECMAScript

Have you ever wanted to write a to-the-letter implementation of some ECMAScript spec function? Maybe you want to run tests against it; maybe you're just crazy and like self-hosting JavaScript in JavaScript. In either case, this is the package for you!

Especially has a small-but-growing collection of meta-textual and abstract operations drawn directly from the pages of the ECMAScript 2015 draft specification. From common things like Get to dealing with internal slots, Especially has you covered.

APIs

Especially has no main module (gasp). Instead, you'll require one of the top-level modules that contain the stuff you want.

require("especially/abstract-operations")

• ArrayCreate
• Call
• CreateDataProperty
• DateFromTime
• Day
• DayFromYear
• DaysInYear
• DayWithinYear
• EnqueueJob
• Get
• GetV
• GetIterator: uses the @@iterator symbol.
• GetMethod
• GetPrototypeFromConstructor
• HasProperty
• InLeapYear
• Invoke
• IsCallable
• IsConstructor: not spec compliant, but the best we can do
• IsPropertyKey
• IteratorComplete
• IteratorNext
• IteratorStep
• IteratorValue
• MakeDate
• MakeDay
• MakeTime
• MonthFromTime
• ObjectCreate
• OrdinaryCreateFromConstructor
• SameValue
• SameValueZero
• SpeciesConstructor
• TimeClip
• TimeFromYear
• TimeWithinDay
• ToBoolean
• ToInteger
• ToLength
• ToNumber
• ToObject
• ToString
• Type: returns the types as strings, e.g. "Object".
• YearFromTime

require("especially/math")

A variety of math operations from the Algorithm Conventions section of the spec:

• abs(x)
• sign(x)
• min(x₁, x₂, …, x_n)
• floor(x)

require("especially/meta")

• assert: ensures you pass it a boolean, then throws if it's not true
• define_built_in_data_property: a shortcut for defining a built-in data property with the usual property descriptor.
• Internal slot management:
  • make_slots(object, arrayOfSlotNames): call this to initialize an object's internal slots. Often referenced in the spec as "instances of (something) are initially created with the internal slots listed in (some table)."
  • get_slot(object, name): get the value of an internal slot. Often referenced in the spec as "the value of (object)'s [[SlotName]] internal slot."
  • set_slot(object, name): set the value of an internal slot. Often referenced in the spec as "Set (object)'s [[SlotName]] internal slot to (a value)."
  • has_slot(object): check whether an object has an internal slot with the given name. Often referenced in the spec as "If (object) does not have a [[SlotName]] internal slot."

require("especially/well-known-symbols")

One well-known symbol is included:

• "@@iterator" will give you a symbol that is used by GetIterator. (It is the same as V8's default Symbol.iterator.)
• "@@species" will give the symbol that is used by SpeciesConstructor. (It is a freshly-minted symbol, since V8 doesn't have Symbol.species yet.)

require("especially/intrinsics")

Some of the well-known intrinsic objects are included by name, e.g. "%ObjectPrototype%". These are used by GetPrototypeFromConstructor and related operations.

Usage Notes

Especially is meant to run in io.js (not Node.js™). It uses certain ES2015 features only implemented in modern V8.

Install it from npm into your project with npm install especially.

You can see examples of it in use in the reference implementation of the ES2015 promises specification.

especially's Issues

Add ArraySpeciesCreate abstract operation?

Would it be desirable to add the ArraySpeciesCreate abstract operation?

I had started working on a PR to add this function, but then got stuck in the realms part. Looks like it is not possible to get the running execution context’s Realm nor a given object's [[Realm]] internal slot, correct?

Is there an approximation we can make for this operation?

Proposal: Combine efforts with ES-Abstract

Side-note: I came across this project via Nicolás Bevacqua's weekly newsletter

This project's goal looks to be the same as @ljharb's es-abstract. I think there may be potential to join your efforts into one project.

Readme: outdated "Usage" section

The Usage section currently reads:

Especially is meant to run in io.js (not Node.js™). It uses certain ES2015 features only implemented in modern V8.

I believe it may make more sense to recommend using an up-to-date Node.js version (e.g. >= 4) rather than io.js.

Create especially-lite

I'd like to create another version of especially that is usable by polyfills, not just reference implementations. It should not depend on Node 0.11 --harmony mode, but instead be usable by all ES5 browsers. (And, a subset of it might be usable by ES3 browsers.)

Its readme would document where it departs from especially. For example, it will likely be missing most constructor-related abstract operations, or perhaps would only polyfill the top-level one in an inaccurate fashion (by using new). And it would either be missing the internal slot stuff, or just add them as underscored-properties.

Then, especially-lite could be used by Traceur and es6-shim. /cc @arv @ljharb

Don't depend on the global bindings being correct

I often do things throughout especially like

exports.ToNumber = function (x) {
    return Number(x);
};

or

exports.abs = function (x) {
    return Math.abs(x);
};

This is not robust in the face of people overwriting globals, and thus will not behave in the same way as ES's abstract operations actually do.

Usage of let keywords prevents this package from being used in FF

This, in turn, prevents me from using https://www.npmjs.com/package/array.prototype.includes.