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.0 KiB Raw
/**
 * The WIT parser's public entry point.
 *
 * Until now the only way in was `parser-test-harness.zena`, whose interface
 * (`parse(): void` plus `getOutputByte(i)`) exists to be driven from a Wasm
 * host one byte at a time. That is a test rig, not an API. This module is the
 * callable surface: a consumer hands over WIT source and gets back a validated
 * AST, or an exception describing what was wrong with it.
 *
 * The AST types themselves live in `parser.zena`, which the package also
 * exports — walking a document means touching most of 87 declarations, so
 * mirroring them here would be a maintenance tax with no benefit. Only the
 * handful needed to call these functions and catch their failures are
 * re-exported below.
 *
 * Names are unqualified because the module already says what they are about —
 * an importer wanting `parseWit` can rename at the import site.
 *
 *     import {parse} from 'zena-lang:wit-parser';
 *     import {AstItemTag} from 'zena-lang:wit-parser/parser';
 *
 *     let doc = parse(source);
 *
 * Errors are thrown rather than returned. `Result<T, E>` is an inline
 * multi-value union (docs/design/result-option.md) but is not in the stdlib
 * yet; once it is, a non-throwing variant can be added alongside these without
 * disturbing callers.
 */
import { Parser, Ast } from './parser.zena';
import { Resolver } from './resolver.zena';
import { serializeAstToJson } from './ast-json.zena';

/**
 * Parse and resolve WIT source into a validated AST.
 *
 * This is what a consumer almost always wants: parsing alone accepts documents
 * that are syntactically fine but meaningless, such as a `use` of an interface
 * that does not exist.
 *
 * Throws `ParseError` for malformed syntax and `ResolveError` for a name or
 * semantic failure. Both carry a `Span` locating the problem.
 */
export function parse(source: String): Ast {
  let ast = Parser.parse(source);
  Resolver.resolve(ast);
  return ast;
}

/**
 * Parse without resolving names.
 *
 * For tooling that wants a syntax tree of a single file in isolation — a
 * formatter, or an editor reparsing on keystroke — where cross-package
 * references cannot be resolved yet and their absence is not an error.
 */
export function parseSyntax(source: String): Ast {
  return Parser.parse(source);
}

/**
 * Resolve an already-parsed AST, validating it in place.
 *
 * Separate from `parseSyntax` so a caller assembling a document from several
 * sources can parse each and resolve once at the end.
 */
export function resolve(ast: Ast): void {
  Resolver.resolve(ast);
}

/**
 * Serialize an AST to the `.wit.json` shape `wasm-tools component wit --json`
 * emits, which is how the test corpus compares against upstream.
 *
 * `packageOrder` optionally fixes the order packages are emitted in; it exists
 * because a concatenated multi-package document has no inherent order.
 */
export function toJson(ast: Ast, packageOrder: String | null = null): String {
  return serializeAstToJson(ast, packageOrder);
}

export { Ast, ParseError } from './parser.zena';
export { ResolveError } from './resolver.zena';
none
VersionPublishedDependenciesApproved by
0.0.1-preview.1 2026-11-19 none