# WIT Cheatsheet

## Keywords

### Structural Keywords
| Identifier | Description |
|----------------------------|-------------|
|`world` | component type definition, collection of imports and exports |
|`package` | defines namespace and version |
|`interface` | name and sequence of items and functions |

### Language Keywords

| Identifier | Description |
|----------------------------|-------------|
|`include` | |
|`import` | define imports for a world |
|`export` | define an export for a world |
|`use` | allows types to be used in a world |
|`static` | denote an function as static |
|`self` | ??? |
|`borrow` | ??? |

### Primitive types

| Identifier | Description |
|----------------------------|-------------|
| `bool` | Boolean value - true or false. |
| `s8`, `s16`, `s32`, `s64` | Signed integers of the appropriate width. For example, `s32` is a 32-bit integer. |
| `u8`, `u16`, `u32`, `u64` | Unsigned integers of the appropriate width. For example, `u32` is a 32-bit integer. |
| `float32`, `float64` | Floating-point numbers of the appropriate width. For example, `float64` is a 64-bit (double precision) floating-point number. |
| `char` | Unicode character. (Specifically, a [Unicode scalar value](https://unicode.org/glossary/#unicode_scalar_value).) |
| `string` | A Unicode string - that is, a finite sequence of characters. |

### Named Types

| Identifier | Description |
|----------------------------|-------------|
| `func` | ??? |
| `record` | ??? |
| `enum` | ??? |
| `variant` | ??? |
| `flags` | ??? |
| `resource` | ??? |

### Container Types

| Identifier | Description |
|----------------------------|-------------|
| `tuple` | ??? |
| `list` | ??? |
| `option` | ??? |
| `result` | ??? |

:::info
**Identifier Naming**: Identifiers are restricted to ASCII `kebab-case` but can be preceded by a single `%` if the identifier would otherwise be a WIT keyword. For example, `interface` is a keyword, but `%interface` is an identifier.
:::

## WASI Interface

- `wasi:cli/command`
- `wasi:keyvalue/keyvalue`
- `wasi:blob-store/blob-store`
- `wasi:messaging/messaging`
- `wasi:nn/ml`
- `wasi:cloud-core/cloud-core`

## WASI Component Types

Commands and Reactors are primarily about how you interface with a component.

### Command

A Command has a "main" or in `wasi:cli` a `run` function, and when this function returns the program terminates.

### Reactor

Like a library. Exposes API once instantiated and the program remains live, allowing functions on the component to be called. Event loop is in the wasm runtime vs. the application.

## Snippets

Create a CLI app:

package acme:my-cli

world my-cli {
  include wasi:cli-core@0.2.0
}

Pro-tip: use `use` in a WIT definition with versions to avoid duplication

package acme:local-use-example

use wasi:http/types@1.0.0
use wasi:http/handler@1.0.0

interface my-interface {
  use types.{request, response}
}

world my-world {
  import handler
  export handler
}

Comment

/// Single Line Comment
/* Comment Block */

## Example `.wit` File

package acme:office-manager@0.1.0

interface types {
  type employee-id = u64
 
  variant addresses {
    none,
    list<u32>,
  }

  flags locations {
    main,
    back,
    warehouse
  }

  enum level {
    staff,
    associate,
    partner,
  }
  
  record employee {
    id: employee-id,
    name: string,
    office-access: locations,
    manager: option<employee>,
    reports: option<list<employee>>,
    start-date: u32,
    end-date: option<u32>,
    addresses: addresses,
  }

  record product {
    name: string,
    price: u32,
    description: string,
    stock: u32,
    tags: list<string>,
  }
}

interface directory {
  use types.{employee-id, addresses, locations, employee}
  
  get-employee: func(id: employee-id) -> result<u32, employee>
  update-employee: func(id: employee-id, changes: employee) -> result<u32, employee>
}

world employees {
  import wasi:logging

  export directory.{get-employee, update-employee}
}

world reporting {
    include employees
    use types.{product}

    export get-inventory: func(item: option<string>) -> list<product>
}

# Component Cheatsheet

## Creating a component

Rust

cargo component new demo --reactor
cd demo
cargo component build

JS

npm install @bytecodealliance/jco
npm install @bytecodealliance/componentize-js
npx jco componentize demo.js --wit demo.wit -n demo -o demo.component.wasm

C/C+

wit-bindgen c ./wit
/opt/wasi-sdk/bin/clang demo.c demo_component_type.o demo_gen.c -o demo.wasm -mexec-model=reactor
wasm-tools component new demo.wasm -o demo.component.wasm

Go

go generate
tinygo build -target=wasi gopher.go
wasm-tools print gopher.wasm -o gopher.wat

COMPONENT_ADAPTER=wasi_snapshot_preview1.reactor.wasm
wasm-tools component embed --world critter ./gopher.wit gopher.wasm -o gopher.embed.wasm
wasm-tools component new -o gopher.component.wasm --adapt wasi_snapshot_preview1="$COMPONENT_ADAPTER" gopher.embed.wasm

## Validate any component

wasm-tools validate component.wasm --features component-model 
wasm-tools print component.wasm -o component.wat
wasm-tools component wit component.wasm

## Compose

wasm-tools compose --output linked.wasm app.wasm --config config.yaml
wasm-tools component wit linked.wasm