Home

Relevant source files

The following files were used as context for generating this wiki page: - [README.md](https://github.com/zhgabor/jurassic/blob/HEAD/README.md) - [Unit Tests/Core/DocumentationSamples.cs](https://github.com/zhgabor/jurassic/blob/HEAD/Unit%20Tests/Core/DocumentationSamples.cs) - [Unit Tests/Real-world/RealWorldTests.cs](https://github.com/zhgabor/jurassic/blob/HEAD/Unit%20Tests/Real-world/RealWorldTests.cs) - [Jurassic/Library/GlobalObject.cs](https://github.com/zhgabor/jurassic/blob/HEAD/Jurassic/Library/GlobalObject.cs) - [Test Suite Runner/Test Suite Files/harness/helper.js](https://github.com/zhgabor/jurassic/blob/HEAD/Test%20Suite%20Runner/Test%20Suite%20Files/harness/helper.js) - [Test Suite Runner/Test Suite Files/harness/sections.js](https://github.com/zhgabor/jurassic/blob/HEAD/Test%20Suite%20Runner/Test%20Suite%20Files/harness/sections.js) - [Jurassic/Compiler/Emit/OptimizationInfo.cs](https://github.com/zhgabor/jurassic/blob/HEAD/Jurassic/Compiler/Emit/OptimizationInfo.cs) - [Test Suite Runner/Kangax/compat-table.json](https://github.com/zhgabor/jurassic/blob/HEAD/Test%20Suite%20Runner/Kangax/compat-table.json) - [Unit Tests/Real-world/Files/showdown.js](https://github.com/zhgabor/jurassic/blob/HEAD/Unit%20Tests/Real-world/Files/showdown.js) - [Jurassic/Library/GlobalObject.g.cs](https://github.com/zhgabor/jurassic/blob/HEAD/Jurassic/Library/GlobalObject.g.cs)

Jurassic is a high-performance, standards-compliant implementation of the ECMAScript (JavaScript) language and runtime, designed to be integrated into .NET programs. It is not a standalone application for end-users, but rather a library for .NET developers to compile and execute JavaScript code within their applications. The engine compiles JavaScript directly into .NET bytecode (CIL), avoiding the overhead of an interpreter.

The project aims to support ECMAScript 3 and ECMAScript 5 (including strict mode) fully, with ongoing progress in supporting ECMAScript 6 features. It is deployed as a single .NET assembly with no native code dependencies, making it portable across .NET 3.5, .NET 4, and Silverlight.

Sources: README.md:5-11, 16-18

Features

• ECMAScript 5 Support: Full support for all ECMAScript 3 and 5 functionality, including ES5 strict mode.
• Compilation to CIL: Compiles JavaScript into .NET bytecode (CIL) for high performance, rather than using an interpreter.
• Simple API: Provides a straightforward API for embedding into .NET applications.
• Single Assembly: Deployed as a single .NET assembly with no native code dependencies.
• Debugging: Basic support for integrated debugging within Visual Studio.
• Garbage Collection: Uses light-weight code generation, ensuring that generated code is fully garbage collected.
• Extensively Tested: Passes over five thousand unit tests, demonstrating robustness and compliance.

Sources: README.md:12-18

Usage

Basic Evaluation

To use Jurassic, instantiate a ScriptEngine and use its Evaluate or Execute methods.

// File: Unit Tests/Core/DocumentationSamples.cs

// Create a new script engine
var engine = new ScriptEngine();

// Evaluate a simple expression
int result1 = engine.Evaluate<int>("5 * 10 + 2"); // returns 52

// The result can be converted to a specific type
int result2 = engine.Evaluate<int>("1.5 + 2.4"); // returns 3

Sources: Unit Tests/Core/DocumentationSamples.cs:15-26

Interoperability with .NET

Jurassic provides powerful mechanisms for interoperability between JavaScript and .NET.

Accessing .NET from JavaScript

You can expose .NET objects, values, and functions to the JavaScript environment.

Exposing Global Functions:
Use SetGlobalFunction to make a .NET delegate available as a global JavaScript function.

// File: Unit Tests/Core/DocumentationSamples.cs

var engine = new ScriptEngine();
engine.SetGlobalFunction("test", new Func<int, int, int>((a, b) => a + b));
Assert.AreEqual(11, engine.Evaluate<int>("test(5, 6)"));

Sources: Unit Tests/Core/DocumentationSamples.cs:49-54

Exposing .NET Classes:
You can expose instances of .NET classes by creating a wrapper that inherits from Jurassic.Library.ObjectInstance.

The following diagram shows how a custom .NET class AppInfo can be structured to be exposed to the Jurassic engine.

This C# code demonstrates the implementation and usage:

// File: Unit Tests/Core/DocumentationSamples.cs

public class AppInfo : ObjectInstance
{
    public AppInfo(ScriptEngine engine)
        : base(engine)
    {
        this.DefineProperty("name", new PropertyDescriptor("Test Application", PropertyAttributes.Sealed), true);
        this.DefineProperty("version", new PropertyDescriptor(5, PropertyAttributes.Sealed), true);
    }
}

// Usage:
var engine = new ScriptEngine();
engine.SetGlobalValue("appInfo", new AppInfo(engine));
string result = engine.Evaluate<string>("appInfo.name + ' ' + appInfo.version"); // "Test Application 5"

Sources: Unit Tests/Core/DocumentationSamples.cs:63-78

Calling JavaScript from .NET

You can execute JavaScript functions from .NET code using CallGlobalFunction.

// File: Unit Tests/Core/DocumentationSamples.cs

var engine = new ScriptEngine();
engine.Evaluate("function test(a, b) { return a + b }");
Assert.AreEqual(11, engine.CallGlobalFunction<int>("test", 5, 6));

Sources: Unit Tests/Core/DocumentationSamples.cs:57-61

Architecture

Jurassic is a compiling engine. It parses JavaScript source code into an Abstract Syntax Tree (AST) and then compiles it into .NET Intermediate Language (CIL).

This diagram illustrates the high-level process of executing script with Jurassic.

Key Components

• Jurassic.ScriptEngine: The main entry point for interacting with the engine. It manages state, global objects, and the compilation/execution pipeline.
• Jurassic.Compiler: This namespace contains the parser, AST nodes, and the CIL emitter. The OptimizationInfo class plays a key role in passing state and hints (like strict mode or loop context) through the compilation process.
• Jurassic.Library: Contains implementations of the standard JavaScript built-in objects, such as GlobalObject, ObjectInstance, ArrayInstance, and FunctionInstance.

Sources: Unit Tests/Core/DocumentationSamples.cs:15, Jurassic/Compiler/Emit/OptimizationInfo.cs, Jurassic/Library/GlobalObject.cs

Global Object

The global scope in Jurassic is represented by the GlobalObject class. It provides standard properties and functions required by the ECMAScript specification.

Property/Function	Description
Infinity	Represents positive infinity.
NaN	Represents Not-a-Number.
undefined	Represents the value undefined.
decodeURI()	Decodes a Uniform Resource Identifier (URI).
decodeURIComponent()	Decodes a URI component.
encodeURI()	Encodes a URI.
encodeURIComponent()	Encodes a URI component.
eval()	Evaluates JavaScript code represented as a string.
isFinite()	Determines whether a value is a finite number.
isNaN()	Determines whether a value is NaN.
escape()	(Deprecated) Encodes a string.
unescape()	(Deprecated) Decodes a string encoded with escape().

Sources: Jurassic/Library/GlobalObject.cs:25-31, 51-144, Jurassic/Library/GlobalObject.g.cs:15-23

Testing and Compliance

Jurassic includes a comprehensive test suite to ensure correctness and standards compliance. This includes unit tests and tests based on real-world JavaScript libraries.

Test Suite Runner

The project includes a web-based test runner for the Test262 suite. The runner loads tests, executes them, and presents the results in a hierarchical view based on the ECMA-262 specification chapters.

This diagram shows the flow of adding a test result to the UI.

The test runner is composed of several key JavaScript components:

• Presenter: Manages the user interface, including updating progress bars, result counts, and the failure log. It handles the overall state of the test run (started, paused, finished).
• Section: A data structure representing a section of the ECMAScript specification. It stores subsections and individual test results, and calculates pass/fail statistics for that section.
• XML Reporting: The test runner can generate an XML report of the test results, including the user agent, date, and a breakdown of tests by section.

Sources: Test Suite Runner/Test Suite Files/harness/helper.js:8, Test Suite Runner/Test Suite Files/harness/sections.js:5, Test Suite Runner/Test Suite Files/harness/helper.js:290-311

Real-World Tests

To ensure robustness, Jurassic is tested against several popular, real-world JavaScript libraries. This demonstrates its ability to handle complex and idiomatic JavaScript code. Examples include:

• Showdown: A JavaScript port of Markdown.
• CoffeeScript: A compiler for the CoffeeScript language.
• Crypto Libraries: MD5, SHA1, SHA256 implementations.
• Compression: An LZW compression library.

Sources: Unit Tests/Real-world/RealWorldTests.cs:15, 102, 65, 87, Unit Tests/Real-world/Files/showdown.js

ECMAScript 6 Status

The project actively tracks its compliance with the ECMAScript 6 standard. The status is maintained against the compat-table tests.

Feature	Status
Optimisation
proper tail calls (tail call optimisation)	:x:
Syntax
default function parameters	4/7
rest parameters	:x:
spread syntax for iterable objects	:x:
object literal extensions	:white_check_mark: 6/6
for..of loops	6/9
octal and binary literals	:white_check_mark: 4/4
template literals	6/7
RegExp "y" and "u" flags	:x:
destructuring, declarations	:x:
destructuring, assignment	:x:
destructuring, parameters	:x:
Unicode code point escapes	:white_check_mark: 4/4
new.target	:white_check_mark: 2/2
Bindings
const	:white_check_mark: 18/18
let	14/16
block-level function declaration[18]	:x:
Functions
arrow functions	:x:
class	:white_check_mark: 24/24
super	:white_check_mark: 8/8
generators	:x:
Built-ins
typed arrays	45/46
Map	18/19
Set	18/19
WeakMap	11/12
WeakSet	10/11
Proxy [25]	33/34
Reflect [26]	18/20
Promise	4/8
Symbol	:white_check_mark: 12/12
well-known symbols[27]	23/26

Sources: README.md:26-110, Test Suite Runner/Kangax/compat-table.json