# @shexjs/extension-wasi
[](https://www.npmjs.com/package/@shexjs/extension-wasi)
[](https://github.com/shexjs/shex.js/actions/workflows/ci.yml)
The generic WASI semantic-action extension,
`http://shex.io/extensions/WASI/`.
Where the [Test extension](http://shex.io/extensions/Test/) interprets a tiny
fixed grammar (`print`/`fail`), this extension's semantic-action code **is a
program** in [WebAssembly Text](https://webassembly.github.io/spec/core/text/index.html),
run as a [WASI](https://wasi.dev/) command. Each invocation compiles the
module (cached per code text, via [wabt](https://github.com/WebAssembly/wabt))
and runs it under `wasi_snapshot_preview1`.
``` shell
npm install @shexjs/extension-wasi
```
The code takes one of two forms:
- **standalone** — code beginning with `(module` is compiled as-is: a
self-contained WASI command importing only `wasi_snapshot_preview1`;
- **library** (the compact, common form) — anything else is a list of module
*fields*, completed by [`lib/prelude.wat`](lib/prelude.wat): the prelude
supplies the WASI imports, exported memory, argv loading and print
helpers, and an exported `_start` that calls the author's
`(func $main …)`. A whole `print(o)` is:
```
%{ (func $main (call $println_o)) %}
```
The composed module still imports only `wasi_snapshot_preview1`, so any WASI
host that performs the same composition (the prelude text is part of this
extension's definition) runs the same actions.
A schema can extend the library for itself: a **start action whose fields
declare no `$main`** runs nothing — its fields are composed, after the
prelude, into every later action of the validation, so a function is
declared once and called per constraint:
```
%{
(func $myPrint (call $put_o) (call $nl))
(func $myFail (call $fail))
%}
start = @
{ . %{ (func $main (call $myPrint)) %} }
```
A start action *with* `$main` still runs once as its own program, and a
standalone `(module …)` ignores the schema's library along with the
prelude.
### the library
| helper | effect |
|--------|--------|
| `$put (ptr len)` | write bytes to fd 1 |
| `$nl ()` | write `"\n"` |
| `$println (ptr len)` | `$put` then `$nl` |
| `$put_s` `$put_p` `$put_o` `$put_n` | write a binding's value (exit 2 if absent) |
| `$println_s` `$println_p` `$println_o` `$println_n` | ditto, newline-terminated |
| `$fail ()` | exit 1 — a `SemActFailure` |
| `$strlen (ptr) → len` | NUL-terminated string length |
Author data segments start at offset **8192** (below that is the prelude's
argv/scratch space):
```
%{
(data (i32.const 8192) "spo: ")
(func $main
(call $put (i32.const 8192) (i32.const 5))
(call $put_s) (call $put_p) (call $put_o)
(call $nl))
%}
```
This is enough to express everything
[`@shexjs/extension-wasi-test`](../extension-wasi-test#readme)'s Wasm-side
Test-grammar interpreter can do, without the interpreter: each `print`/`fail`
becomes a few library calls (see the generated suite below).
## the contract
**Input — WASI argv.** The evaluation context arrives as command arguments:
```
argv[0] = "http://shex.io/extensions/WASI/"
argv[1…] = one "=" per in-scope binding:
s=, p=, o= the matched triple's terms (TripleConstraint actions)
n= the focus node (Shape and NodeConstraint actions)
```
startActs run with no bindings. Term values are serialized as in the Test
extension: the term's `.value`, except literals with a non-`xsd:string`
datatype, which appear in Turtle form
(`"1"^^http://www.w3.org/2001/XMLSchema#integer`).
**Output — WASI stdout.** Whatever the module writes to fd 1 is collected;
each newline-terminated line (plus any unterminated tail at exit) is appended
to `validator.semActHandler.results["http://shex.io/extensions/WASI/"]`.
**Verdict — the exit status.**
| exit | meaning |
|-----:|---------|
| `0` | success |
| `1` | `SemActFailure` — validation treats the action as failed; lines printed before exiting are still recorded (like Test's `fail()`) |
| `≥2` | invocation error — the extension throws (e.g. the generated test modules `exit(2)` when a binding they need is absent) |
A trap or a WAT compile error is also an invocation error.
**Escaping.** ShExC code blocks reserve `%` and `\`, so WAT embedded in a
schema writes them `\%` and `\\` (a WAT string's `\0a` newline escape becomes
`\\0a`). The parser unescapes before this extension sees the text.
## usage
```js
const WasiExt = require("@shexjs/extension-wasi");
await WasiExt.ready(); // wabt's Wasm build initializes async
const results = WasiExt.register(validator, {ShExTerm});
// ... validator.validateShapeMap(...) ...
WasiExt.done(validator);
```
`configure({impl})` selects the WASI host:
- **`shim`** (default): a self-contained implementation of the handful of
calls a command module needs (`args_sizes_get`, `args_get`, `fd_write`,
`proc_exit`, empty `environ_*`), capturing fd 1 in memory;
- **`wasi`**: Node's built-in [`node:wasi`](https://nodejs.org/api/wasi.html),
fd 1 captured through a temporary file — proving the same modules run under
a stock WASI host (or wasmtime, or any other conforming runtime).
## the recoded shexTest suite
[`test/wasi/`](test/wasi/) holds every shexTest validation test bearing the
`sht:SemanticAction` trait (except the `shapeExtern*` four, which carry the
trait for the ExternalShape mechanism and contain no code), re-coded for this
extension by [`tools/gen-tests.js`](tools/gen-tests.js): after each
`%<…Test/>{ print(o) %}` it appends a library-form
`%<…WASI/>{ (func $main (call $put_o) (call $nl)) %}` printing the same
line. The original bytes are untouched, so the recoded schemas diff against
shexTest's as pure additions and **do double duty**: an implementation
registering the Test extension fires the Test acts (unregistered WASI acts
are skipped), one registering this extension fires the WASI acts — the suite
verifies both give the same results.
The mocha suite runs each test under both extensions and requires identical
validation status and result lines, plus agreement with the manifest's
`mf:extensionResults` where declared.
Two shexTest observations the suite works around:
- the `…NoCode…` tests name their actions with fragments
(`…Test/#a`, `…Test/#b`, …) and bind code externally (`.semact` files);
`dispatchAll` only routes action names with a registered handler, and the
stock Validation-test harness registers only the base URL — so those
actions are silently skipped there, and their `extensionResults` (filtered
by `extension === `) are never compared. This suite registers
the handler under each external-code name so the declared prints are
honored.
- `schemas/1dotAbstractShapeCode1.shex`, `schemas/open1dotcloseCode1.shex`
and `schemas/openopen1dotcloseCode1closeCode3.shex` contain Test semacts
but no validation test exercises them.
---
`@shexjs/extension-wasi` is one of the [shex.js](https://github.com/shexjs/shex.js#readme) packages; installing [`shex`](https://www.npmjs.com/package/shex) pulls in the whole suite, and [its README](https://github.com/shexjs/shex.js/tree/main/packages/shex#the-shexjs-packages) maps them.