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.

8.2 KiB Raw
/**
 * WIT Lexer Token Types
 *
 * Token definitions for the WIT (WebAssembly Interface Types) lexer.
 * Based on the canonical implementation in wasm-tools:
 * https://github.com/bytecodealliance/wasm-tools/blob/main/crates/wit-parser/src/ast/lex.rs
 */

// ============================================================================
// Token Type Enum
// ============================================================================

/**
 * All possible token types in WIT syntax.
 * 
 * Note: Enum values are auto-assigned starting from 0.
 */
export enum TokenType {
  // Whitespace and comments (usually skipped)
  Whitespace,
  Comment,
  DocComment,  // /// doc comment

  // Punctuation
  Equals,        // =
  Comma,         // ,
  Colon,         // :
  Period,        // .
  Semicolon,     // ;
  LeftParen,     // (
  RightParen,    // )
  LeftBrace,     // {
  RightBrace,    // }
  LessThan,      // <
  GreaterThan,   // >
  RArrow,        // ->
  Star,          // *
  At,            // @
  Slash,         // /
  Plus,          // +
  Minus,         // -

  // Keywords - Types
  U8,
  U16,
  U32,
  U64,
  S8,
  S16,
  S32,
  S64,
  F32,
  F64,
  Char,
  Bool,
  String,

  // Keywords - Composite Types
  Record,
  Flags,
  Variant,
  Enum,
  Option,
  Result,
  List,
  Tuple,
  Future,
  Stream,
  Map,

  // Keywords - Resources
  Resource,
  Own,
  Borrow,
  Constructor,
  Static,

  // Keywords - Declarations
  Type,
  Func,
  Interface,
  World,
  Package,
  Use,
  As,
  From,
  Import,
  Export,
  Include,
  With,
  
  // Keywords - Async
  Async,
  ErrorContext,

  // Special
  Underscore,    // _

  // Identifiers and literals
  Id,            // Regular identifier (e.g., my-func)
  ExplicitId,    // %-prefixed identifier (e.g., %bool)
  Integer,       // Numeric literal

  // End of file
  Eof,
}

// ============================================================================
// Token Structure
// ============================================================================

/**
 * A source span indicating where a token appears in the input.
 */
export class Span {
  start: i32;
  end: i32;

  new(start: i32, end: i32) : start = start, end = end;

  /** Length of this span in bytes. */
  length: i32 {
    get {
      return this.end - this.start;
    }
  }
}

/**
 * A token with its type and source location.
 */
export class Token {
  type: TokenType;
  span: Span;

  new(type: TokenType, span: Span) : type = type, span = span;
}

// ============================================================================
// Keyword Lookup
// ============================================================================

/**
 * Map a keyword string to its token type, or return Id if not a keyword.
 *
 * WIT keywords are all lowercase with hyphens (kebab-case).
 */
export function keywordToToken(s: String): TokenType {
  // Types
  if (s == "u8") { return TokenType.U8; }
  if (s == "u16") { return TokenType.U16; }
  if (s == "u32") { return TokenType.U32; }
  if (s == "u64") { return TokenType.U64; }
  if (s == "s8") { return TokenType.S8; }
  if (s == "s16") { return TokenType.S16; }
  if (s == "s32") { return TokenType.S32; }
  if (s == "s64") { return TokenType.S64; }
  if (s == "f32") { return TokenType.F32; }
  if (s == "f64") { return TokenType.F64; }
  if (s == "char") { return TokenType.Char; }
  if (s == "bool") { return TokenType.Bool; }
  if (s == "string") { return TokenType.String; }

  // Composite types
  if (s == "record") { return TokenType.Record; }
  if (s == "flags") { return TokenType.Flags; }
  if (s == "variant") { return TokenType.Variant; }
  if (s == "enum") { return TokenType.Enum; }
  if (s == "option") { return TokenType.Option; }
  if (s == "result") { return TokenType.Result; }
  if (s == "list") { return TokenType.List; }
  if (s == "tuple") { return TokenType.Tuple; }
  if (s == "future") { return TokenType.Future; }
  if (s == "stream") { return TokenType.Stream; }
  if (s == "map") { return TokenType.Map; }

  // Resources
  if (s == "resource") { return TokenType.Resource; }
  if (s == "own") { return TokenType.Own; }
  if (s == "borrow") { return TokenType.Borrow; }
  if (s == "constructor") { return TokenType.Constructor; }
  if (s == "static") { return TokenType.Static; }

  // Declarations
  if (s == "type") { return TokenType.Type; }
  if (s == "func") { return TokenType.Func; }
  if (s == "interface") { return TokenType.Interface; }
  if (s == "world") { return TokenType.World; }
  if (s == "package") { return TokenType.Package; }
  if (s == "use") { return TokenType.Use; }
  if (s == "as") { return TokenType.As; }
  if (s == "from") { return TokenType.From; }
  if (s == "import") { return TokenType.Import; }
  if (s == "export") { return TokenType.Export; }
  if (s == "include") { return TokenType.Include; }
  if (s == "with") { return TokenType.With; }

  // Async
  if (s == "async") { return TokenType.Async; }
  if (s == "error-context") { return TokenType.ErrorContext; }

  // Special
  if (s == "_") { return TokenType.Underscore; }

  // Not a keyword
  return TokenType.Id;
}

