Faking this and require (and similar)

[MikeCheel]

When in ModuleCategory.Standard, there is no this reference. How can I fake one?
A lot of third party libraries refer to this (referring to either global or window).

When in ModuleCategory.CommonJS, how can override things like require so they do what i want them to do?

[ClearScriptLib]

Hello @MikeCheel,

When in ModuleCategory.Standard, there is no this reference. How can I fake one?

We aren't aware of a way to do that without modifying V8. Per the JavaScript language specification, V8 executes standard modules in a mode that forces this to be undefined. The relevant text in the specification is here. ClearScript has no way to override that.

A lot of third party libraries refer to this (referring to either global or window).

JavaScript code that depends on this having a non-undefined value cannot be executed as a standard module.

When in ModuleCategory.CommonJS, how can override things like require so they do what i want them to do?

You can't override the require function, but you can use DocumentSettings to control its behavior. If you can tell us more about your scenario, we might be able to provide specific recommendations.

Good luck!

[MikeCheel]

My scenario is I was hoping to get a third party script called bluebutton.js to run in ClearScript. I've tried various ways of getting it to run from Browserifying it to installing via node and then pulling the js files. I've tried running as Script, Standard and CommonJS. I get real close but theres always a hitch. If I run it as standard module it, wants access reference this and document which isn't there (and DOMParser which I was able to get going after a number of tries). If I run under CommonJS then it wants to require xmldom and it can't find the implementation I got working (which is why I was asking how I can override require). If I run under Script, it doesn't like to combine Script with other categories.

How can I run BlueButton under ClearScript? https://github.com/blue-button/bluebutton.js/releases/tag/0.4.2

[ClearScriptLib]

Hi @MikeCheel,

A quick look at bluebutton.js reveals that it's designed to work in the browser and in Node.js. In addition to the standard JavaScript built-ins, those environments provide extensive APIs, making many such libraries difficult to run in an application scripting environment.

However, this particular library only depends on xmldom, which has no dependencies, and ejs, which appears to be optional. It's therefore relatively easy to get it working in ClearScript.

First, let's set up the basics:

using var engine = new V8ScriptEngine();
engine.AddHostType(typeof(Console));

Next, let's bring in xmldom. To do that, we can simply npm install it in the application directory. One wrinkle is that the main file isn't named "xmldom.js". ClearScript doesn't support package.json, but we can work around that by using a system document:

var path = Path.Combine(Directory.GetCurrentDirectory(), @"node_modules\xmldom\lib\dom-parser.js");
var info = new DocumentInfo(new Uri(path)) { Category = ModuleCategory.CommonJS };
engine.DocumentSettings.AddSystemDocument("xmldom", new StringDocument(info, File.ReadAllText(path)));

Note that this doesn't execute any script code; it just configures the engine to fulfill "xmldoc" loading requests via the given in-memory document. Using a DocumentInfo with a full path allows dom-parser.js to correctly load its auxiliary files (dom.js, sax.js, etc.).

Next, let's set up a mock ejs and give the engine access to some XML data:

engine.DocumentSettings.AddSystemDocument("ejs", ModuleCategory.CommonJS, "module.exports = undefined");
engine.Script.xml = File.ReadAllText("Sample.xml");

We're now ready to bring in bluebutton.js. For this example, we'll get it straight from GitHub:

engine.DocumentSettings.AccessFlags = DocumentAccessFlags.EnableAllLoading;
engine.DocumentSettings.SearchPath = "https://github.com/blue-button/bluebutton.js/releases/download/0.4.2";
engine.Execute(new DocumentInfo { Category = ModuleCategory.CommonJS }, "BlueButton = require('bluebutton')");

As you can see, we used a CommonJS module to load bluebutton.js and expose it in the global scope, making it available to any module or normal script:

