universal_wasm_loader 0.3.0
universal_wasm_loader: ^0.3.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 v4.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: one for every WIT import.
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');
// A 5 s limit per fetch instead of the default 30 s, and a cancel token.
final token = LoadCancelToken();
final f = await wasmImport('https://example.com/mod.wasm',
options: LoadOptions(timeout: const Duration(seconds: 5), cancel: token));
}
What fails, and how (SPEC 4.0.0) #
The loader never guesses. Each of these is an error, not a default value:
| Situation | Error |
|---|---|
The .wit answers anything but 2xx, 404 or 410, or the network fails |
StateError naming the URL (before the .wasm is fetched) |
The .wit does not parse, or uses a type outside s32 s64 f32 f64 bool string |
FormatException naming the .wit and the fault |
| A WIT import has no host callback | ArgumentError naming every missing one, at load |
A WIT import returns string |
UnsupportedError, at load |
| A WIT export is missing from the module | StateError naming it, at load |
The .wasm answers an HTTP error |
StateError naming the status and URL (one request) |
A fetch takes longer than options.timeout (default 30 s; null = no limit) |
TimeoutException naming the URL and the limit |
options.cancel is cancelled |
the reason given to cancel (else a StateError) |
| A typed call has the wrong number of arguments, or one outside its type | ArgumentError naming the export and the parameter |
A host callback returns a value outside its WIT result, or a Future |
ArgumentError naming the callback, reaching the export's caller |
Only an absent .wit (HTTP 404 / 410, or a path that does not end in .wasm) gives raw exports.
Typed arguments are checked, never coerced: s32 takes an int in the 32-bit range, s64 an int
or a BigInt (and returns a BigInt), f32 / f64 a num, bool a bool, string a String.
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.3.0 | SPEC 4.0.0: loads and calls that 0.2.x accepted silently now fail (table above): a .wit that answers an HTTP error or does not parse, a missing host callback, a callback result of the wrong kind, a typed-call argument of the wrong count or kind, an s64 value (now a BigInt result). wasmImport, createSingleton and InstancePool take a new options parameter (30 s default fetch limit). parseWit throws FormatException. |
Pass a callback for every WIT import that returns its WIT result type; pass int / num / bool / String arguments that match the WIT exactly; fix or remove a malformed .wit (a server must answer 404 for an absent one). Use LoadOptions(timeout: null) for a fetch that may take over 30 s. |
| 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 with its 4.0.0 Refusals table, the lifecycle scenarios, and §10. The HTTP cases
(status codes, a server that never answers) use a local test server started by the suite
(test/support/http_server.dart). 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.