wit-parser 0.0.1-preview.1

A WIT (WebAssembly Interface Types) parser, resolver and component encoder

Readme Files Dependencies Versions

wit-parser#

A WebAssembly Interface Types (WIT) parser, semantic resolver, .wit.json serializer, and component type encoder for Zena.

Installation#

zena pkg add zena-lang:wit-parser

Example#

import { parse } from 'zena-lang:wit-parser';
import { AstItemTag } from 'zena-lang:wit-parser/parser';

let source = `
package example:greeter@1.0.0;

interface greet {
  record greeting { text: string, formal: bool }
  hello: func(name: string) -> greeting;
}

interface farewell {
  use greet.{greeting};
  goodbye: func(name: string) -> greeting;
}

world greeter {
  export greet;
  export farewell;
}
`;

// Parses syntax and resolves names and cross-interface `use` references.
// Throws `ParseError` or `ResolveError` if the document is invalid.
let doc = parse(source);

var interfaces = 0;
var worlds = 0;
for (let item in doc.items) {
  if (item.tag == AstItemTag.Interface) {
    interfaces += 1;
  } else if (item.tag == AstItemTag.World) {
    worlds += 1;
  }
}

Libraries#

zena-lang:wit-parser#

The primary entry point for parsing, resolving, and serializing WIT source text.

Function Description
parse(source) Parses and resolves source into a validated Ast. Throws ParseError or ResolveError.
parseSyntax(source) Parses source without resolving names, for single-file syntax tooling such as formatters.
resolve(ast) Resolves names and validates an Ast in place.
toJson(ast, packageOrder?) Serializes a resolved Ast to the .wit.json format emitted by wasm-tools component wit --json.

zena-lang:wit-parser also re-exports Ast, ParseError, and ResolveError. Both error types carry a Span with byte offsets into the source text.

zena-lang:wit-parser/parser#

The AST node declarations (Ast, AstItem, AstItemTag, InterfaceDef, WorldDef, TypeDef, Type, NamedFunc, ResourceFunc, Use, Include, Docs, Attribute, PackageName, NestedPackage, and related types) and Parser.

zena-lang:wit-parser/document#

Utilities for assembling multi-file WIT directories into a single source document while tracking file boundaries for error reporting:

  • WitFile(name, source) and joinWitDocument(files): concatenates .wit files in canonical name order and records where each file starts.
  • WitDocument.locate(offset): maps a byte offset back to a WitLocation (file, 1-based line, 1-based column).
  • witDiagnostic(doc, error): formats a LexError, ParseError, or ResolveError with its filename, line, column, source line, and caret underline.
  • findInterface(ast, namespace, interfacePath): looks up an interface (pkg/iface) in a parsed document.

zena-lang:wit-parser/component-encoder#

Encodes a resolved WIT world into WebAssembly Component Model binary type and import sections:

  • encodeTypesOnlyComponent(ast, worldName): encodes the named world as a standalone types-only component binary.
  • ComponentTypeEncoder: emits component type, alias, import, and export sections and canonical ABI metadata (WitFuncMeta, WitFlatMeta).
  • expandedWorldItems(ast, world) and worldNames(ast): expands world includes and transitive use dependencies.

zena-lang:wit-parser/lexer and zena-lang:wit-parser/token#

Low-level tokenization: Lexer, LexError, Token, TokenType, and Span.

zena-lang:wit-parser/resolver#

Semantic validation and name resolution: Resolver and ResolveError.

3.7 KiB Rendered Raw
# wit-parser

A WebAssembly Interface Types (WIT) parser, semantic resolver, `.wit.json`
serializer, and component type encoder for Zena.

## Installation

```bash
zena pkg add zena-lang:wit-parser
```

## Example

```zena
import { parse } from 'zena-lang:wit-parser';
import { AstItemTag } from 'zena-lang:wit-parser/parser';

let source = `
package example:greeter@1.0.0;

interface greet {
  record greeting { text: string, formal: bool }
  hello: func(name: string) -> greeting;
}

interface farewell {
  use greet.{greeting};
  goodbye: func(name: string) -> greeting;
}

world greeter {
  export greet;
  export farewell;
}
`;

// Parses syntax and resolves names and cross-interface `use` references.
// Throws `ParseError` or `ResolveError` if the document is invalid.
let doc = parse(source);

var interfaces = 0;
var worlds = 0;
for (let item in doc.items) {
  if (item.tag == AstItemTag.Interface) {
    interfaces += 1;
  } else if (item.tag == AstItemTag.World) {
    worlds += 1;
  }
}
```

## Libraries

### `zena-lang:wit-parser`

The primary entry point for parsing, resolving, and serializing WIT source text.

| Function                     | Description                                                                                         |
| ---------------------------- | --------------------------------------------------------------------------------------------------- |
| `parse(source)`              | Parses and resolves `source` into a validated `Ast`. Throws `ParseError` or `ResolveError`.         |
| `parseSyntax(source)`        | Parses `source` without resolving names, for single-file syntax tooling such as formatters.         |
| `resolve(ast)`               | Resolves names and validates an `Ast` in place.                                                     |
| `toJson(ast, packageOrder?)` | Serializes a resolved `Ast` to the `.wit.json` format emitted by `wasm-tools component wit --json`. |

`zena-lang:wit-parser` also re-exports `Ast`, `ParseError`, and `ResolveError`. Both
error types carry a `Span` with byte offsets into the source text.

### `zena-lang:wit-parser/parser`

The AST node declarations (`Ast`, `AstItem`, `AstItemTag`, `InterfaceDef`,
`WorldDef`, `TypeDef`, `Type`, `NamedFunc`, `ResourceFunc`, `Use`, `Include`,
`Docs`, `Attribute`, `PackageName`, `NestedPackage`, and related types) and
`Parser`.

### `zena-lang:wit-parser/document`

Utilities for assembling multi-file WIT directories into a single source
document while tracking file boundaries for error reporting:

- `WitFile(name, source)` and `joinWitDocument(files)`: concatenates `.wit`
  files in canonical name order and records where each file starts.
- `WitDocument.locate(offset)`: maps a byte offset back to a `WitLocation`
  (`file`, 1-based `line`, 1-based `column`).
- `witDiagnostic(doc, error)`: formats a `LexError`, `ParseError`, or
  `ResolveError` with its filename, line, column, source line, and caret
  underline.
- `findInterface(ast, namespace, interfacePath)`: looks up an interface (`pkg/iface`)
  in a parsed document.

### `zena-lang:wit-parser/component-encoder`

Encodes a resolved WIT world into WebAssembly Component Model binary type and
import sections:

- `encodeTypesOnlyComponent(ast, worldName)`: encodes the named world as a
  standalone types-only component binary.
- `ComponentTypeEncoder`: emits component type, alias, import, and export
  sections and canonical ABI metadata (`WitFuncMeta`, `WitFlatMeta`).
- `expandedWorldItems(ast, world)` and `worldNames(ast)`: expands world
  `include`s and transitive `use` dependencies.

### `zena-lang:wit-parser/lexer` and `zena-lang:wit-parser/token`

Low-level tokenization: `Lexer`, `LexError`, `Token`, `TokenType`, and `Span`.

### `zena-lang:wit-parser/resolver`

Semantic validation and name resolution: `Resolver` and `ResolveError`.
none
VersionPublishedDependenciesApproved by
0.0.1-preview.1 2026-11-19 none