D4rt class

The main D4rt interpreter class.

This class provides the primary interface for executing Dart code at runtime. It manages the interpretation environment, handles bridged types, and provides methods for code execution with proper error handling and debugging support.

Example:

final interpreter = D4rt();

// Register a bridged class to make native types available in interpreted code
interpreter.registerBridgedClass(myBridgedClass, 'my_library');

// Execute Dart code
final result = await interpreter.execute(source: '''
  void main() {
    print("Hello from D4rt!");
  }
''');

Constructors

D4rt({bool reuseAcrossRuns = true}): Creates an interpreter.

Properties

allowedPackages → Set<String>: The packages this instance has been granted via providePackage (its security whitelist). Read-only snapshot.
no setter
bridgesFinalized → bool: Whether finalizeBridges has been called on this runner. Step 6.
no setter
classAliases → List<({String aliasName, String library, String targetName})>: GEN-100: Registered class aliases for module-env registration.
no setter
debugLoadedModuleCount → int: Step #3 (retention) — number of source modules whose parsed CompilationUnit this instance currently retains (via the live _moduleLoader's per-loader cache). 0 before the first execute or after dispose. Because every execute* builds a fresh _moduleLoader, this reflects only the current run, never an accumulation of prior runs' ASTs — the test asserts it stays bounded across N sequential executes.
no setter
functionTypedefs → List<({String library, String name})>: GEN-100: Registered function typedefs for module-env registration.
no setter
hashCode → int: The hash code for this object.
no setterinherited
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
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 execute* 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

analyze({required String source, Map<String, String>? sources, bool includeBuiltins = false}) → IntrospectionResult: Analyzes the given source code and returns introspection information about all declared functions, classes, variables, enums, and extensions.
checkPermission(dynamic operation) → bool: Checks if any permission in the granted set allows the given operation.
continuedExecute({String? source, String name = 'main', List<Object?>? positionalArgs, Map<String, Object?>? namedArgs, String? library}) → dynamic: Execute additional source code in the existing global context.
dispose() → void: Step #3 (retention) — releases the interpreter artifacts retained from the most recent run so a finished run's parsed CompilationUnit, interpreted declarations, and per-run environment become collectable while this instance is kept alive but idle.
eval(String expression) → dynamic: Evaluates an expression or statement in the context of previously executed code.
execute({String? source, String name = 'main', List<Object?>? positionalArgs, Map<String, Object?>? namedArgs, Object? args, String? library, Map<String, String>? sources, String? basePath, bool allowFileSystemImports = false}) → dynamic: Execute the given source code.
finalizeBridges() → void: Runs every extension callback registered via registerExtensions in registration order, then marks the runner as finalized.
getConfiguration() → D4rtConfiguration: Returns a complete configuration snapshot of this interpreter instance.
getEnvironmentState() → EnvironmentState?: Returns the current state of the global environment.
grant(Permission permission) → void: Grants a permission for security-sensitive operations.
hasPermission(Permission permission) → bool: Checks if a specific permission is granted.
invoke(String name, List<Object?> positionalArgs, [Map<String, Object?> namedArgs = const {}, Map<String, String>? sources]) → dynamic: Invoke a property or method on the given instance.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
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 for use in interpreted code.
registerBridgedClassLazy(String name, Type nativeType, BridgedClass thunk(), String library, {String? sourceUri}) → void: Lazily registers a bridged class: stores name / nativeType / the deferred thunk without building the BridgedClass. The body (member maps + adapter closures) is built (and memoized) only when name or nativeType is first resolved during interpretation.
registerBridgedEnum(BridgedEnumDefinition<Enum> definition, String library, {String? sourceUri}) → void: Registers a bridged enum definition for use in interpreted code.
registerBridgedExtension(BridgedExtensionDefinition definition, String library, {String? sourceUri}) → void: Registers a bridged extension for use in interpreted code.
registerClassAlias(String aliasName, String targetName, String library) → void: GEN-074: Registers a type alias for a bridged class.
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: GEN-079: 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 for use in interpreted code.
registerGlobalSetter(String name, void setter(Object? value), String library, {String? sourceUri}) → void: Registers a global setter for a top-level setter in a specific library.
registerGlobalVariable(String name, Object? value, String library, {String? sourceUri}) → void: Registers a global variable for use in interpreted code.
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 for use in interpreted code.
resetScriptDeclarations() → void: §U28 / TODO #14 — Evict script-declared entries from the current _moduleLoader.globalEnvironment so a follower execute* / executeBundle* call starts with the same name-set the last _initModule produced.
revoke(Permission permission) → void: Revokes a previously granted permission.
setDebug(bool enabled) → void: Enables or disables debug logging for the interpreter.
toString() → String: A string representation of this object.
inherited
validateRegistrations({required String source, Map<String, String>? sources, String? basePath, bool allowFileSystemImports = false}) → List<String>: Validates all bridge registrations by running the given init script and collecting all registration errors without aborting on the first one.
warmup() → void: OPEN B.11 / U25 — Pre-builds the parser + bridge infrastructure so the first real build does not cold-start mid-test under host load.

Operators

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

Static Properties

debugBridgedModuleEnvBuildCount → int: Step #2 diagnostics — number of bridged module environments built so far (process-wide). See _debugBridgedModuleEnvBuilds.
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).
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).
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. Not part of the normal runtime contract.