Beginner

# Install WABT on macOS
brew install wabt        # => installs wat2wasm, wasm-objdump, wasm-decompile, etc.
 
# Create the minimal WAT module
cat > empty.wat << 'EOF'
(module)                 ;; => defines an empty WebAssembly module
                         ;; => compiles to exactly 8 bytes of binary
EOF
 
# Compile WAT text to .wasm binary
wat2wasm empty.wat -o empty.wasm   # => reads empty.wat, writes empty.wasm
                                    # => exit code 0 on success
 
# Inspect binary size
ls -la empty.wasm        # => -rw-r--r--  1 user group  8 Apr 29 00:00 empty.wasm
                         # => 8 bytes: magic (4) + version (4)

;; value-types.wat — demonstrates all core WAT value types
(module
  ;; Function returning an i32 constant
  (func (export "get_i32") (result i32)  ;; => declares func returning one i32
    i32.const 42                          ;; => pushes integer 42 onto the stack
                                          ;; => stack: [42 : i32]
  )                                       ;; => implicit return: top of stack
 
  ;; Function returning an i64 constant
  (func (export "get_i64") (result i64)  ;; => declares func returning one i64
    i64.const 9007199254740993            ;; => pushes 64-bit integer (> JS Number.MAX_SAFE_INTEGER)
                                          ;; => stack: [9007199254740993 : i64]
  )
 
  ;; Function returning an f32 constant
  (func (export "get_f32") (result f32)  ;; => declares func returning one f32
    f32.const 3.14                        ;; => pushes single-precision float
                                          ;; => stack: [3.14 : f32] (only ~7 significant digits)
  )
 
  ;; Function returning an f64 constant
  (func (export "get_f64") (result f64)  ;; => declares func returning one f64
    f64.const 2.718281828459045           ;; => pushes double-precision float
                                          ;; => stack: [2.718281828459045 : f64] (~15-17 significant digits)
  )
)

;; functions.wat — function definition, locals, parameters, exports
(module
  ;; Simple function: takes two i32 params, returns their sum
  (func $add                             ;; => internal name $add (for calling within module)
    (param $a i32)                       ;; => first parameter, named $a, type i32
    (param $b i32)                       ;; => second parameter, named $b, type i32
    (result i32)                         ;; => return type: one i32
    local.get $a                         ;; => push value of param $a onto stack
                                         ;; => stack: [$a : i32]
    local.get $b                         ;; => push value of param $b onto stack
                                         ;; => stack: [$a : i32, $b : i32]
    i32.add                              ;; => pop two i32s, push their sum
                                         ;; => stack: [($a + $b) : i32]
  )                                      ;; => top of stack is the return value
 
  ;; Export $add as "add" to the JavaScript host
  (export "add" (func $add))             ;; => makes $add callable as module.exports.add
 
  ;; Function with a local variable
  (func $square
    (param $n i32)
    (result i32)
    (local $result i32)                  ;; => declare local variable $result, type i32
                                         ;; => locals are zero-initialized
    local.get $n                         ;; => push $n => stack: [$n]
    local.get $n                         ;; => push $n again => stack: [$n, $n]
    i32.mul                              ;; => pop two i32s, push product => stack: [$n*$n]
    local.set $result                    ;; => pop stack top, store in $result
                                         ;; => stack: []
    local.get $result                    ;; => push $result => stack: [$result]
  )                                      ;; => returns $result (= $n * $n)
 
  (export "square" (func $square))       ;; => export as "square"
)

# Compile WAT to Wasm binary (from Example 3's functions.wat)
wat2wasm functions.wat -o functions.wasm   # => reads text, writes binary
                                            # => validates module structure during compilation
                                            # => exit 0 on success, non-zero on error
 
# Check binary output
ls -lh functions.wasm    # => shows file size (typically 30-100 bytes for small modules)
 
# Verbose output: see all sections
wat2wasm functions.wat --dump-module       # => prints section layout to stdout
                                            # => Output: sections: type, function, export, code
 
# Validate a .wasm file without executing (useful for CI)
wasm-validate functions.wasm              # => exit 0 if valid Wasm binary
                                           # => exit 1 with error description if invalid
 
# Round-trip: decompile .wasm back to .wat
wasm2wat functions.wasm -o functions_rt.wat   # => reproduces (numbered, not named) WAT
                                               # => $add becomes (func (;0;))

# Full section dump of a .wasm file
wasm-objdump -x functions.wasm
# => Output:
# functions.wasm: file format wasm 0x1
#
# Section Details:
#
# Type[2]:
#  - type[0] (i32, i32) -> i32     ;; => function signature for $add
#  - type[1] (i32) -> i32          ;; => function signature for $square
#
# Function[2]:
#  - func[0] sig=0                  ;; => $add uses type[0]
#  - func[1] sig=1                  ;; => $square uses type[1]
#
# Export[2]:
#  - func[0] -> "add"               ;; => exported as "add"
#  - func[1] -> "square"            ;; => exported as "square"
#
# Code[2]:
#  - func[0] size=7 <add>           ;; => 7 bytes of bytecode for $add
#  - func[1] size=9 <square>        ;; => 9 bytes of bytecode for $square
 
