universal_wasm_loader 0.2.1
universal_wasm_loader: ^0.2.1 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).
Install #
Published on pub.dev: universal_wasm_loader.
dart pub add universal_wasm_loader
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.
SPEC §10 (producer model) is implemented since 0.2.0. Every module gets a minimal WASI Preview 1 shim
(wasi_snapshot_preview1; fd_write goes to the browser console), so library modules that do I/O
load in the browser. A reactor module's exported _initialize is called once, automatically, right
after instantiation; don't call it yourself.
⚠️ Breaking Changes #
| Version | What changed | How to migrate |
|---|---|---|
| 0.2.0 | A module's exported _initialize is now called automatically after instantiation (behaviour, not API). |
Remove any manual call to _initialize; calling it again initializes the module twice. |
From the release after 0.2.0 on, every release is checked against the previous one by
scripts/compat.dart (added 2026-10-22): a removed or changed API symbol requires a major version (pre-1.0: a minor plus a row
here), and the previous release's tests must still pass for a patch or minor.
Testing #
dart pub get
dart analyze
dart test -p chrome # requires a Chrome/Chromium browser
dart run scripts/check_fixtures.dart
Tests run against the shared reference fixtures in test/fixtures/ (math_50, booleans_50,
strings_50, imports_50, plus the §10 fixtures wasi_io_50 and init_check), covering the
SPEC §8 suite, the lifecycle scenarios, and §10. The fixtures are byte-identical copies of the
reference loader's set, built by wasmtk modc. test/fixtures/fixtures.json stamps the wasmtk
commit and each file's sha256, and scripts/check_fixtures.dart verifies them against it.
Releasing #
The package version lives in pubspec.yaml (version:) — the single source of truth.
# 0. See what the next release must be (compares with the last release tag).
dart run scripts/compat.dart
# 1. Raise the version (default: patch). Refused if below the compatibility floor.
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.
dart run scripts/release.dart
The compatibility gate. bump.dart (and CI, again, on the tag) diffs the public API against the
last release using the committed api-surface.json, which is generated by dart run scripts/surface.dart. A removed or changed symbol needs a major, an added one at least a minor. The
previous release's tests must also pass against the new code for a patch or minor. Before 1.0, a
minor may stand in for a major, but it needs a row labelled _next release_ in the Breaking
Changes table above. bump.dart replaces that label with the version, and does the same for the
CHANGELOG's Unreleased heading. An intended API change re-baselines api-surface.json in its own commit first.
Pushing a v* tag runs .github/workflows/publish.yml, which installs the Dart SDK, runs the
fixture check and the compatibility gate (both blocking), and runs dart pub publish on pub.dev.
run:-only workflow. The GitHub Actions policy permits only first-party (owner-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.