D4rtRunner class

D4rtRunner - Execute pre-parsed AST trees without analyzer dependency.

This class provides the core interpreter functionality for executing SAstNode trees. Unlike the full D4rt class in tom_d4rt_exec, D4rtRunner works exclusively with pre-parsed AST and does not require the analyzer.

Use Cases

  • Execute AST loaded from JSON files
  • Execute AST from precompiled scripts
  • Embedded interpreter without heavy analyzer dependency

Example:

// From JSON string
final runner = D4rtRunner();
final ast = runner.parseJson(jsonString);
final result = runner.execute(ast: ast);

// From JSON file
final result = await runner.executeFromJsonFile('script.ast.json');

For source code parsing and execution, use the D4rt class from tom_d4rt_exec which provides full integration with tom_ast_generator.

Constructors

D4rtRunner({bool reuseAcrossRuns = true})
Creates a D4rtRunner instance for executing pre-parsed AST.

Properties

allowedPackages → Set<String>
The packages this instance has been granted via providePackage (its security whitelist). Read-only snapshot.
no setter
bridgedClasses → Map<String, Map<String, LibraryClass>>
Registered bridged class definitions: URI → (name → class).
no setter
bridgedEnumDefinitions → Map<String, Map<String, LibraryEnum>>
Registered bridged enum definitions: URI → (name → enum).
no setter
bridgedExtensions → Map<String, List<LibraryExtension>>
Registered bridged extension definitions: URI → list of extensions.
no setter
bridgedLibraryUris → Set<String>
The set of library URIs that have at least one registered bridge (class, enum, extension, function, variable, getter, or setter).
no setter
bridgesFinalized → bool
Whether finalizeBridges has been called on this runner. Step 6.
no setter
classAliases → List<({String aliasName, String library, String targetName})>
Registered class aliases keyed by library URI.
no setter
debugLoadedModuleCount → int
Step #3 (retention) — number of bundle modules whose SCompilationUnit this runner currently retains (via the most recent _lastModuleLoader). 0 before the first execute or after dispose. Because every executeBundle builds a fresh loader, this reflects only the current run, never an accumulation of prior runs' ASTs.
no setter
functionTypedefs → List<({String library, String name})>
Registered function typedefs.
no setter
hashCode → int
The hash code for this object.
no setterinherited
libraryFunctions → Map<String, Map<String, LibraryFunction>>
Registered library functions: URI → (name → function).
no setter
libraryGetters → Map<String, Map<String, LibraryGetter>>
Registered library getters: URI → (name → getter).
no setter
libraryReExports → Map<String, List<({Set<String>? hide, Set<String>? show, String uri})>>
GEN-107: Registered library re-exports keyed by source library URI.
no setter
librarySetters → Map<String, Map<String, LibrarySetter>>
Registered library setters: URI → (name → setter).
no setter
libraryVariables → Map<String, Map<String, LibraryVariable>>
Registered library variables: URI → (name → variable).
no setter
onUncaughtError ↔ void Function(Object error, StackTrace stackTrace)?
Called when an error escapes an interpreted callback that the platform invoked outside the script's own future chain.
getter/setter pair
reuseAcrossRuns → bool
Whether the cross-run bridge caches are reused between executeBundle* calls. See the constructor. false forces a fresh warm parent and fresh bridged module environments on every run for full inter-run isolation.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
visitor → InterpreterVisitor?
Gets the current interpreter visitor instance.
no setter

Methods