# Disassemble instructions (--disassemble or -d)
wasm-objdump -d functions.wasm
# => Code Disassembly:
# 00002e func[0] <add>:             ;; => byte offset 0x2e in file
#  00002f: 20 00                    local.get 0     ;; => get param 0 ($a)
#  000031: 20 01                    local.get 1     ;; => get param 1 ($b)
#  000033: 6a                       i32.add         ;; => add
#  000034: 0b                       end             ;; => function end
 
# Show only exports
wasm-objdump -x -j Export functions.wasm   # => -j selects specific section
                                             # => Output: only Export section

# Decompile to C-like pseudocode
wasm-decompile functions.wasm -o functions.dcmp
# => writes human-readable pseudocode to functions.dcmp
 
cat functions.dcmp
# => Output (approximate — format varies by WABT version):
# export function add(a:int, b:int):int {
#   return a + b;      ;; => clearly shows the addition
# }
#
# export function square(n:int):int {
#   var result:int;    ;; => shows local variable declaration
#   result = n * n;    ;; => shows multiplication assignment
#   return result;
# }
 
# Decompile directly to stdout (no -o flag)
wasm-decompile functions.wasm            # => prints to stdout
                                          # => same content, no file written
 
# Useful for third-party .wasm files
wasm-decompile vendor-lib.wasm | grep -n "function"   # => list all function names
                                                         # => helps audit foreign modules

;; control-flow.wat — block, loop, if/else, br, br_if
(module
  ;; Computes absolute value of an i32
  (func $abs (param $x i32) (result i32)
    local.get $x           ;; => push $x => stack: [$x]
    i32.const 0            ;; => push 0  => stack: [$x, 0]
    i32.lt_s               ;; => signed less-than: pops two i32s, pushes 1 if $x < 0, else 0
                           ;; => stack: [($x < 0) : i32]
    if (result i32)        ;; => pop condition; enter then-branch if non-zero
      i32.const 0          ;; => push 0
      local.get $x         ;; => push $x => stack: [0, $x]
      i32.sub              ;; => 0 - $x = negation => stack: [-$x]
    else
      local.get $x         ;; => else-branch: push $x unchanged
    end                    ;; => if/else produces one i32 result (top of stack)
  )                        ;; => returns result of if/else
 
  (export "abs" (func $abs))
 
  ;; Count-down loop: counts from n down to 0, returns 0
  (func $countdown (param $n i32) (result i32)
    (local $i i32)          ;; => loop counter, initialized to 0
    local.get $n            ;; => push $n
    local.set $i            ;; => $i = $n (start at n, count down)
 
    block $exit             ;; => label $exit: br $exit exits this block
      loop $top             ;; => label $top: br $top restarts this loop
        local.get $i        ;; => push $i
        i32.const 0         ;; => push 0
        i32.le_s            ;; => $i <= 0?
        br_if $exit         ;; => if $i <= 0, jump to $exit (exits loop)
                            ;; => otherwise fall through
 
        local.get $i        ;; => push $i
        i32.const 1         ;; => push 1
        i32.sub             ;; => $i - 1
        local.set $i        ;; => $i = $i - 1 (decrement)
 
        br $top             ;; => unconditional jump to $top (next iteration)
      end                   ;; => end of loop $top
    end                     ;; => end of block $exit (br $exit lands here)
 
    local.get $i            ;; => push final $i (which is 0)
  )
 
  (export "countdown" (func $countdown))
)

;; fibonacci.wat — recursive Fibonacci demonstrating function calls
(module
  (func $fib                    ;; => internal function, named $fib
    (param $n i32)              ;; => n: which Fibonacci number to compute
    (result i32)                ;; => returns the nth Fibonacci number
    local.get $n                ;; => push $n
    i32.const 2                 ;; => push 2
    i32.lt_s                    ;; => $n < 2?  (base case: fib(0)=0, fib(1)=1)
    if (result i32)             ;; => if $n < 2
      local.get $n              ;; => return $n directly (fib(0)=0, fib(1)=1)
    else
      local.get $n              ;; => push $n
      i32.const 1               ;; => push 1
      i32.sub                   ;; => $n - 1
      call $fib                 ;; => recursive call fib($n - 1)
                                ;; => result pushed onto stack
 
      local.get $n              ;; => push $n
      i32.const 2               ;; => push 2
      i32.sub                   ;; => $n - 2
      call $fib                 ;; => recursive call fib($n - 2)
                                ;; => result pushed onto stack
 
      i32.add                   ;; => fib($n-1) + fib($n-2)
    end                         ;; => if/else produces one i32
  )
 
  (export "fib" (func $fib))    ;; => export fib to JavaScript host
)

