What is a Document? And question about isolating parts of a large number of scripts.

[the-byte-bender]

Hi,

I didn't find much documentation around what Document objects are. When to use them and why?

The important second question, is there a way to isolate multiple scripts in a way that one script can't modify globals for other scripts, but we could add host types which will be accessible to all?
I am developing a large multiplayer game with scriptables, which are things that can be scripted like items, entities, and so on. I don't want a hole V8 isolate for each script as that will get resource intensive quickly, so I use a shared runtime that we then create engines from. The scripts are long-lived and they will get specific functions called in the case of events and other special circumstances. However, now we have to add host types and objects for each new engine created from the runtime, and we have to recreate the engine if the script is updated in order for old global state the script might have made to not carry through, so to "reset" the script, and then we have to add host types and objects once again.
It would be great to add some shared host types and objects between all engines, without specifically adding them to each one, and still keep the global state isolated between the scripts, so that one script can't modify a global that another script had created. I feel like there is a better way to go about this, but I'm not sure.

[ClearScriptLib]

Hi @the-byte-bender,

I didn't find much documentation around what Document objects are. When to use them and why?

A Document instance represents a script, module, or other file retrieved from a specific location. It's the principal data type returned from a document loader, so if you're implementing a custom document loader, you'll be dealing directly with these objects. ClearScript provides a default document loader that retrieves documents from the file system and the web, and most hosts just use that.

It would be great to add some shared host types and objects between all engines

If you're asking whether you can expose a specific host object or type in multiple script engines, then yes, absolutely.

On the other hand, if you're asking whether ClearScript has a feature whereby a set of host resources is added automatically to every new script engine, then no, although you can minimize that work by exposing a single object through which script code can access the rest. The GlobalMembers feature could be useful in that scenario.

Good luck!

[ClearScriptLib]

I thought that instead of an engine for each script, we could somehow just restrict their scope just like modules.

Yes, if you execute your scripts as standard (ES6) modules, each will have its own scope. Here's an example:

engine.Evaluate(new DocumentInfo { Category = ModuleCategory.Standard }, @"
    const foo = 123; // does not create a global property
");

However, be aware of the following: Unlike normal scripts, modules are always executed in strict mode. Also, modules support additional language features such as the import statement. Finally, the top-level code in a module can be asynchronous, so if you wish to wait for the module to be evaluated fully before continuing, you'll have to do something like this:

// assuming engine constructed with V8ScriptEngineFlags.EnableTaskPromiseConversion
var result = engine.Evaluate(new DocumentInfo { Category = ModuleCategory.Standard }, code);
if (result is Task task) {
    await task;
}

Are individual script engines the only way to do this?

Separate script engines are the only way to get distinct global objects. However, if modules as discussed above are an acceptable solution, another possibility might be to wrap each script inside a strict-mode function:

engine.Evaluate($@"
    (function () {{
        ""use strict"";
        {code}
    }})()
");

Please let us know if any of these solutions work for you. Thanks!

[the-byte-bender]

Thank you. Documents seem to be perfect for what I want. One final thing: Since we will be executing something as a module, is there a way to access its exports or somehow interact with it from host? And do that for multiple modules?

[ClearScriptLib]

is there a way to access its exports or somehow interact with it from host?

If you expose your host API via AddHostObject, AddHostType, or by setting global properties, code in a module can use it exactly like code in a normal script – e.g., it can call your API to acquire other resources, register event callbacks, etc.

As for module exports, the only way to access them is by importing the module. That can be done from another module via the import statement or from any script via the import operator.

A sticking point is that both import mechanisms require some way to identify the module to be imported. For modules that reside in the file system or on the web, the module's URI automatically serves that purpose. In a code sample, the system document feature is a convenient way to bypass the complexities of document retrieval.

Suppose we have a simple module that exports two symbols, foo and bar. Let's give it a name and add it to the script engine's document configuration:

engine.DocumentSettings.AddSystemDocument("fooAndBar", ModuleCategory.Standard, @"
    export const foo = 123;
    export const bar = 'baz';
");

Now we can use a one-line script to import the module and return its exports to the host. Note that this particular code requires V8ScriptEngineFlags.EnableTaskPromiseConversion and V8ScriptEngineFlags.EnableDynamicModuleImports:

dynamic exports = await (Task<object>)engine.Evaluate("import('fooAndBar')");

Now the host can access the individual exports as follows:

Console.WriteLine("exports.bar is {0}", exports.bar);
foreach (var name in exports.PropertyNames) {
    Console.WriteLine("exports.{0} is {1}", name, exports[name]);
}

[the-byte-bender]

Thank you so much for putting up with all the questions :)
Your answers were really helpful. I think what we will do is, since we can't have script names, we'll have execution be wrapped in a function like you suggested earlier, maybe passing that function a PropertyBag so that it can "export" things using it, just like Node. This will also make updating scripts better, as we don't have to create a new engine every time. I assume that V8 does not keep track of the code between calls to Evaluate, and only cares about the side effects of that which the gc will control? So it is safe to update one piece of code, by rerunning it also inside a wrapping function, and the gc will get rid of the older one without building up some kind of internal code string or something? Sorry if that doesn't make sense.

[ClearScriptLib]

Thank you so much for putting up with all the questions :)

You're very welcome 😊

since we can't have script names

Just to be clear, that name can be anything. If you're loading modules from the file system or the web, then they already have names; otherwise, you can use algorithmically generated names or something else.

In any case, the names are only necessary for import purposes, and that's entirely optional. You can use modules without exports – that is, just like normal scripts but with private top-level contexts and some extra safety features.

we'll have execution be wrapped in a function like you suggested earlier, maybe passing that function a PropertyBag so that it can "export" things using it, just like Node.

Yes, that seems like a nice way to do it too. ClearScript supports Node.js-style CommonJS modules, but getting at the exports would still require a module name; you'd just use require instead of import. A custom solution could streamline the process for you.

I assume that V8 does not keep track of the code between calls to Evaluate, and only cares about the side effects of that which the gc will control? So it is safe to update one piece of code, by rerunning it also inside a wrapping function, and the gc will get rid of the older one without building up some kind of internal code string or something?

Sorry, we aren't quite clear on your question. Some general points:

• Methods like Evaluate are just one way to enter the engine. It also happens when the host manipulates a script object, calls a script function, resolves a promise, etc.
• It's perfectly safe to run as many scripts as necessary and to rerun a given script as many times as necessary. Just keep in mind that, within a given engine, side effects apply to the same shared object tree rooted at the global object. So, if a script adds, say, globalThis.foo, then rerunning that script could fail if globalThis.foo is initially configured as read-only. Also, for best performance, we recommend that hosts don't actually rerun the same JavaScript source code multiple times. Re-invoking an existing script function, if possible, is always faster and incurs much less overhead.
• You should be fine in terms of GC as long as reachable references to unused objects don't pile up on either side of the host-script boundary.

Good luck!