checkPermission(dynamic operation) → bool
Checks if any permission allows the given operation.
dispose() → void
Step #3 (retention) — releases the interpreter artifacts retained from the most recent run so a finished run's SCompilationUnit graph, interpreted declarations, and per-run environment become collectable while this runner is kept alive but idle.
eval(String expression) → dynamic
Evaluate an expression in the current context.
execute({required SCompilationUnit ast, String name = 'main', List<Object?>? positionalArgs, Map<String, Object?>? namedArgs}) → dynamic
Execute an AST.
executeBundle(AstBundle bundle, {String? entryPoint, String name = 'main', List<Object?>? positionalArgs, Map<String, Object?>? namedArgs}) → dynamic
Execute an AstBundle with full import resolution.
executeBundleAs<T>(AstBundle bundle, {String? entryPoint, String name = 'main', List<Object?>? positionalArgs, Map<String, Object?>? namedArgs}) → T
Execute bundle and unwrap the result to type T via D4.unwrapAs.
executeBundleAsAsync<T>(AstBundle bundle, {String? entryPoint, String name = 'main', List<Object?>? positionalArgs, Map<String, Object?>? namedArgs}) → Future<T>
Async variant of executeBundleAs — awaits the result if it is a Future before unwrapping to T.
executeFromJson({required String jsonString, String name = 'main', List<Object?>? positionalArgs, Map<String, Object?>? namedArgs}) → dynamic
Execute from a JSON string.
executeFromJsonFile({required String path, String name = 'main', List<Object?>? positionalArgs, Map<String, Object?>? namedArgs}) → Future
Execute from a JSON file.
finalizeBridges() → void
Runs every extension callback registered via registerExtensions in registration order, then marks the runner as finalized.
grant(Permission permission) → void
Grants a permission.
hasPermission(Permission permission) → bool
Checks if a specific permission is granted.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
parseJson(String jsonString) → SCompilationUnit
Parses an AST from a JSON string.
parseJsonFile(String path) → Future<SCompilationUnit>
Parses an AST from a JSON file.
providePackage(String packageName) → bool
Step 7 — Grants packageName to this instance and reports whether its bridge definitions are already in the process-global pool.
registerBridgedClass(BridgedClass definition, String library, {String? sourceUri}) → void
Registers a bridged class definition.
registerBridgedClassLazy(String name, Type nativeType, BridgedClass thunk(), String library, {String? sourceUri}) → void
Step #17 — registers a bridged class via a deferred factory thunk.
registerBridgedEnum(BridgedEnumDefinition<Enum> definition, String library, {String? sourceUri}) → void
Registers a bridged enum definition.
registerBridgedExtension(BridgedExtensionDefinition definition, String library, {String? sourceUri}) → void
Registers a bridged extension.
registerClassAlias(String aliasName, String targetName, String library) → void
GEN-074: Registers a class alias (type alias).
registerExtensions(String packageName, void body()) → void
Registers a body callback that wires additional bridge state (e.g. registerRelaxers(), registerD4rtRuntimeExtensions(), registerD4rtInterfaceProxyOverrides()) after the main registerBridgedClass/registerBridgedEnum/etc. registrations for packageName have happened.
registerFunctionTypedef(String name, String library) → void
Registers a function typedef so it can be resolved as a type.
registerGenericConstructor(String className, String constructorName, GenericConstructorFactory factory) → void
Registers a generic-constructor factory for className.constructorName.
registerGlobalGetter(String name, Object? getter(), String library, {String? sourceUri}) → void
Registers a global getter.
registerGlobalSetter(String name, void setter(Object? value), String library, {String? sourceUri}) → void
Registers a global setter.
registerGlobalVariable(String name, Object? value, String library, {String? sourceUri}) → void
Registers a global variable.
registerInterfaceProxy(String bridgedTypeName, InterfaceProxyFactory factory) → void
Registers an interface-proxy factory for bridgedTypeName.
registerLibraryReExport(String sourceUri, String targetUri, {Set<String>? show, Set<String>? hide}) → void
GEN-107: Registers a re-export from one library to another.
registerRelaxerFactory(String baseTypeName, GenericTypeWrapperFactory factory) → void
Registers a relaxer (generic-type-wrapper) factory for baseTypeName.
registerTopLevelFunction(String? name, NativeFunctionImpl function, String library, {String? sourceUri, String? signature}) → void
Registers a top-level native function.
registertopLevelFunction(String? name, NativeFunctionImpl function, String library, {String? sourceUri, String? signature}) → void
Lower-case alias for registerTopLevelFunction.
resetScriptDeclarations() → void
§U28 / TODO #14 — Evict script-declared entries from the current global environment so a follower executeBundle call starts with the same name-set the first build saw.
revoke(Permission permission) → void
Revokes a permission.
setDebug(bool enabled) → void
Enables or disables debug logging.
toString() → String
A string representation of this object.
inherited
warmup() → void
OPEN B.11 / U25 — Pre-builds the bridge + stdlib infrastructure so the first real execute/executeBundle call does not cold-start mid-test.

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Properties

debugBridgedModuleEnvBuildCount → int
Diagnostics / test introspection — number of bridged-module envs built so far (PERF step #2). Increments only on a cache miss.
no setter
debugPooledPackages → Set<String>
Diagnostics / test introspection — the set of package names currently in the process-global pool (including the synthetic _defaultPackage once a legacy register* call has run). Read-only; does not expose the bundles.
no setter
debugWarmParentCacheSize → int
Diagnostics / test introspection — how many warm parents are currently cached for migrated instances (step 8). Lets tests assert that two consecutive executes for the same allowed-set build the parent once.
no setter

Static Methods

debugPooledClassCount(String packageName) → int
Diagnostics / test introspection — the number of bridged classes pooled under packageName across all source URIs (0 if not pooled). Lets tests assert that a freshly-provided package's definitions landed in the pool without exposing the internal bundle type.
debugResetPool() → void
Diagnostics / test introspection — clears the process-global pool and the step-8 warm-parent cache (the migrated-instance parents are keyed on pool contents, so they must be evicted together to stay consistent). Used only by tests that need a pristine pool (both are otherwise immortal for the life of the process). Not part of the normal runtime contract.