npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@casual-simulation/engine262

v0.0.1-4de2170374e22761996e46eb1362f4496ee57f8f

Published

Implementation of ECMA-262 in JavaScript

Downloads

797

Readme

engine262

An implementation of ECMA-262 in JavaScript

Goals

  • 100% Spec Compliance
  • Introspection
  • Ease of modification

Non-Goals

  • Speed at the expense of any of the goals

This project is bound by a Code of Conduct.

Join us in #engine262:matrix.org.

Changes from Mainline

  • Additional generators have been added so that it is possible to step through the evaluation by simply calling .next() on the returned iterator.
    • It should be possible to step into most user code, including callbacks from standard library functions.
    • Scenarios that are mostly not supported are stepping into Proxy getters/setters from within standard library functions. For example, it is currently not possible to step into a Proxy getter when using a proxy as the thisValue for standard library functions.
    • The process for enabling stepping for such features is pretty simple: you look for situations where the unwind() function is used and replace it with yield*. The tricky part is that using yield* forces you to make the containing function to be a generator function, which means that callers of that function now also need to use yield* or unwind().

Why this exists

While helping develop new features for JavaScript, I've found that one of the most useful methods of finding what works and what doesn't is being able to actually run code using the new feature. Babel is fantastic for this, but sometimes features just can't be nicely represented with it. Similarly, implementing a feature in one of the engines is a large undertaking, involving long compile times and annoying bugs with the optimizing compilers.

engine262 is a tool to allow JavaScript developers to have a sandbox where new features can be quickly prototyped and explored. As an example, adding do expressions to this engine is as simple as the following diff:

--- a/src/evaluator.mjs
+++ b/src/evaluator.mjs
@@ -232,6 +232,8 @@ export function* Evaluate(node) {
     case 'GeneratorBody':
     case 'AsyncGeneratorBody':
       return yield* Evaluate_AnyFunctionBody(node);
+    case 'DoExpression':
+      return yield* Evaluate_Block(node.Block);
     default:
       throw new OutOfRange('Evaluate', node);
   }
--- a/src/parser/ExpressionParser.mjs
+++ b/src/parser/ExpressionParser.mjs
@@ -579,6 +579,12 @@ export class ExpressionParser extends FunctionParser {
         return this.parseRegularExpressionLiteral();
       case Token.LPAREN:
         return this.parseParenthesizedExpression();
+      case Token.DO: {
+        const node = this.startNode();
+        this.next();
+        node.Block = this.parseBlock();
+        return this.finishNode(node, 'DoExpression');
+      }
       default:
         return this.unexpected();
     }

This simplicity applies to many other proposals, such as optional chaining, pattern matching, the pipeline operator, and more. This engine has also been used to find bugs in ECMA-262 and test262, the test suite for conforming JavaScript implementations.

Requirements

To run engine262 itself, a engine with support for recent ECMAScript features is needed. Additionally, the CLI (bin/engine262.js) and test262 runner (test/test262/test262.js) require a recent version of Node.js.

Using engine262

Use it online: https://engine262.js.org

You can install the latest engine262 build from GitHub Packages.

If you install it globally, you can use the CLI like so:

$ engine262

Or, you can install it locally and use the API:

'use strict';

const {
  Agent,
  setSurroundingAgent,
  ManagedRealm,
  Value,

  CreateDataProperty,

  inspect,
} = require('engine262');

const agent = new Agent({
  // onDebugger() {},
  // ensureCanCompileStrings() {},
  // hasSourceTextAvailable() {},
  // onNodeEvaluation() {},
  // features: [],
});
setSurroundingAgent(agent);

const realm = new ManagedRealm({
  // promiseRejectionTracker() {},
  // resolveImportedModule() {},
  // getImportMetaProperties() {},
  // finalizeImportMeta() {},
  // randomSeed() {},
});

realm.scope(() => {
  // Add print function from host
  const print = new Value((args) => {
    console.log(...args.map((tmp) => inspect(tmp)));
    return Value.undefined;
  });
  CreateDataProperty(realm.GlobalObject, new Value('print'), print);
});

realm.evaluateScript(`
'use strict';

async function* numbers() {
  let i = 0;
  while (true) {
    const n = await Promise.resolve(i++);
    yield n;
  }
}

(async () => {
  for await (const item of numbers()) {
    print(item);
  }
})();
`);

// a stream of numbers fills your console. it fills you with determination.

Testing engine262

This project can be run against test262, which is particularly useful for developing new features and/or tests:

$ # build engine262
$ npm build

$ # update local test262 in test/test262/test262
$ git submodule update --init --recursive

$ # update local test262 to a pull request
$ pushd test/test262/test262
$ git fetch origin refs/pull/$PR_NUMBER/head && git checkout FETCH_HEAD
$ popd

$ # run specific tests
$ npm run test:test262 built-ins/AsyncGenerator*

$ # run all tests
$ npm run test:test262

The output will indicate counts for total tests, passing tests, failing tests, and skipped tests.

Related Projects

Many people and organizations have attempted to write a JavaScript interpreter in JavaScript much like engine262, with different goals. Some of them are included here for reference, though engine262 is not based on any of them.

  • https://github.com/facebook/prepack
  • https://github.com/mozilla/narcissus
  • https://github.com/NeilFraser/JS-Interpreter
  • https://github.com/metaes/metaes
  • https://github.com/Siubaak/sval