universal_wasm_loader 0.3.1
universal_wasm_loader: ^0.3.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 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 in two jobs. checks has a read-only
token and no secrets. It installs the Dart SDK and dependencies and runs analysis, the browser
tests, the fixture check and the compatibility gate (both blocking). publish runs only after
checks passes, on a fresh runner. It runs only the Dart SDK (dart pub publish, and
scripts/ci_release.dart, which uses only Dart's core libraries and GitHub's REST API), so no
dependency's code ever runs where the pub.dev credentials are on disk. The credentials are deleted
afterwards. Both jobs refuse to run if the tag has moved off the commit that triggered the run.
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.