// Load and call fib from JavaScript
const { instance } = await WebAssembly.instantiateStreaming(
  fetch("fibonacci.wasm"), // => fetches binary from server
);
console.log(instance.exports.fib(10)); // => 55
console.log(instance.exports.fib(20)); // => 6765
// Note: exponential time complexity — fib(40) is slow (no memoization)

// instantiate-streaming.js — recommended Wasm loading pattern
 
// instantiateStreaming takes a Promise<Response> and optional importObject
// It compiles and instantiates concurrently with the download
const result = await WebAssembly.instantiateStreaming(
  fetch("/wasm/functions.wasm"), // => fetch returns Promise<Response>
  // => compilation begins as bytes arrive
  {}, // => importObject: no imports for this module
);
// => result is { module: WebAssembly.Module, instance: WebAssembly.Instance }
 
const { module, instance } = result; // => destructure result
// => module: reusable, serializable compiled module
// => instance: the running instance with exports
 
// Access exported functions
const add = instance.exports.add; // => function reference (callable from JS)
console.log(add(3, 4)); // => 7  (calls Wasm add function)
console.log(add(100, 200)); // => 300
 
// Content-Type requirement: server MUST serve .wasm as application/wasm
// Chrome/Firefox enforce this; some CDNs default to application/octet-stream
// Nginx: add_type application/wasm .wasm;
// Express: res.set('Content-Type', 'application/wasm'); res.sendFile(...);

// fallback-instantiate.js — non-streaming fallback for Node.js / older environments
 
async function loadWasm(url, importObject = {}) {
  // Check if streaming compilation is available
  if (WebAssembly.instantiateStreaming) {
    // => feature check
    return WebAssembly.instantiateStreaming(
      // => use streaming if available
      fetch(url),
      importObject,
    );
  }
 
  // Fallback: fetch full binary into memory first
  const response = await fetch(url); // => awaits full HTTP response
  const buffer = await response.arrayBuffer(); // => reads body into ArrayBuffer
  // => entire binary in memory at this point
 
  // Compile from buffer (not streaming)
  return WebAssembly.instantiate(buffer, importObject); // => compiles from ArrayBuffer
  // => returns { module, instance }
}
 
// In Node.js 18+ with built-in fetch
const { instance } = await loadWasm("./functions.wasm");
console.log(instance.exports.add(5, 6)); // => 11
 
// In Node.js 16 and earlier: use node-fetch or fs.readFile
import { readFile } from "fs/promises";
const buffer = await readFile("./functions.wasm"); // => reads from filesystem
const { instance: inst2 } = await WebAssembly.instantiate(buffer, {});
console.log(inst2.exports.add(7, 8)); // => 15

// exported-calls.js — calling exported Wasm functions
 
const { instance } = await WebAssembly.instantiateStreaming(fetch("/wasm/functions.wasm"));
const exports = instance.exports; // => exports object: { add: Function, square: Function, ... }
 
// Calling i32-returning functions: result is a JS Number
const sum = exports.add(10, 20); // => calls Wasm $add(10, 20)
// => returns 30 as JS Number (i32 → Number)
console.log(sum); // => 30
console.log(typeof sum); // => "number"
 
// Calling with out-of-range values: i32 truncates
const overflow = exports.add(
  2147483647, // => i32 max value (2^31 - 1)
  1, // => adding 1 causes overflow
);
console.log(overflow); // => -2147483648 (wraps around in two's complement)
// => IMPORTANT: Wasm i32 arithmetic wraps silently
 
// Exported memory (if module exports memory)
const memory = exports.memory; // => WebAssembly.Memory object (if exported)
const view = new Int32Array(memory.buffer); // => typed view over raw bytes
 
// Exported globals (if module exports a global)
// const globalVal = exports.myGlobal.value;  // => WebAssembly.Global.value
 
// BigInt for i64 functions
// const bigResult = exports.get_i64(); // => 9007199254740993n (BigInt suffix n)
// console.log(typeof bigResult);        // => "bigint"

;; imports.wat — importing a JavaScript function into Wasm
(module
  ;; Import declaration: module "env", function "log_i32"
  (import "env" "log_i32"              ;; => host must provide { env: { log_i32: fn } }
    (func $log_i32 (param i32))        ;; => imported function signature: takes one i32
  )
 
  ;; Use the imported function inside a Wasm function
  (func $demo (export "demo")          ;; => export "demo" directly inline
    i32.const 42                       ;; => push 42
    call $log_i32                      ;; => calls JS log_i32(42)
                                        ;; => JS side prints to console
    i32.const 100                      ;; => push 100
    call $log_i32                      ;; => calls JS log_i32(100)
  )
)

// Host-side import object providing the imported functions
const importObject = {
  env: {
    // => matches "env" namespace in WAT import
    log_i32: (value) => {
      // => matches "log_i32" function name
      console.log("Wasm says:", value); // => called when Wasm calls $log_i32
    },
  },
};
 
const { instance } = await WebAssembly.instantiateStreaming(
  fetch("/wasm/imports.wasm"),
  importObject, // => imports must match declarations exactly
);
 
