wit-parser 0.0.1-preview.1
A WIT (WebAssembly Interface Types) parser, resolver and component encoder
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)andjoinWitDocument(files): concatenates.witfiles in canonical name order and records where each file starts.WitDocument.locate(offset): maps a byte offset back to aWitLocation(file, 1-basedline, 1-basedcolumn).witDiagnostic(doc, error): formats aLexError,ParseError, orResolveErrorwith 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)andworldNames(ast): expands worldincludes and transitiveusedependencies.
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.
# 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`.
| Version | Published | Dependencies | Approved by |
|---|---|---|---|
| 0.0.1-preview.1 | 2026-11-19 | none |
|