Skip to main content

universal_wasm_loader 0.3.3 copy "universal_wasm_loader: ^0.3.3" to clipboard
universal_wasm_loader: ^0.3.3 copied to clipboard

Platformweb

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_interop over the browser's native WebAssembly and fetch. 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:

  • checks has 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 of main runs only this job.
  • tag creates the tag vX.Y.Z on the checked commit, through GitHub's REST API.
  • release makes the GitHub Release page from that tag.
  • dispatch starts .github/workflows/publish-pubdev.yml on 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) #

  1. Own the package on pub.dev. universal_wasm_loader must be owned by the publishing account (or a verified publisher).
  2. Enable automated publishing on the package's pub.dev admin page: GitHub Actions, repository synapticforge1/universalWasmLoader-dart, tag pattern v{{version}}, with workflow_dispatch events allowed (the publish run is dispatched on the tag). No GitHub environment is required.
0
likes
160
points
560
downloads

Documentation

API reference

Publisher

unverified uploader

Weekly Downloads

Web-first Dart loader for WebAssembly "DLL" modules. Auto-detects the companion .wit, applies the Canonical ABI (wasmtime profile), and returns a typed handle.

Repository (GitHub)
View/report issues

License

MIT (license)

Dependencies

web

More

Packages that depend on universal_wasm_loader