instance.exports.demo();
// => Output: Wasm says: 42
// => Output: Wasm says: 100

// module-lifecycle.js — Module vs Instance lifecycle
 
// Step 1: Compile the module (expensive, stateless result)
const response = await fetch("/wasm/functions.wasm");
const buffer = await response.arrayBuffer(); // => full binary in memory
const module = await WebAssembly.compile(buffer); // => compilation (CPU-intensive)
// => module: WebAssembly.Module
// => stateless: no memory, no globals
 
// Step 2: Instantiate multiple times from the same module (cheap)
const instance1 = await WebAssembly.instantiate(module, {}); // => fresh state
const instance2 = await WebAssembly.instantiate(module, {}); // => separate state
// => each instance has own memory
 
// Verify instances are independent
instance1.exports.add(1, 2); // => operates on instance1's state (if stateful)
instance2.exports.add(3, 4); // => operates on instance2's state (independent)
 
// Modules are serializable and transferable between workers
const worker = new Worker("worker.js");
worker.postMessage(module, []); // => transfer module to worker (zero-copy)
// => worker can instantiate its own instance
 
// Module caching: store compiled module in IndexedDB or Cache API
// const cache = await caches.open('wasm-cache');
// cache.put('/wasm/functions.wasm', new Response(buffer));  // raw bytes
// Or serialize module: const moduleBytes = WebAssembly.Module.serialize(module);

// precompile.js — pre-compile at startup, instantiate on demand
 
// Pre-compile during app initialization (not on critical path)
let compiledModule = null;
 
async function precompile() {
  const buffer = await fetch("/wasm/functions.wasm").then((r) => r.arrayBuffer()); // => download binary
  compiledModule = await WebAssembly.compile(buffer); // => compile asynchronously
  // => compiledModule is WebAssembly.Module
  console.log("Wasm pre-compiled"); // => log when ready
}
 
// Instantiate on-demand (fast, module already compiled)
async function getInstance() {
  if (!compiledModule) {
    await precompile(); // => ensure compiled if not yet done
  }
  return WebAssembly.instantiate(compiledModule, {}); // => cheap instantiation
}
 
// Usage pattern: pre-compile in background, use later
precompile(); // => start compilation (no await — fire and forget)
 
// Later, when user action triggers Wasm usage:
const instance = await getInstance(); // => if pre-compilation finished: fast
// => if not yet done: waits for compile
console.log(instance.exports.add(1, 2)); // => 3

// validate.js — validate a .wasm binary without compiling it
 
// Valid Wasm binary: must start with magic \0asm and version \1\0\0\0
const validWasm = new Uint8Array([
  0x00,
  0x61,
  0x73,
  0x6d, // => \0asm magic header (4 bytes)
  0x01,
  0x00,
  0x00,
  0x00, // => version 1 (4 bytes)
]); // => empty module: 8 bytes total
 
const isValid = WebAssembly.validate(validWasm); // => synchronous check
console.log(isValid); // => true (valid empty module)
 
// Invalid binary: wrong magic
const invalidWasm = new Uint8Array([0xff, 0x00, 0x00, 0x00]);
console.log(WebAssembly.validate(invalidWasm)); // => false
 
// Invalid binary: truncated
const truncated = new Uint8Array([0x00, 0x61, 0x73]); // => magic incomplete
console.log(WebAssembly.validate(truncated)); // => false
 
// Use in a build pipeline test
async function verifyWasmBuild(url) {
  const buffer = await fetch(url).then((r) => r.arrayBuffer());
  if (!WebAssembly.validate(buffer)) {
    // => validate before deploying
    throw new Error(`Invalid Wasm binary at ${url}`);
  }
  console.log(`${url}: valid Wasm module`); // => passes validation
}

// feature-detect.js — detect Wasm features at runtime
// npm install wasm-feature-detect
import {
  simd, // => detects fixed 128-bit SIMD (universally available: Chrome 91+, Firefox 89+, Safari 16.4+)
  threads, // => detects shared memory + atomic operations (requires COOP/COEP headers)
  gc, // => detects WasmGC (Baseline Dec 11, 2024: Chrome 119+, Firefox 120+, Safari 18.2+)
  relaxedSimd, // => detects Relaxed SIMD (Chrome/Firefox/Edge shipped; Safari: behind flag as of 2026)
  memory64, // => detects Memory64 (Chrome/Firefox/Edge shipped; Safari: lagging)
  tailCall, // => detects tail call optimization (Baseline Dec 11, 2024)
  exceptions, // => detects exception handling (Wasm 3.0)
} from "wasm-feature-detect";
 
// Detect individual features (all return Promise<boolean>)
const hasSimd = await simd(); // => true on Chrome 91+, Firefox 89+, Safari 16.4+
const hasThreads = await threads(); // => true only if COOP/COEP headers present
const hasGc = await gc(); // => true on Chrome 119+, Firefox 120+, Safari 18.2+
const hasRelaxedSimd = await relaxedSimd(); // => true Chrome/Firefox; false Safari (2026)
const hasMemory64 = await memory64(); // => true Chrome/Firefox/Edge; false Safari
 
