Introduction

By default, ClearScript provides a bare scripting environment. Unless the host takes explicit steps to expose .NET objects or types, scripts can access only their core language facilities, such as the standard JavaScript built-in objects.

Although ClearScript makes it easy to expose managed resources, high-resolution timing is something that benefits from a native implementation – not because .NET doesn’t support it, but because the expensive transition to managed code and back can reduce its effectiveness.

ClearScript 7.4.5 introduces the Performance object – an optional JavaScript API for high-resolution timing, available for ClearScript’s V8-based JavaScript engine.

Setting Up

To enable the Performance object, specify V8ScriptEngineFlags.AddPerformanceObject when constructing a V8ScriptEngine instance:

var engine = new V8ScriptEngine(V8ScriptEngineFlags.AddPerformanceObject);

The API

The Performance object has the following members:

• Performance.timeOrigin: This property gets the script engine’s creation time. It is a double-precision floating-point value that represents the number of milliseconds since the Unix epoch (00:00:00 UTC on Thursday, January 1, 1970).

• Performance.now(): This method returns a high-resolution timestamp in milliseconds. It represents the time elapsed since Performance.timeOrigin.

• Performance.sleep(delay, precise): This method suspends script execution for at least the millisecond duration specified by delay. If precise is falsy or unspecified, the method calls an operating system sleep function. A truthy argument directs it to perform a “cooperative spin wait” instead, providing enhanced precision at the cost of mild CPU load.

Timer Resolution

The precision of native timing facilities differs across operating systems and can in some cases be adjusted at runtime. In addition to the Performance object, ClearScript 7.4.5 supports a new option that sets native timers to the highest available resolution while the script engine is active:

var flags = V8ScriptEngineFlags.AddPerformanceObject | V8ScriptEngineFlags.SetTimerResolution;
var engine = new V8ScriptEngine(flags);

Note that V8ScriptEngineFlags.SetTimerResolution is only a hint and may be ignored on some systems. Where supported, it can degrade overall system performance or power efficiency, so caution is recommended.

Good luck!

Introduction

JavaScript modules offer a way to split complex scripts into independent functional units with well-defined interfaces. The import and export declarations, as well as the import operator, were introduced in ECMAScript 2015 (ES6) as a standard way for modules to share code and data.

This facility supersedes earlier module specifications such as CommonJS. However, the latter remains in heavy use, and many popular libraries aren’t available in any other form.

ClearScript 7.3.7 allows JavaScript modules to import resources from CommonJS libraries. In this post we’ll walk through an example.

Basic Setup

For this example, let’s allow scripts to load documents and use the console:

engine.DocumentSettings.AccessFlags = DocumentAccessFlags.EnableFileLoading;
engine.AddHostType(typeof(Console));

Document Categories

ClearScript uses document categories to distinguish between the following document types:

• JavaScript module – ModuleCategory.Standard
• CommonJS module – ModuleCategory.CommonJS
• Normal script – DocumentCategory.Script

However, it has no way to detect the category of a document. Instead, the host must specify the category when it initiates script execution:

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

If the host doesn’t provide a category, ClearScript assumes DocumentCategory.Script.

On the other hand, if a module is loaded on behalf of another module, it inherits its category from the requesting module. In our example, Geometry inherits ModuleCategory.Standard.

Overriding the Category

Now let’s suppose that Geometry is actually a CommonJS module and looks something like this:

// Geometry.js
exports.Rectangle = class {
    constructor(width, height) {
        this.width = width;
        this.height = height;
    }
    get Area() {
        return this.width * this.height;
    }
}

Normally, the sample code above would result in a SyntaxError with a message such as “The requested module ‘Geometry’ does not provide an export named ‘Rectangle’”.

To allow our example to work, we must override Geometry’s document category. To do that, we can use a document load callback:

engine.DocumentSettings.LoadCallback = (ref DocumentInfo info) => {
    if (Path.GetFileNameWithoutExtension(info.Uri.AbsolutePath) == "Geometry") {
        info.Category = ModuleCategory.CommonJS;
    }
};

Note that we’re using a simple file name comparison to assign the document category. A real-world host might use a more generic algorithm, basing the assignment on the document’s location, its file name extension, an external manifest, or even the document’s contents.

A Final Hurdle

In ClearScript 7.3.7, V8ScriptEngine is capable of importing CommonJS resources via the standard import declaration and operator. However, by default, the document loader throws an exception if a newly loaded document is of an unexpected category.

In other words, simply overriding the category would make our example fail even earlier – at the document loading stage. ClearScript 7.3.7 retains that behavior for compatibility and safety reasons. In many cases, blocking unexpected document categories is the prudent option.

In this case, however, we can use a new flag to relax that requirement:

engine.DocumentSettings.AccessFlags |= DocumentAccessFlags.AllowCategoryMismatch;

