Skip to content

Latest commit

 

History

History
143 lines (115 loc) · 16.2 KB

Features.md

File metadata and controls

143 lines (115 loc) · 16.2 KB
id language-features
title Language Features

Hermes is a JavaScript engine optimized for fast start-up. It executes JavaScript using a combination of ahead-of-time (AOT) compilation to bytecode and runtime interpretation.

Hermes aims to support the latest ECMAScript specification, prioritizing language features over new library functions. However, some features are intentionally excluded or de-prioritized if they conflict with Hermes' design goals of performance, low memory use, and efficient AOT compilation.

Supported ECMAScript Features

Hermes provides broad support for ECMAScript features, including:

  • Full support for ES2015 (ES6) Language Features:

    • let and const declarations (Temporal Dead Zone checks and per-iteration bindings are supported but off by default, see "Known Deviations")
    • Arrow Functions (=>)
    • Classes (Basic syntax: class, extends, static methods, super, constructor)
    • Enhanced Object Literals (shorthand properties, computed names, methods)
    • Template Literals (tagged and untagged)
    • Destructuring Assignment (arrays and objects, including rest ...)
    • Default, Rest, and Spread (...) operators
    • Iterators and Generators (Symbol.iterator, for..of, function*)
    • Symbols (primitive type, Symbol(), well-known symbols)
    • And all other ES2015 language constructs (unless listed below).
  • Key Post-ES2015 Language Features:

    • async / await (ES2017)
    • Object Rest/Spread Properties (ES2018)
    • RegExp Named Capture Groups (ES2018)
    • Optional Chaining (?.) (ES2020)
    • Nullish Coalescing (??) (ES2020)
    • BigInt (ES2020)
    • Class Fields & Static Blocks (ES2022):
      • Public and Private Instance Fields (property declarations and initializers, e.g., myField = 1;, #privateField = 2;)
      • Public and Private Static Fields (e.g., static staticField = 3;, static #privateStatic = 4;)
      • Static Initialization Blocks (static {})
      • Private Methods, Private Static Methods and Private Accessors
      • Private Brand Checks (#x in obj)
    • RegExp Match Indices (/d flag) (ES2022)
    • Logical Assignment Operators (??=, ||=, &&=) (ES2021)
    • for await...of and Symbol.asyncIterator (ES2018)
    • Async Generators (ES2018), behind the -Xasync-generators compiler flag. Off by default; without it the compiler reports "async generators are unsupported".
  • Key Library Features:

    • ES2015 standard built-ins (Promise, Set, Map, WeakSet, WeakMap, TypedArrays, Reflect, Proxy, updated methods on Array, String, Object, etc.)
    • Extended Promise API (see "Known Deviations" for the limits of Symbol.species and microtask timing):
      • Promise.prototype.finally (ES2018)
      • Promise.allSettled (ES2020)
      • Promise.any (ES2021)
      • Promise.withResolvers (ES2024)
      • Promise.try (ES2025)
    • Symbol.prototype.description (ES2019)
    • WeakRef and FinalizationRegistry (ES2021). WeakRef, WeakMap and WeakSet also accept symbols as targets (ES2023).
    • Object.hasOwn (ES2022), Array.prototype.at / findLast (ES2022), Array.prototype.toSorted / toReversed / with / toSpliced (ES2023)
    • String.prototype.isWellFormed / toWellFormed (ES2024)
    • Iterator Helpers (ES2025): Iterator with map, filter, take, drop, flatMap, reduce, toArray, forEach, some, every, find, plus Iterator.from and Iterator.concat
    • Array grouping (ES2024): Object.groupBy and Map.groupBy
    • Set methods (ES2025): union, intersection, difference, symmetricDifference, isSubsetOf, isSupersetOf, isDisjointFrom
    • RegExp.escape (ES2025), Math.sumPrecise (ES2026), Error.isError (ES2026)
    • ArrayBuffer.prototype.detached (ES2024), Float16Array (ES2025), Uint8Array.fromBase64 (ES2026), Map.prototype.getOrInsert / WeakMap.prototype.getOrInsert (ES2026)
    • TextEncoder and TextDecoder (WHATWG, not ECMAScript)
    • Note: Support for the latest standard library features may lag behind language feature support.

Planned Features

Features Hermes intends to support in the future. Active development or implementation hasn't started or completed yet.

  • with Statements: Support is planned. See "Intentionally Excluded" for the current state.
  • ES Modules (import/export): A module system is planned. See "Intentionally Excluded" for the current state.
  • Other Standard Library Features: Newer library additions are considered but may be lower priority. Currently absent: RegExp /v (unicodeSets) flag, ArrayBuffer.prototype.transfer and resizable buffers, SharedArrayBuffer and Atomics, Array.fromAsync, explicit resource management (using, Symbol.dispose, Symbol.asyncDispose), Temporal.

Intentionally Excluded / De-prioritized Features

These features are not supported, often due to incompatibility with Hermes' AOT compilation strategy, performance concerns, limited utility, or complexity costs.

  • Local eval(): eval() cannot access or modify local variables in the surrounding lexical scope (neither in strict nor non-strict mode). This restriction is fundamental to Hermes' AOT compilation and optimization strategy; supporting local eval would severely degrade performance across the engine. Use of eval is strongly discouraged. Every direct call to eval() produces the compiler warning "Direct call to eval(), but lexical scope is not supported". The precise behavior:
    • Reading a local from inside eval throws ReferenceError, in both strict and loose mode.
    • Writing a local from inside eval throws ReferenceError in strict mode. In loose mode it fails silently: the local is left unchanged and a global of that name is created or overwritten instead.
    • eval sees the global scope, but only var and function declarations and properties of the global object. Top-level let, const and class declarations of the running script are not visible to it.
  • with Statements: Not supported yet. When source is compiled ahead of time this is a compile-time error ("with statement is not supported") which fails the build, not a runtime exception. When the VM compiles source lazily (-lazy), it surfaces as a thrown SyntaxError the first time the enclosing function is called, and the same happens when it is reached through eval() or new Function(). with hinders performance and optimization and is disallowed in strict mode. This is a current limitation rather than a permanent exclusion: support is planned.
  • ES Modules (import/export): Hermes does not currently provide a runtime ES module loader. The parser accepts the full module syntax and builds the corresponding AST, but semantic analysis rejects it ("'import' statement requires module mode"), and dynamic import() is not supported. An earlier implementation was removed because the React Native ecosystem relies on bundlers such as Metro, which provide their own module systems. An ES module system is planned.
  • Symbol.species: Not supported. The well-known symbol itself does not exist (Symbol.species is undefined), and no built-in exposes an @@species accessor. Hermes does not commit to supporting the pattern, due to its complexity and performance overhead for an AOT-focused engine. Note that the consequences reach beyond @@species overrides: subclass propagation is missing outright, so class Sub extends Array {} followed by new Sub().map(f) yields a plain Array rather than a Sub. The same applies to TypedArray methods such as subarray. Promise is the exception, because its polyfill dispatches on this.constructor; see "Known Deviations".
  • Non-Strict arguments Object Behavior: See "Known Deviations" for details on how Hermes deviates from the spec regarding parameter syncing, assignment, and var shadowing for the arguments object in non-strict mode. These deviations simplify implementation and improve performance.
  • Intl API: Not supported. A partial implementation exists for Android, which calls into Java platform APIs, and for Apple platforms, which use Foundation. It is not built by default (HERMES_ENABLE_INTL is OFF), so in a default build Intl is undefined. Even where it is enabled, coverage is incomplete: RelativeTimeFormat, PluralRules and formatRange are missing or partial, and using them can throw. The underlying platform APIs are inadequate, there is no public ICU4C on mobile, and bundling ICU4C would cost tens of megabytes. Meta does not use Intl internally and cannot invest in it, so the implementation is expected to move to extensions/contrib or a separate community-maintained repository. Use a polyfill such as FormatJS instead, accepting its start-up cost. See discussion #1211.
  • Symbol.unscopables: Not supported. Symbol.unscopables and Array.prototype[Symbol.unscopables] are both undefined. Its main purpose is tied to with, which is also unsupported, but the absence is observable to any code that reflects on the built-in prototypes.

Known Deviations & Implementation Details

Specific behaviors where Hermes differs from the ECMAScript specification or has notable implementation characteristics. These deviations are often deliberate choices prioritizing performance, simplicity, or compatibility with Hermes' AOT compilation model, especially concerning rarely used or complex legacy features. SpecIncompat.md discusses some of them in more detail.

  • Temporal Dead Zone (TDZ) Checks: Reading a let or const binding before its initializer has run should throw a ReferenceError. Hermes implements these checks, but they are off by default, because they impose a cost on every access to a lexical variable. By default such a read produces undefined instead of throwing. Pass -Xenable-tdz to hermes or shermes to enable them:

    function f() {
      var get = function () { return v; };
      get();     // undefined by default; ReferenceError with -Xenable-tdz
      let v = 1;
    }

    With the flag on, a violation the compiler can prove statically becomes a compile-time error rather than a runtime throw. Class declarations follow the same rule: by default a class binding reads as undefined before its declaration, so typeof C yields "undefined" and new C() throws a TypeError (not a ReferenceError).

  • Block Scoping of Captured Bindings: A let, const or class binding declared in a block or a loop head should be created anew each time the block is entered or the loop iterates. By default Hermes creates it once per function call instead. Name resolution and shadowing are unaffected; the difference shows only when closures capture the binding, because closures created in different iterations then share one variable. Pass -Xes6-block-scoping to hermes or shermes to get spec behavior:

    var fns = [];
    for (let i = 0; i < 3; i++) fns.push(() => i);
    fns.map(f => f());  // [3, 3, 3] by default; [0, 1, 2] with -Xes6-block-scoping
  • arguments Object Behavior (Non-Strict Mode): Hermes simplifies arguments object handling in non-strict ("loose") mode compared to the specification:

    • No Parameter Syncing: Assigning to indices of the arguments object does not dynamically update the corresponding named parameters, and vice-versa (e.g., setting arguments[0] = x does not change the value of the first named parameter). This matches strict mode behavior. (Motivation: High cost and complexity for a rare feature).
    • Assignment Forbidden: Direct assignment to the arguments identifier itself (e.g., arguments = ...;) is disallowed, unlike in spec-compliant loose mode. (Motivation: Rare, complex, little practical benefit).
    • var arguments Shadows: Declaring var arguments; inside a function creates a new variable that shadows the arguments object (like let arguments;) rather than aliasing it. (Motivation: Extremely rare, no known practical uses).
    • These arguments deviations are considered very low priority to align with the spec due to the reasons mentioned.
  • Function Declaration Hoisting (Non-Strict Mode Blocks): Most of the scoped function promotion semantics are implemented, but some corner cases in non-strict mode differ from the spec: a function declared in an inner block can overwrite one declared in an outer block at the function scope level.

    function g() {
        { function f() { return 1; } { function f() { return 2; } } }
        print(f());   // spec requires 1, Hermes prints 2
    }

    (Motivation: Affects rare edge cases primarily in non-strict mode; other major engines behave the same way in quick testing. Low priority to fix).

  • Function.prototype.toString(): Because functions are compiled ahead of time, this method does not normally return the original JavaScript source. It returns a synthesized declaration whose body is a placeholder and whose parameters are renamed:

    function foo(a, b) {}       // "function foo(a0, a1) { [bytecode] }"
    async function bar() {}     // "async function bar() { [bytecode] }"
    Math.max                    // "function max() { [native code] }"

    The result is the same whether the function was compiled from source or loaded from precompiled bytecode. A function can opt out with a source visibility directive in its body: 'show source' makes toString() return the real source text, while 'hide source' and 'sensitive' make it report [native code].

  • Promise Implementation: Promises are implemented using an internally bundled JavaScript polyfill rather than as a native intrinsic. It is compiled to bytecode by default, or compiled natively when the engine is built with HERMESVM_INTERNAL_JAVASCRIPT_NATIVE=ON. The polyfill covers the full ES2025 surface (then, catch, finally, all, allSettled, any, race, resolve, reject, try, withResolvers, Symbol.toStringTag), but the following corners differ from the spec:

    • No Symbol.species dispatch. Per spec, the prototype methods Promise.prototype.then, Promise.prototype.catch, and Promise.prototype.finally use SpeciesConstructor(this, %Promise%) to determine the constructor of the chained promise. The polyfill substitutes this.constructor (and takes the built-in Promise directly on the common-case this.constructor === Promise fast path), so a subclass that overrides Symbol.species will not see its override applied (consistent with the engine-wide "Symbol.species not supported" stance noted above). The static methods (all, allSettled, any, race, resolve, reject) use this via NewPromiseCapability per spec — Symbol.species is not involved there.
    • Extra microtask hop on subclass .then. When this.constructor !== Promise, the polyfill bridges the user's reaction to the subclass capability through an intermediate core Promise, costing one additional microtask hop compared to spec's PerformPromiseThen, which attaches the reaction directly to the capability. The fast path (this.constructor === Promise) is unaffected.
    • Promise.all 1-microtask fast path (non-spec, default). When an input is an already-fulfilled core Promise, the polyfill synchronously invokes the resolve element and collapses the spec-mandated PerformPromiseAll step 8.e microtask hop. This is a deliberate performance default; the spec-compliant .then-only dispatch is enabled under the --test262 runtime flag.
    • Microtask timing in await. Hermes' async function machinery lowers to a generator wrapped with the polyfill's then, and a few test262 tick-counting tests (e.g. await-non-promise-thenable, the for-await-of/ticks-with-…-constructor-lookup family) observe a different microtask sequence than spec because the polyfill does one fewer .constructor read on each await hop.
    • See the polyfill source.