API Host BuiltInModuleDefinition

BuiltInModuleDefinition

Immutable host definition for an opt-in native module.

Namespace: AuroraScript.Runtime.Package. Kind: class.

Back to .NET Host API Reference

Overview

BuiltInModuleDefinition connects a bare script import path to a factory callback that configures each runtime ScriptModule. Definitions are immutable and may be reused across option instances. The engine creates fresh module objects for its global environment and domains, so mutable module state is not shared between engines or domains.

Most hosts should select a definition from BuiltInModules. Construct this type directly only when supplying a custom native module.

Constructors

BuiltInModuleDefinition(string name, Action<ScriptModule> configure)
BuiltInModuleDefinition(string name, string modulePath, Action<ScriptModule> configure)

Name	Type	Required	Description
name	string	Yes	Explicit lookup name used by host module APIs and script global.getModule. Must be a non-keyword AuroraScript identifier.
modulePath	string	Yes	Bare import path. Backslashes are normalized to /; rooted paths, empty segments, trailing /, . and .. segments are rejected.
configure	Action<ScriptModule>	Yes	Callback that defines each newly created module instance.

The two-argument constructor uses name as modulePath.

var metrics = new BuiltInModuleDefinition("metrics", module =>
{
    module.Define("now", (Func<double>)(() => Stopwatch.GetTimestamp()));
});

var options = EngineOptions.Default.WithBuiltIns(builtIns =>
    builtIns.Add(metrics));

The script imports the configured bare path:

import metrics from "metrics";

Properties

Name

string Name

Explicit lookup name used by host module APIs, script global.getModule, and name-conflict detection. Runtime storage identity remains the built-in source FullPath.

ModulePath

string ModulePath

Normalized bare import path used by import Alias from "path";.

Behavior and Boundaries

• A definition does not enable itself. Add it to EngineOptions.BuiltIns before constructing AuroraEngine.
• The callback runs for each runtime module instance. Do not capture unintended shared mutable state in it.
• Enabled built-in module names and paths must be unique.
• A resolver-visible project module whose @module name collides with an enabled native module causes a linking error.
• Bare paths may contain /, but module names are single AuroraScript identifiers.