With this flag in place, the document loader allows Geometry to pass on to the script engine, which now supports the CommonJS module category and safely imports the requested resources.

Putting It All Together

Here’s the complete, working sample code:

engine.DocumentSettings.AccessFlags = DocumentAccessFlags.EnableFileLoading | DocumentAccessFlags.AllowCategoryMismatch;
engine.DocumentSettings.LoadCallback = (ref DocumentInfo info) => {
    if (Path.GetFileNameWithoutExtension(info.Uri.AbsolutePath) == "Geometry") {
        info.Category = ModuleCategory.CommonJS;
    }
};
engine.AddHostType(typeof(Console));
engine.Execute(new DocumentInfo { Category = ModuleCategory.Standard }, @"
    import { Rectangle } from 'Geometry';
    Console.WriteLine('The area is {0}.', new Rectangle(3, 4).Area);
");

Module interoperability allows newer scripts to use the standard JavaScript module facility while consuming existing CommonJS libraries.

How About Reverse Interoperability?

Unfortunately, importing standard modules from CommonJS modules is not possible. The problem has to do with synchronous vs. asynchronous execution modes.

Specifically, standard modules can be asynchronous, so they can invoke both synchronous and asynchronous code at the top level. Even if a module doesn’t use await, its top-level code can be effectively asynchronous if it imports any asynchronous modules.

The top-level code of a CommonJS module is executed as a normal (synchronous) function, so it cannot interoperate with asynchronous code.

Good luck!

Background

.NET playgrounds such as LINQPad and .NET Fiddle offer a great way to create small programs and explore the .NET platform.

In the past, ClearScript was difficult to use with these environments due to its reliance on native V8 assemblies and the Windows-only .NET Framework. Now that it supports newer .NET runtimes as well as several popular operating systems and machine architectures, ClearScript is much easier to incorporate into LINQPad and .NET Fiddle.

ClearScript 7.3 includes additional changes that make it almost as easy to use in these environments as a pure .NET library.

LINQPad

LINQPad is a powerful .NET playground for Windows. We’ve tested ClearScript 7.3 with LINQPad 7 (x86/x64 and arm64) and LINQPad 5 (x86/x64).

Use the LINQPad NuGet Manager to add the appropriate package to your query:

• For LINQPad 7 (x86/x64) and LINQPad 5, use ClearScript Library for Windows (x86/x64) (Package ID: Microsoft.ClearScript).
  

• For LINQPad 7 (arm64), use ClearScript Library for Windows (arm64) (Package ID: Microsoft.ClearScript.win-arm64).
  

Be sure to select Version 7.3.0 or later. As soon as LINQPad completes the package import procedure, ClearScript is ready to go:

.NET Fiddle

.NET Fiddle is a convenient online .NET playground that enables easy sharing of code snippets. ClearScript 7.3 works seamlessly with its .NET 6 compiler.

Here’s how to enable ClearScript in your fiddle:

1. Select “.NET 6” in the Compiler drop-down menu:
   

2. Add the NuGet package ClearScript Library for Linux (x64) (Package ID: Microsoft.ClearScript.linux-x64). Be sure to select Version 7.3.0 or later:
   

You are now ready to use ClearScript:

You can find this fiddle here. Click here to see the full set of ClearScript examples in action.

Good luck!

Background

ClearScript offers several attributes for controlling how .NET resources are exposed for scripting. They allow hosts to expose type members under substitute names, restrict or block script access to individual resources, and adjust marshaling behavior. An example is ScriptMemberAttribute.

.NET languages typically provide dedicated syntax for declaring attributes in source code, enabling fine-grained customization. However, that approach has some disadvantages:

1. New attributes can’t be added to code developed elsewhere, such as .NET platform components and external libraries.

2. There’s no convenient and efficient way to apply attributes broadly – e.g., for automatic renaming of all exposed type members.

Custom Attribute Loaders

ClearScript now funnels all attribute access through a global facility, the custom attribute loader. The host can override that facility to virtualize attribute retrieval, gaining the ability to add new attributes to any .NET resource – as well as modify or hide conventionally declared attributes – all by overriding a single class method.

Example: Expose .NET Type Members as Lower Camel Case

By convention, the names of public .NET type members are usually upper-camel-cased (a.k.a. Pascal-cased), whereas Javascript property names are often lower-camel-cased.

Suppose you’d like to make all exposed .NET type members accessible to script code via lower-camel-cased names. Until now, if your script API included types developed elsewhere, there was no way to achieve this without writing wrappers whose member names were under your control.

Now, by overriding ClearScript’s custom attribute loader, you can write a small method to implement a global transformation to lower camel case:

class MyAttributeLoader : CustomAttributeLoader {
    public override T[] LoadCustomAttributes<T>(ICustomAttributeProvider resource, bool inherit) {
        var declaredAttributes = base.LoadCustomAttributes<T>(resource, inherit);
        if (!declaredAttributes.Any() && typeof(T) == typeof(ScriptMemberAttribute) && resource is MemberInfo member) {
            var lowerCamelCaseName = char.ToLowerInvariant(member.Name[0]) + member.Name.Substring(1);
            return new[] { new ScriptMemberAttribute(lowerCamelCaseName) } as T[];
        }
        return declaredAttributes;
    }
}

And then:

HostSettings.CustomAttributeLoader = new MyAttributeLoader();
engine.AddHostType(typeof(Console));
engine.Execute("Console.writeLine('Hello, world!');");

You can also use this technique to centralize script access control and extend other ClearScript attribute capabilities to platform and external resources.

Good luck!

Background

Top-Level Await is a feature that enables code at the outermost scope of an ECMAScript 6 module to be executed as an async function.

ClearScript 7.1.3 added an API for controlling Top-Level Await. When enabled, it caused module evaluation to return a promise, eventually to be resolved with the module’s evaluation result.

Unfortunately, due to a V8 bug, the promise resolution value is always undefined. For that reason, and to maintain compatibility with hosts that rely on immediate module evaluation results, ClearScript left Top-Level Await disabled by default.

V8 9.8 and ClearScript 7.2.2

As of version 9.8, V8 no longer allows embedders to control Top-Level Await. Instead, the feature is always enabled.

However, embedders can now ask V8 whether a loaded module requires async evaluation – true only if the module uses await or for await...of, or if any of its imported modules require async evaluation.

ClearScript 7.2.2 uses this information to extract the correct result from a promise tracking normal (non-async) module evaluation, and to return that result directly to the host.

That preserves ClearScript’s original behavior and allows async modules to work as expected. The only remaining issue, as of this blog entry, is that the evaluation result of an async module is still inaccessible due to the V8 bug mentioned above.

Good luck!

Introduction

In ClearScript 7.1 and earlier, passing a script object from one engine to another always results in the latter holding a “proxy to a proxy” – a special object that forwards property access to a managed proxy to the original script object.

The overhead of that arrangement is usually unavoidable, as script engines generally can’t be given direct access to foreign script objects.

However, there are specific scenarios in which alternate means of sharing are not only possible but preferable. ClearScript 7.2 enables the following exceptions to the normal behavior.

Engines That Share a V8 Runtime

Consider the following C# code:

using var runtime = new V8Runtime();
using var engine1 = runtime.CreateScriptEngine();
using var engine2 = runtime.CreateScriptEngine();

This creates a V8 runtime with two script engines – an arrangement that looks something like this:

Now let’s create a script object in one engine and copy a reference to the other:

engine1.Execute("foo = { bar: 123 }");
engine2.Script.foo = engine1.Script.foo;

Executing this code in ClearScript 7.1 or earlier results in the following:

With this setup, foo in engine2 is very expensive to access and may be missing some functionality. For example, JavaScript iteration protocols can’t be routed through the managed proxy.

This “double proxy” construction is usually required, as different script engines generally can’t access each other’s objects directly. In this instance, however, they can do just that – safely and without ClearScript’s involvement.

ClearScript 7.2 detects this case and produces the following configuration for the same code:

All script engines in the same V8 runtime can be given direct access to each other’s objects with full functionality, performance, and safety.

V8 Shared Array Buffers and Views

Suppose you create two V8 script engines, each within its own runtime:

using var engine1 = new V8ScriptEngine();
using var engine2 = new V8ScriptEngine();

In memory, this setup looks something like this:

Normally, script engines in separate runtimes can’t share objects. However, SharedArrayBuffer was designed specifically for sharing memory across runtimes.

ClearScript 7.1 and earlier don’t support this form of sharing. Let’s say you create a shared array buffer in one script engine and copy a reference to the other:

engine1.Execute("sab = new SharedArrayBuffer(1024)");
engine2.Script.sab = engine1.Script.sab;

In ClearScript 7.1 and earlier, this code results in the following:

In this configuration, sab in engine2 is a “double proxy” that really isn’t very useful. For example, you can’t create data views or typed arrays on top of it. Additionally, it incurs a lot of overhead, as all access is routed through the host back to engine1.

However, the same code in ClearScript 7.2 results in this:

This arrangement supports the full functionality and performance of shared array buffers in both script engines, with independent access to the shared backing store.

Finally, note that shared data views and typed arrays – that is, data views and typed arrays backed by shared array buffers – are also marshaled in this manner, enabling easy memory sharing across V8 runtimes. You can use the standard Atomics object to synchronize access to these resources.

Good luck!

We’d like to use this space for in-depth articles on ClearScript features, significant changes, and user-requested topics. Please feel free to suggest topics on the project’s Issues or Discussions pages.

Thanks for visiting!