engine.Execute(@"
    record = BlueButton(xml);
    Console.WriteLine('type: ' + record.type);
    Console.WriteLine('data: ' + record.data.json());
");

Please send any additional thoughts or questions our way!

[MikeCheel]

Thank you so much, that totally works. I have a couple of questions please.

1. So to make sure I understand correctly, when you AddSystemDocument with CommonJS category, is the identifier parameter the same name that 'require' will look for in subsequent calls to 'require'?

2. For the line where you AddSystemDocument with ejs, could you provide a bit more clarity on what that line is doing? I see on line 1440 of bluebutton.js that it checks module.exports for ejs. Is that what that you are doing in the AddSystemDocument call to disable ejs?

3. For the line that actually executes BlueButton, how does it know which file to load? There is no package.json (and ClearScript doesn't care about that anyways). There are four files in that location; two non javascript files and then bluebutton.js and bluebutton.min.js.

4. If I was using browserify, which is the recommended category and approach?

5. How do V8Script objects fit into all of this? or could they?

I really wish there was a book or other comprehensive guide on ClearScript.

[ClearScriptLib]

Hi again,

So to make sure I understand correctly, when you AddSystemDocument with CommonJS category, is the identifier parameter the same name that 'require' will look for in subsequent calls to 'require'?

Yes. When a script requests that a document be loaded – be it due to require, import, or some other mechanism – the engine examines its DocumentSettings, which holds a system document table and a reference to a document loader. It first consults the former, searching for a system document with a matching identifier (the string specified by the script) and category (inherited from the requesting document). If AccessFlags includes DocumentAccessFlags.AllowCategoryMismatch, then only the identifier is used.

For the line where you AddSystemDocument with ejs, could you provide a bit more clarity on what that line is doing? I see on line 1440 of bluebutton.js that it checks module.exports for ejs. Is that what that you are doing in the AddSystemDocument call to disable ejs?

The checks on lines 1440 and 1441 are how BlueButton.js detects whether it's running in Node.js. In reality, those checks pass whenever BlueButton.js is executed via require. As it uses the ejs library only in this "Node.js mode", it may never execute line 1442, leaving the ejs variable undefined. To handle that case, the script always checks the variable before using it.

Because our example uses require('bluebutton'), those checks pass and BlueButton.js calls require('ejs'). We don't want to bring in the real ejs library, as it has quite a few dependencies. However, since the script can handle the ejs variable being undefined, all we need is a dummy script that causes require('ejs') to return undefined. The system document facility provides an easy way to set that up.

For the line that actually executes BlueButton, how does it know which file to load?

The default document loader tries every permutation of the identifier, SearchPath, and FileNameExtensions. In our case, it finds https://github.com/blue-button/bluebutton.js/releases/download/0.4.2/bluebutton.js.

If I was using browserify, which is the recommended category and approach?

Our understanding is that Browserify implements portions of the Node.js API on top of the Web APIs. Since ClearScript doesn't implement the Web APIs, the host application would have to provide whatever is required.

How do V8Script objects fit into all of this? or could they?

Sorry, please clarify. Generally speaking, ClearScript aims to make script objects easy to use on the .NET side and vice versa.

Cheers!

[MikeCheel]

I really appreciate the detailed replies.

I guess as far V8Script objects go, I was wondering how they fit in to all of this. I know they are created via CompileDocument but I wasn't sure what purpose they serve.

My biggest question right now though is are there any plans to put together some sort of comprehensive documentation on ClearScript (or maybe a book is in the works)? I really think this project has a lot of potential but I spent a LOT of time trying to get bluebutton.js to run before I finnaly gave in and consulted you guys. I think if I had a more detailed guide it would have gone better for me.

Thanks again for the detailed responses. They really helped me and I am trying to think of ways that I can use ClearScript at my company. BlueButton is one thing I am considering.

[ClearScriptLib]

Hi @MikeCheel,

I guess as far V8Script objects go, I was wondering how they fit in to all of this. I know they are created via CompileDocument but I wasn't sure what purpose they serve.

Ah, of course; you're asking about compiled scripts, not script objects. Sorry about that 😳

Anyway, compiled scripts are simply scripts that have gone through V8's compilation phase and can be executed multiple times without additional compilation overhead. We aren't clear on the exact meaning of "compilation" for a language like JavaScript, so we tend to think of it as a V8-specific tokenized or parsed script representation.

Each compiled script is bound to the V8 runtime that created it, so they're useful mostly for executing the same script in multiple engines that share a runtime. In a given engine, we prefer not to re-execute the same script over and over. Instead, we recommend invoking previously defined functions or reusing code via one of the supported module systems.

My biggest question right now though is are there any plans to put together some sort of comprehensive documentation on ClearScript (or maybe a book is in the works)?

Unfortunately, no. However, if you can think of a good topic for an in-depth article, we'll be happy to consider it for our blog.

Thanks!