ClearScript Documentation

ClearScript is a library designed to integrate scripting capabilities into .NET applications. It allows you to create a script engine, expose .NET objects or types to that engine, and execute scripts that can interact with your .NET code.

Supported Script Engines:

• JavaScript: via Google's V8 engine or Microsoft's JScript.
• VBScript

Key Capabilities:

• Seamless Integration: Exposed .NET resources require no special modification or decoration. Scripts gain access to methods, properties, fields, events, indexers, extension methods, and more.
• Advanced Type Support: Full support for generic types/methods (including C#-like type inference), constructors, and nested types.
• Collection Interop: .NET collections work with native script iteration (e.g., for...of in V8, Enumerator in JScript, or For Each...Next in VBScript).
• Bidirectional Communication: Scripts can invoke .NET methods (including those with out parameters, optional parameters, and params arrays), and the host can invoke script functions or access script objects directly.
• Modern JavaScript Features (V8): Supports JavaScript modules, typed arrays for fast data transfer, and automatic conversions for BigInt, Date, and Promise (from .NET Task).

ClearScript uses DocumentCategory to distinguish how scripts should be executed and how they interact with the module system. Because ClearScript cannot automatically detect the category of a document, the host must provide this context.

Categories

• ModuleCategory.Standard: Represents a standard ES6 JavaScript module.
• ModuleCategory.CommonJS: Represents a CommonJS module.
• DocumentCategory.Script: The default category used if no category is provided. This is for normal scripts that are not part of a module system.

Behavior Rules

• Explicit Execution: When calling engine.Execute(), you should pass a DocumentInfo object specifying the Category to ensure the entry point is treated correctly.
• Inheritance: When a module is loaded by another module, it inherits the category of the requesting module. For example, if a Standard module imports a file, that file is treated as Standard unless the LoadCallback overrides it.
• Detection: Use engine.DocumentSettings.LoadCallback to intercept document loading and manually set info.Category for specific files.

ClearScript provides a robust bridge between .NET and scripting environments with the following features:

.NET Integration

• Zero Modification: Exposed resources require no special decoration or coding.
• Rich Access: Scripts can access methods, properties, fields, events, indexers, extension methods, and constructors.
• Generics Support: Full support for generic types and methods with C#-like type inference.
• Collection Iteration: .NET collections support native iteration mechanisms:
  • V8: for...of and for await...of
  • JScript: Enumerator
  • VBScript: For Each...Next
• Advanced Method Invocation: Supports output parameters, optional parameters, and parameter arrays.
• Callbacks: Script delegates enable calling back into script code from .NET.
• Assembly Exposure: Ability to expose all types in one or more assemblies in a single step.

Engine-Specific Features

• V8: Supports JavaScript typed arrays (fast data transfer), JavaScript modules, BigInt conversion, Date conversion, and Promise conversion.
• JScript/V8: Supports CommonJS modules.

Platform Support

• Runtimes: .NET 5.0+, .NET Framework 4.6.2+, .NET Core 3.1, and .NET Standard 2.1.
• OS: Windows (x86/x64/arm64), Linux (x64/arm/arm64), and macOS (x64/arm64).

In ClearScript 7.3.7+, you can allow standard ES6 modules to import CommonJS modules. This requires three specific configuration steps:

1. Enable File Loading: Set DocumentAccessFlags.EnableFileLoading so the engine can resolve module URIs.
2. Allow Category Mismatch: Set DocumentAccessFlags.AllowCategoryMismatch. By default, the loader throws an exception if a loaded module's category (e.g., CommonJS) differs from the requesting module's category (e.g., Standard). This flag relaxes that restriction.
3. Specify Categories via LoadCallback: Since ClearScript cannot automatically detect if a file is ES6 or CommonJS, you must use the DocumentSettings.LoadCallback to manually assign the correct ModuleCategory based on the file's URI or name.

Note: Reverse interoperability (CommonJS importing ES6) is not supported because CommonJS execution is synchronous and cannot handle the potentially asynchronous nature of ES6 modules.

// 1. Configure access flags
engine.DocumentSettings.AccessFlags = DocumentAccessFlags.EnableFileLoading | DocumentAccessFlags.AllowCategoryMismatch;

// 2. Define how to categorize files (e.g., identifying CommonJS files)
engine.DocumentSettings.LoadCallback = (ref DocumentInfo info) => {
    if (Path.GetFileNameWithoutExtension(info.Uri.AbsolutePath) == "Geometry") {
        info.Category = ModuleCategory.CommonJS;
    }
};

// 3. Execute the entry point as a Standard module
engine.Execute(new DocumentInfo { Category = ModuleCategory.Standard }, @"
    import { Rectangle } from 'Geometry';
    Console.WriteLine('The area is {0}.', new Rectangle(3, 4).Area);
");