/**
 * Whether `t` is one of WIT's keywords — a word the grammar claims, so
 * spelling it as a name takes the `%` escape.
 *
 * The keywords are one contiguous run of the enum, from the first type
 * keyword through `_`; a keyword added outside that run would not be
 * recognized here.
 */
export function isKeyword(t: TokenType): boolean {
  let n = t as i32;
  return n >= (TokenType.U8 as i32) && n <= (TokenType.Underscore as i32);
}

/**
 * Get a human-readable description of a token type.
 */
export function describeToken(t: TokenType): String {
  return match (t) {
    case TokenType.Whitespace: "whitespace"
    case TokenType.Comment: "a comment"
    case TokenType.DocComment: "a doc comment"
    case TokenType.Equals: "'='"
    case TokenType.Comma: "','"
    case TokenType.Colon: "':'"
    case TokenType.Period: "'.'"
    case TokenType.Semicolon: "';'"
    case TokenType.LeftParen: "'('"
    case TokenType.RightParen: "')'"
    case TokenType.LeftBrace: "'{'"
    case TokenType.RightBrace: "'}'"
    case TokenType.LessThan: "'<'"
    case TokenType.GreaterThan: "'>'"
    case TokenType.RArrow: "'->'"
    case TokenType.Star: "'*'"
    case TokenType.At: "'@'"
    case TokenType.Slash: "'/'"
    case TokenType.Plus: "'+'"
    case TokenType.Minus: "'-'"
    case TokenType.U8: "keyword `u8`"
    case TokenType.U16: "keyword `u16`"
    case TokenType.U32: "keyword `u32`"
    case TokenType.U64: "keyword `u64`"
    case TokenType.S8: "keyword `s8`"
    case TokenType.S16: "keyword `s16`"
    case TokenType.S32: "keyword `s32`"
    case TokenType.S64: "keyword `s64`"
    case TokenType.F32: "keyword `f32`"
    case TokenType.F64: "keyword `f64`"
    case TokenType.Char: "keyword `char`"
    case TokenType.Bool: "keyword `bool`"
    case TokenType.String: "keyword `string`"
    case TokenType.Record: "keyword `record`"
    case TokenType.Flags: "keyword `flags`"
    case TokenType.Variant: "keyword `variant`"
    case TokenType.Enum: "keyword `enum`"
    case TokenType.Option: "keyword `option`"
    case TokenType.Result: "keyword `result`"
    case TokenType.List: "keyword `list`"
    case TokenType.Tuple: "keyword `tuple`"
    case TokenType.Future: "keyword `future`"
    case TokenType.Stream: "keyword `stream`"
    case TokenType.Map: "keyword `map`"
    case TokenType.Resource: "keyword `resource`"
    case TokenType.Own: "keyword `own`"
    case TokenType.Borrow: "keyword `borrow`"
    case TokenType.Constructor: "keyword `constructor`"
    case TokenType.Static: "keyword `static`"
    case TokenType.Type: "keyword `type`"
    case TokenType.Func: "keyword `func`"
    case TokenType.Interface: "keyword `interface`"
    case TokenType.World: "keyword `world`"
    case TokenType.Package: "keyword `package`"
    case TokenType.Use: "keyword `use`"
    case TokenType.As: "keyword `as`"
    case TokenType.From: "keyword `from`"
    case TokenType.Import: "keyword `import`"
    case TokenType.Export: "keyword `export`"
    case TokenType.Include: "keyword `include`"
    case TokenType.With: "keyword `with`"
    case TokenType.Async: "keyword `async`"
    case TokenType.ErrorContext: "keyword `error-context`"
    case TokenType.Underscore: "keyword `_`"
    case TokenType.Id: "an identifier"
    case TokenType.ExplicitId: "an '%' identifier"
    case TokenType.Integer: "an integer"
    case TokenType.Eof: "end of file"
  };
}
none
VersionPublishedDependenciesApproved by
0.0.1-preview.1 2026-11-19 none