console.log({ hasSimd, hasThreads, hasGc, hasRelaxedSimd, hasMemory64 });
 
// Load optimized vs compatible build based on features
async function loadBestModule() {
  if ((await simd()) && (await threads())) {
    return import("./wasm-simd-threads.js"); // => best performance build
  } else if (await simd()) {
    return import("./wasm-simd.js"); // => SIMD-only build
  } else {
    return import("./wasm-baseline.js"); // => universally compatible fallback
  }
}

;; memory.wat — declaring and using linear memory
(module
  ;; Declare memory: 1 initial page (64 KiB), max 10 pages (640 KiB)
  (memory $mem 1 10)                 ;; => 1 page = 65536 bytes initially
                                      ;; => max 10 pages = 655360 bytes
                                      ;; => memory is zero-initialized
 
  ;; Export memory so JavaScript can read/write it directly
  (export "memory" (memory $mem))    ;; => JS gets a WebAssembly.Memory object
 
  ;; Store a value into memory at byte offset 0
  (func $store_at_0 (param $val i32)
    i32.const 0                      ;; => push address: byte offset 0
    local.get $val                   ;; => push value to store
    i32.store                        ;; => store i32 at address 0 (little-endian)
                                      ;; => writes 4 bytes at offsets 0,1,2,3
  )
  (export "storeAt0" (func $store_at_0))
 
  ;; Load a value from memory at byte offset 0
  (func $load_at_0 (result i32)
    i32.const 0                      ;; => push address: byte offset 0
    i32.load                         ;; => load i32 from address 0 (little-endian)
                                      ;; => pops address, pushes 4-byte value
  )
  (export "loadAt0" (func $load_at_0))
 
  ;; Query current memory size (in pages)
  (func $page_count (result i32)
    memory.size                      ;; => pushes current page count as i32
  )
  (export "pageCount" (func $page_count))
)

// memory-constructor.js — creating WebAssembly.Memory in JavaScript
 
// Create non-shared memory: 2 pages initial (128 KiB), max 10 pages (640 KiB)
const memory = new WebAssembly.Memory({
  initial: 2, // => 2 * 65536 = 131072 bytes initially
  maximum: 10, // => max 10 * 65536 = 655360 bytes
  // shared: false   // => default: not shared (can't use with workers + SharedArrayBuffer)
});
 
console.log(memory.buffer.byteLength); // => 131072 (2 pages)
console.log(memory.buffer instanceof ArrayBuffer); // => true (standard ArrayBuffer)
 
// Pre-populate memory before passing to Wasm
const view = new Uint8Array(memory.buffer);
view[0] = 42; // => write byte 42 at offset 0
view[1] = 100; // => write byte 100 at offset 1
 
// Pass memory as an import to the Wasm module
const importObject = {
  env: {
    memory: memory, // => key must match the WAT import name
  },
};
const { instance } = await WebAssembly.instantiateStreaming(
  fetch("/wasm/memory.wasm"),
  importObject, // => module uses this memory instead of declaring its own
);
 
// Shared memory for use with Web Workers (requires COOP/COEP headers)
const sharedMemory = new WebAssembly.Memory({
  initial: 1,
  maximum: 4,
  shared: true, // => backs with SharedArrayBuffer instead of ArrayBuffer
});
console.log(sharedMemory.buffer instanceof SharedArrayBuffer); // => true

// memory-access.js — reading/writing Wasm memory from JavaScript
 
const { instance } = await WebAssembly.instantiateStreaming(fetch("/wasm/memory.wasm"));
 
const memory = instance.exports.memory; // => WebAssembly.Memory exported from module
 
// Create typed views over the same ArrayBuffer
const bytes = new Uint8Array(memory.buffer); // => byte-level view
const shorts = new Int16Array(memory.buffer); // => 16-bit signed view
const ints = new Int32Array(memory.buffer); // => 32-bit signed view
const floats = new Float64Array(memory.buffer); // => 64-bit float view
 
// Write an i32 to offset 0 using Int32Array (index 0 = byte offset 0)
ints[0] = 12345; // => writes 4 bytes at offsets 0-3
// => little-endian: [0x39, 0x30, 0x00, 0x00]
 
// Verify from Wasm (if module has loadAt0)
console.log(instance.exports.loadAt0()); // => 12345 (Wasm reads same bytes)
 
// Write using byte view (precise control)
bytes[4] = 0xff; // => sets byte at offset 4
bytes[5] = 0x00; // => sets byte at offset 5
bytes[6] = 0x00; // => sets byte at offset 6
bytes[7] = 0x00; // => sets byte at offset 7
// => ints[1] is now 0x000000FF = 255
 
// IMPORTANT: After memory.grow(), existing views become detached!
// Always re-create typed array views after growth
memory.grow(1); // => grows memory by 1 page (adds 64 KiB)
// ints is now DETACHED: ints[0] throws TypeError
const ints2 = new Int32Array(memory.buffer); // => create new view after grow
console.log(ints2[0]); // => 12345 (data preserved after growth)

