PackageEncoder class

Encodes a full Dart package directory into a single ball Program.

Module naming

Each .dart file is mapped to a ball module whose name is derived from its path relative to the package root, with / replaced by . and the .dart suffix removed:

File path	Ball module name
`lib/src/models.dart`	`lib.src.models`
`lib/my_lib.dart`	`lib.my_lib`
`bin/server.dart`	`bin.server`

Import resolution

Relative imports (import 'src/utils.dart') and same-package imports (import 'package:mypkg/src/utils.dart') are both mapped to the corresponding ball module. External package imports (import 'package:other/...') are kept as empty stub modules.

Entry point

By default the encoder looks for bin/main.dart; if that does not exist it picks the lexically first file that contains void main. Override with the entryFile / entryFunction parameters.

Usage

final enc = PackageEncoder(Directory('/path/to/my_package'));
final program = enc.encode();
print(program.modules.length); // one module per .dart file + std

Constructors

PackageEncoder(Directory packageDir, {bool includeTests = false, bool resolveExternalDeps = false, PubClient? pubClient, Map<String, Program>? encodedCache, Set<String>? inProgress, int maxDepth = 10, int currentDepth = 0})

Properties

fileToModuleMap → Map<String, String>: All discovered source files and their ball module names.
no setter
hashCode → int: The hash code for this object.
no setterinherited
hasStaticTypes → bool: Whether prepareStaticTypes resolved at least one file.
no setter
includeTests → bool: Whether to also scan test/ files. Defaults to false.
final
manifest → PackageManifest: Full manifest parsed from pubspec.yaml + pubspec.lock.
final
maxDepth → int: Maximum transitive dependency depth.
final
packageDir → Directory: Root directory of the Dart package (must contain pubspec.yaml).
final
packageName → String: Package name read from pubspec.yaml (convenience getter).
no setter
packageVersion → String: Package version read from pubspec.yaml (convenience getter).
no setter
resolveExternalDeps → bool: When true, external package: imports are resolved via the pub API, downloaded, and recursively encoded instead of being stubbed.
final
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
warnings → List<String>: Warnings accumulated during dependency resolution.
final

Methods

encode({String? entryFile, String entryFunction = 'main'}) → Program: Encode the whole package and return a ball Program.
encodeAsync({String? entryFile, String entryFunction = 'main'}) → Future<Program>: Async variant of encode that supports dependency resolution.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
prepareStaticTypes() → Future<void>: Resolves every in-package .dart file with the real Dart front end so a subsequent encode sees a type-resolved AST instead of the syntax-only one parseString produces.
toString() → String: A string representation of this object.
inherited

Operators

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

Static Methods

filePathToModuleName(String relPath) → String: Convert a package-relative file path to a ball module name.
moduleNameToFilePath(String moduleName) → String: Convert a ball module name back to a relative file path.