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. With the release notes (CHANGELOG "## Unreleased") merged into main: raise the
# version. The level is required. Refused if below the compatibility floor or if
# the tree is not clean. Makes the "bump to vX.Y.Z" commit.
dart run scripts/bump.dart patch # 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. Check everything, then push main (and nothing else). CI does the rest.
dart run scripts/release.dart --dry-run # optional: every check, no push
dart run scripts/release.dart
The compatibility gate. bump.dart (and CI, again, before tagging) 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.
A push of main whose pubspec.yaml version has no tag yet is a release.
.github/workflows/publish.yml then runs four jobs in this order, each holding only what it needs:
checkshas a read-only token and no secrets. It runs analysis, the browser tests, the release-script tests, the fixture check and the compatibility gate, all blocking. Every other push ofmainruns only this job.tagcreates the tagvX.Y.Zon the checked commit, through GitHub's REST API.releasemakes the GitHub Release page from that tag.dispatchstarts.github/workflows/publish-pubdev.ymlon the new tag, then waits until pub.dev serves the version.
publish-pubdev.yml uploads to pub.dev with pub.dev's automated publishing (OIDC): no secret is
stored anywhere. GitHub issues a token for that one run, valid for minutes, and pub.dev accepts it
for this package only. The workflow refuses to publish unless its tag's Release page was made by
CI, so it cannot publish a tag that skipped the checks. No job that can publish or write runs a
dependency's code.
A failed release is finished with "Re-run failed jobs": each job skips what is already done, and a
tag never moves. The Dart SDK is pinned by version and checksum. No third-party action is used: the
GitHub Actions policy permits only owner-owned actions, so every step is a plain run:.
Owner setup (one-time)
- Own the package on pub.dev.
universal_wasm_loadermust be owned by the publishing account (or a verified publisher). - Enable automated publishing on the package's pub.dev admin page: GitHub Actions, repository
synapticforge1/universalWasmLoader-dart, tag patternv{{version}}, with workflow_dispatch events allowed (the publish run is dispatched on the tag). No GitHub environment is required.
Libraries
- universal_wasm_loader
- Web-first Dart loader for WebAssembly "DLL" modules.