;; memory-grow.wat — memory.grow instruction in WAT
(module
  (memory (export "memory") 1 8)   ;; => 1 page initial, 8 pages max
 
  ;; Grow memory by n pages, return old size (or -1 if out of max)
  (func $grow_by (param $n i32) (result i32)
    local.get $n                   ;; => push number of pages to grow
    memory.grow                    ;; => pops n, grows by n pages
                                    ;; => pushes old page count (or -1 on failure)
  )
  (export "growBy" (func $grow_by))
 
  ;; Return current memory size in pages
  (func $size (result i32)
    memory.size                    ;; => pushes current page count
  )
  (export "size" (func $size))
)

// memory-grow.js — growing memory from JavaScript
const { instance } = await WebAssembly.instantiateStreaming(fetch("/wasm/memory-grow.wasm"));
 
const mem = instance.exports;
 
console.log(mem.size()); // => 1 (initial: 1 page = 64 KiB)
 
const oldSize = mem.growBy(2); // => grows by 2 pages (returns old size)
console.log(oldSize); // => 1 (previous page count)
console.log(mem.size()); // => 3 (now 3 pages = 192 KiB)
 
// Also grow from JavaScript directly
const mem2 = instance.exports.memory;
const beforeGrow = mem2.grow(1); // => grows by 1 page, returns old count
console.log(beforeGrow); // => 3 (old page count)
console.log(mem2.buffer.byteLength); // => 262144 (4 pages * 65536)
 
// Try to exceed max (8 pages): growth fails
const result = mem.growBy(10); // => requesting 10 more pages (total would be 14)
console.log(result); // => -1 (failure: exceeds max of 8 pages)
console.log(mem.size()); // => 4 (unchanged after failed grow)

;; pointer-length.wat — pointer+length convention for byte arrays
(module
  (memory (export "memory") 1)     ;; => 1 page = 65536 bytes
 
  ;; Copy n bytes from src pointer to dst pointer
  (func $copy_bytes
    (param $dst i32)               ;; => destination byte offset
    (param $src i32)               ;; => source byte offset
    (param $n i32)                 ;; => number of bytes to copy
    (local $i i32)                 ;; => loop index
    i32.const 0
    local.set $i                   ;; => $i = 0
 
    block $done
      loop $loop
        local.get $i               ;; => push $i
        local.get $n               ;; => push $n
        i32.ge_u                   ;; => $i >= $n? (unsigned comparison)
        br_if $done                ;; => exit loop if done
 
        local.get $dst             ;; => push $dst
        local.get $i               ;; => push $i
        i32.add                    ;; => dst + i (destination address)
 
        local.get $src             ;; => push $src
        local.get $i               ;; => push $i
        i32.add                    ;; => src + i (source address)
        i32.load8_u                ;; => load 1 byte from source (unsigned)
 
        i32.store8                 ;; => store 1 byte to destination
 
        local.get $i               ;; => push $i
        i32.const 1                ;; => push 1
        i32.add                    ;; => $i + 1
        local.set $i               ;; => $i = $i + 1
        br $loop                   ;; => next iteration
      end
    end
  )
  (export "copyBytes" (func $copy_bytes))
)

// string-encoding.js — UTF-8 string round-trip through Wasm memory
 
const { instance } = await WebAssembly.instantiateStreaming(fetch("/wasm/memory.wasm"));
 
const memory = instance.exports.memory;
const encoder = new TextEncoder(); // => encodes JS strings to UTF-8 bytes
const decoder = new TextDecoder(); // => decodes UTF-8 bytes to JS strings
 
// Write a JS string into Wasm memory at offset 1000
function writeString(str, offset) {
  const bytes = encoder.encode(str); // => UTF-8 byte array (Uint8Array)
  // => "Hello, Wasm!" => [72, 101, 108, 108, ...]
  const view = new Uint8Array(memory.buffer);
  view.set(bytes, offset); // => copy bytes into Wasm memory at offset
  return bytes.length; // => return byte length (not character count!)
  // => "café" = 5 bytes (é is 2 bytes in UTF-8)
}
 
// Read a UTF-8 string from Wasm memory at offset/length
function readString(offset, length) {
  const view = new Uint8Array(memory.buffer);
  const bytes = view.subarray(offset, offset + length); // => slice (no copy)
  return decoder.decode(bytes); // => decodes UTF-8 → JS string
}
 
// Round-trip example
const str = "Hello, WebAssembly! 🦀"; // => contains non-ASCII (emoji = 4 bytes)
const offset = 1000; // => arbitrary memory location
const byteLen = writeString(str, offset);
 
console.log(byteLen); // => 24 (bytes, not characters; emoji = 4 bytes)
console.log(str.length); // => 21 (JS string length = code units)
 
const decoded = readString(offset, byteLen);
console.log(decoded === str); // => true (round-trip preserves string)

