universal_wasm_loader 0.1.0
universal_wasm_loader: ^0.1.0 copied to clipboard
Web-first Dart loader for WebAssembly "DLL" modules. Auto-detects the companion .wit, applies the Canonical ABI (wasmtime profile), and returns a typed handle.
universalWasmLoader-dart #
Universal WASM loader for Dart — the Dart port of the
Universal WASM Loader, implementing the
cross-language SPEC.md v3.0.0.
Load a WebAssembly "DLL" the way the reference loader does: auto-detect the companion .wit, apply
the Canonical ABI (wasmtime profile), and get back a typed handle.
Web-only. This package targets the browser (and Flutter web): it uses
dart:js_interopover the browser's nativeWebAssemblyandfetch. There is no Dart-VM / native runtime yet (see Runtime below).
Usage #
import 'package:universal_wasm_loader/universal_wasm_loader.dart';
Future<void> main() async {
// Auto-detects ./math_50.wit, applies the Canonical ABI.
final m = await wasmImport('math_50.wasm');
print(m.call('add', [3, 4])); // 7
print(m.call('multiply', [2.5, 4])); // 10.0
// Strings (Canonical ABI: cabi_realloc params, callee-allocated returns).
final s = await wasmImport('strings_50.wasm');
print(s.call('greet', ['World'])); // "Hello, World!"
// Host import callbacks, keyed by camelCase WIT name.
final i = await wasmImport('imports_50.wasm', hostCallbacks: {
'envMul': (num a, num b) => a * b,
'envAdd': (num a, num b) => a + b,
});
print(i.call('scale', [3.0, 4.0])); // 12.0
// Version pinning (SPEC §3): ./mod.wasm@2 checks the module's `version` global.
// final v = await wasmImport('mod.wasm@2');
}
Instance lifecycle #
// Singleton — loads once, caches (CLI / bounded-call scenarios).
final getMod = createSingleton('math_50.wasm');
final a = await getMod();
final b = await getMod(); // same instance
// Pool — N independent instances for concurrency.
final pool = InstancePool('math_50.wasm', size: 4);
final result = await pool.run((mod) => mod.call('square', [6])); // 36
ModuleExports exposes call(name, [args]), function(name), has(name), names, and the raw
rawExports escape hatch.
Runtime #
Implemented against the browser WebAssembly API via dart:js_interop. A native Dart-VM backend
(e.g. wasmtime via dart:ffi) is a possible follow-up but is not part of this package.
Not implemented (SPEC §10, optional in v3.0.0): the _initialize reactor call and the WASI-P1 shim.
The four reference fixtures need neither.
Testing #
dart pub get
dart analyze
dart test -p chrome # requires a Chrome/Chromium browser
Tests run against the wasmtk reference fixtures (math_50, booleans_50, strings_50,
imports_50) in test/fixtures/, covering the SPEC §8 suite plus the lifecycle scenarios.
Releasing #
The package version lives in pubspec.yaml (version:) — the single source of truth.
# 1. Raise the version (default: patch). Pure-POSIX alt: scripts/bump.sh
dart run scripts/bump.dart # 0.1.0 → 0.1.1
dart run scripts/bump.dart minor # 0.1.0 → 0.2.0
dart run scripts/bump.dart major # 0.1.0 → 1.0.0
# 2. (optional) Validate the package without uploading.
dart pub publish --dry-run
# 3. Tag vX.Y.Z from pubspec.yaml and push — this triggers CI to publish.
scripts/release.sh
Pushing a v* tag runs .github/workflows/publish.yml, which installs the Dart SDK and runs
dart pub publish on pub.dev.
run:-only workflow. This org's GitHub Actions policy permits onlyjrmarcum-owned actions, so the publish workflow uses nouses:steps — checkout isgit clone, the SDK is installed via the Dart apt repo, and publishing is thedart pubCLI. The official pub.dev OIDC automated-publishing reusable workflow (dart-lang/setup-dart/.github/workflows/publish.yml) is a third-party action and therefore cannot be used here; we publish with a credentials file instead.
Owner setup (one-time) #
- Own the package on pub.dev.
universal_wasm_loadermust be created/owned by the publishing account (use a verified publisher if desired). The first publish of a new name creates it. - Create the
PUB_DEV_CREDENTIALSrepo secret. Rundart pub loginlocally and complete the Google OAuth flow; this writespub-credentials.jsonto Dart's config dir (Linux~/.config/dart/, Windows%APPDATA%\dart\, macOS~/Library/Application Support/dart/). Copy the entire JSON into a GitHub Actions secret namedPUB_DEV_CREDENTIALS(Settings → Secrets and variables → Actions). It holds a refresh token — keep it secret; rotate by re-runningdart pub loginand updating the secret.