;; module-a.wat — declares and exports its own memory
(module
  (memory (export "memory") 1 4)   ;; => declares memory, exports it
  (func (export "storeValue")
    (param $addr i32) (param $val i32)
    local.get $addr                ;; => push address
    local.get $val                 ;; => push value
    i32.store                      ;; => store 4 bytes at addr
  )
)

;; module-b.wat — imports memory from host instead of declaring its own
(module
  ;; Import memory from host under namespace "env"
  (import "env" "memory" (memory 1)) ;; => expects at least 1 page from host
                                       ;; => host must provide this memory
 
  (func (export "readValue")
    (param $addr i32) (result i32)
    local.get $addr                ;; => push address
    i32.load                       ;; => load 4 bytes from (host-provided) memory
  )
)

// share-memory.js — sharing one Memory between two modules
 
const sharedMem = new WebAssembly.Memory({ initial: 1, maximum: 4 });
 
// Instantiate module-a (it declares its own memory — different from sharedMem)
// Instantiate module-b with the shared memory
const { instance: b } = await WebAssembly.instantiateStreaming(
  fetch("/wasm/module-b.wasm"),
  { env: { memory: sharedMem } }, // => pass shared memory as import
);
 
// Write to shared memory from JS
new Int32Array(sharedMem.buffer)[10] = 999; // => write 999 at byte offset 40
 
// Read from shared memory via module-b
console.log(b.exports.readValue(40)); // => 999 (same backing buffer)

# Initialize a new AssemblyScript project
mkdir as-project && cd as-project
npm init -y                           # => creates package.json
 
# Install AssemblyScript compiler (developer tool)
npm install --save-dev assemblyscript # => installs asc (AssemblyScript compiler) + loader
                                       # => version: 0.28.x
 
# Initialize AS project structure
npx asinit .                          # => creates:
                                       # => assembly/index.ts — entry point
                                       # => asconfig.json    — compiler config
                                       # => build/           — output directory
 
# Verify asc is installed
npx asc --version                     # => AssemblyScript v0.28.x
 
# Project structure created by asinit:
# as-project/
# ├── assembly/
# │   └── index.ts    ← write AssemblyScript here (NOT TypeScript!)
# ├── build/
# │   ├── release.wasm  ← optimized output
# │   └── debug.wasm    ← debug output
# ├── asconfig.json    ← compiler config
# └── package.json

// asconfig.json — AssemblyScript compiler configuration
{
  "targets": {
    "debug": {
      "sourceMap": true,
      "debug": true
    },
    "release": {
      "optimizeLevel": 3,
      "shrinkLevel": 1,
      "sourceMap": false
    }
  }
}

// assembly/index.ts — AssemblyScript typed functions
// NOTE: This is AssemblyScript (.ts syntax), NOT TypeScript
// File lives in assembly/ directory, compiled with asc (not tsc)
 
// Basic arithmetic: explicit i32 types required (no number type)
export function add(a: i32, b: i32): i32 {
  return a + b; // => i32 addition (wraps on overflow, no exception)
  // => compiled to: local.get 0; local.get 1; i32.add
}
 
// Float64 function: TypeScript's 'number' is not valid here — must be f64
export function sqrt(x: f64): f64 {
  return Math.sqrt(x); // => AS Math.sqrt operates on f64
  // => compiled to: local.get 0; f64.sqrt
}
 
// Boolean return type maps to i32 in Wasm (0 = false, 1 = true)
export function isEven(n: i32): bool {
  return (n & 1) === 0; // => bitwise AND with 1: 0 means even
  // => bool compiles to i32 (0 or 1)
}
 
// u32: unsigned 32-bit integer (no C-style unsigned int keyword needed)
export function countBits(n: u32): i32 {
  let count: i32 = 0; // => local variable with explicit type
  for (let i: u32 = 0; i < 32; i++) {
    if (n & (1 << i)) {
      // => check bit i
      count++; // => count set bits
    }
  }
  return count; // => popcount result
}

# Compile AssemblyScript to Wasm
npx asc assembly/index.ts --target release --outFile build/release.wasm
# => reads assembly/index.ts
# => optimizes (level 3)
# => writes build/release.wasm
 
# Also produce WAT for inspection
npx asc assembly/index.ts --target debug --textFile build/debug.wat
# => builds debug binary + produces human-readable WAT

# Compile to release .wasm
npx asc assembly/index.ts --target release --outFile build/release.wasm
# => builds optimized Wasm
# => exports: add, sqrt, isEven, countBits
 
# Inspect what was exported
wasm-objdump -x build/release.wasm | grep Export
# => Export[4]:
# =>  - func[0] -> "add"
# =>  - func[1] -> "sqrt"
# =>  - func[2] -> "isEven"
# =>  - func[3] -> "countBits"

// load-as.js — loading AssemblyScript .wasm in the browser
 
// Method 1: Raw WebAssembly API (works for numeric-only modules)
const { instance } = await WebAssembly.instantiateStreaming(
  fetch("/build/release.wasm"),
  {}, // => no imports needed for these functions
);
 
const { add, sqrt, isEven, countBits } = instance.exports;
 
console.log(add(10, 20)); // => 30
console.log(sqrt(2.0)); // => 1.4142135623730951
console.log(isEven(42)); // => 1 (true: 1 in Wasm, not JS boolean)
console.log(isEven(7)); // => 0 (false)
console.log(countBits(255)); // => 8 (all 8 bits set in 0xFF)
 
// Method 2: @assemblyscript/loader (adds string/array helpers)
// npm install @assemblyscript/loader
import { instantiate } from "@assemblyscript/loader";
 
const wasmModule = await instantiate(
  fetch("/build/release.wasm"), // => accepts Promise<Response> or ArrayBuffer
  {}, // => import object
);
// wasmModule.exports has same functions PLUS loader helpers (__newString, __getString, etc.)
console.log(wasmModule.exports.add(3, 4)); // => 7

// assembly/memory.ts — AssemblyScript memory access
// Compile: npx asc assembly/memory.ts --outFile build/memory.wasm
 
// Store a 32-bit integer at a byte offset
export function storeInt(offset: i32, value: i32): void {
  store<i32>(offset, value); // => writes 4 bytes at byte offset
  // => same as i32.store in WAT
}
 
// Load a 32-bit integer from a byte offset
export function loadInt(offset: i32): i32 {
  return load<i32>(offset); // => reads 4 bytes from byte offset
  // => same as i32.load in WAT
}
 
// Store an f64 at a byte offset (8 bytes)
export function storeFloat(offset: i32, value: f64): void {
  store<f64>(offset, value); // => writes 8 bytes at byte offset
}
 
// Load an f64 from a byte offset
export function loadFloat(offset: i32): f64 {
  return load<f64>(offset); // => reads 8 bytes from byte offset
}
 
// Query current memory size (in pages, each 65536 bytes)
export function getPageCount(): i32 {
  return memory.size(); // => returns current page count
  // => same as memory.size in WAT
}
 
// Grow memory by n pages (returns old page count or -1)
export function growMemory(pages: i32): i32 {
  return memory.grow(pages); // => grows by pages, returns old count
}
 
// Fill memory region with zeros (memset pattern)
export function zeroMemory(start: i32, length: i32): void {
  memory.fill(start, 0, length); // => memset to 0
  // => compiled to memory.fill instruction (Wasm bulk memory)
}

// assembly/arrays.ts — StaticArray vs Array in AssemblyScript
// Compile: npx asc assembly/arrays.ts --outFile build/arrays.wasm
 
// StaticArray<T>: fixed size at declaration, no GC overhead
// Suitable for fixed-size buffers: lookup tables, fixed-size scratch space
export function sumStaticArray(): i32 {
  const arr = new StaticArray<i32>(5); // => allocates 5 * 4 = 20 bytes in data segment
  // => no GC tracking for this array
  arr[0] = 10; // => direct store at offset 0
  arr[1] = 20; // => direct store at offset 4
  arr[2] = 30; // => direct store at offset 8
  arr[3] = 40; // => direct store at offset 12
  arr[4] = 50; // => direct store at offset 16
 
  let sum: i32 = 0;
  for (let i = 0; i < arr.length; i++) {
    sum += arr[i]; // => direct load from offset i*4
  }
  return sum; // => 150
}
 
// Array<T>: heap-allocated, GC-managed, resizable
// Use @assemblyscript/loader on JS side to handle GC-managed arrays
export function createArray(len: i32): Array<i32> {
  const arr = new Array<i32>(len); // => allocates on GC heap
  for (let i = 0; i < len; i++) {
    arr[i] = i * i; // => fill with squares
  }
  return arr; // => returns pointer to GC-managed array object
  // => JS must use loader.__getArray(ptr) to read values
}
 
// Efficient pattern: accept pre-allocated pointer from JS host
// (avoids GC allocation entirely for hot paths)
export function fillSquares(ptr: i32, len: i32): void {
  for (let i = 0; i < len; i++) {
    store<i32>(ptr + i * 4, i * i); // => store squares at ptr+offset
  }
}

// array-usage.js — loading and using AssemblyScript arrays
import { instantiate } from "@assemblyscript/loader";
 
const module = await instantiate(fetch("/build/arrays.wasm"), {});
 
// StaticArray result (simple numeric return)
console.log(module.exports.sumStaticArray()); // => 150
 
// GC-managed Array<i32>: use loader to extract
const ptr = module.exports.createArray(5); // => returns pointer into Wasm heap
const arr = module.exports.__getArray(ptr); // => loader reads GC array → JS array
console.log(arr); // => [0, 1, 4, 9, 16]
 
// Zero-copy pattern: pre-allocate in JS, pass pointer to Wasm
const mem = new Int32Array(module.exports.memory.buffer, 1000, 5);
module.exports.fillSquares(1000, 5); // => Wasm writes at offset 1000
console.log([...mem]); // => [0, 1, 4, 9, 16]