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.
/**
* The WIT type encoder: a resolved document's world, as the type and
* import sections of a component binary.
*
* This is the encoding half of what `wasm-tools component embed` does —
* each imported interface becomes an instance type whose declarations
* spell out its types and functions, and the component imports one
* instance per interface. The compiler's component target consumes the
* emitted pieces to head its own component; `encodeTypesOnlyComponent`
* wraps the same pieces in a bare component so the encoding can be
* verified on its own, by handing the bytes back to
* `wasm-tools component wit`.
*
* The encoding rules that are easy to get wrong, verified against
* `wasm-tools 1.252.0` byte for byte:
*
* - A type index in *value-type position* is a signed LEB128, because
* the primitive opcodes (`0x64`–`0x7f`) are its negative range. An
* index of 79 is two bytes. Indices in every other position (type
* bounds, `own`, export declarations) are unsigned.
* - Every WIT-*named* type — record, variant, enum, flags, resource,
* `type` alias — must be **exported** from the instance type, and it
* is the *export* that creates the index everything else refers to.
* An instance type that keeps a record anonymous validates on its
* own and then fails at the import with "instance not valid to be
* used as import". Anonymous constructors (`list`, `tuple`,
* `option`, `result`, `own`, `borrow`) need no export.
* - A `use`d type crosses instances in two hops: at component level an
* `alias export` pulls it out of the already-imported source
* instance, and inside the dependent instance type an `alias outer`
* (count 1: the enclosing component) brings it back in, where it is
* re-exported under its local name.
* - A method's `self: borrow<R>` parameter is implicit in WIT and
* explicit in the binary; a constructor returns `own<R>` the same
* way. Resource function export names carry the `[constructor]r` /
* `[method]r.f` / `[static]r.f` prefixes.
*
* What this does not encode yet, each a loud `EncodeError` rather than
* wrong bytes: `future`, `stream`, `map` and `error-context` (their
* runtime is C6), fixed-length lists, world-level `use` and type
* definitions, and `include`. A world's *exports* are skipped rather
* than rejected — a types-only component has nothing to implement them
* with, and the compiler's own export machinery is what lifts real
* functions — and the skipped names are reported on the result so a
* caller can say so.
*/
import { ByteBuffer } from 'zena:core';
import {
Ast, AstItem, AstItemTag, InterfaceDef, WorldDef, InterfaceItem,
InterfaceItemTag, TypeDef, TypeDefTag, Type, TypeTag, NamedFunc, Func,
ResourceFunc, ResourceFuncTag, Use, UsePath, UsePathTag,
IdUsePath, PackageUsePath,
PackageName, WorldItem, WorldItemTag, Import, Export, ExternKind,
ExternKindTag, Id, Include, Field, Case, EnumCaseDef, FlagDef, Parser,
Docs, AttributeTag,
} from './parser.zena';
/** A failure to encode: a construct the encoder cannot express yet. */
export class EncodeError extends Error {
new(message: String) : super(message);
}
/**
* A WIT type expression, parsed alone: wrapped in a one-alias
* document so the ordinary parser reads it, then unwrapped. Names
* stay syntactic — the caller resolves them against an interface.
*/
function parseTypeText(text: String): Type {
let ast = Parser.parse(
`package canon:payload;\ninterface t {\n type p = ${text};\n}\n`);
for (let item in ast.items) {
if (item.tag != AstItemTag.Interface) { continue; }
for (let ii in (item.interfaceDef as InterfaceDef).items) {
if (ii.tag != InterfaceItemTag.TypeDef) { continue; }
let td = ii.typeDef as TypeDef;
if (td.tag == TypeDefTag.Alias) {
return td.aliasType as Type;
}
}
}
throw new EncodeError(`cannot parse the canon type payload '${text}'`);
}
// Component binary section ids. They are not core wasm's — a component
// numbers its sections differently.
export let sectionCoreModule = 1;
export let sectionType = 7;
export let sectionAlias = 6;
export let sectionImport = 10;
export let sectionExport = 11;
/** The name a nested component imports the export `name` under: the
* resource and the kind spelled out, as wit-component names them. */
function nestedFuncImportName(name: String) {
if (name.startsWith("[constructor]")) {
return "import-constructor-" + name.sliceBytes(13, name.length);
}
if (name.startsWith("[method]") || name.startsWith("[static]")) {
let kind = name.sliceBytes(1, 7);
let rest = name.sliceBytes(9, name.length);
var out = `import-${kind}-`;
for (var i = 0; i < rest.length; i += 1) {
let c = rest.getByteAt(i);
out = out + (if (c == 46) "-" else rest.sliceBytes(i, i + 1)); // '.'
}
return out;
}
return "import-func-" + name;
}
/**
* One section of the component head, in emission order. The ids repeat —
* a type section per instance type, an import section per import — which
* the format allows and `wasm-tools` itself produces; interleaving is
* what lets an alias name the import before it.
*/
export final class SectionPiece {
id: i32;
payload: ByteBuffer;
new(this.id, this.payload);
}
/**
* A value-type code: a local type index when `>= 0`, and a primitive's
* opcode negated when `< 0`. The two need one representation because a
* field or parameter holds either, and the sign is what keeps an index
* of 0x73 distinct from `string`.
*/
function primCode(opcode: i32) {
return 0 - opcode;
}
function writeValType(buf: ByteBuffer, code: i32) {
if (code < 0) {
buf.writeByte(0 - code);
} else {
// Signed on purpose: this position's grammar is
// `typeidx | primvaltype`, and the primitives are the negative
// SLEB128 space. An unsigned encoding of 64..127 would collide.
buf.writeSLEB128(code);
}
}
function writeName(buf: ByteBuffer, name: String) {
buf.writeULEB128(name.length);
for (var i = 0; i < name.length; i += 1) {
buf.writeByte(name.getByteAt(i));
}
}
/** An import or export name: the plain-name discriminant, then the name. */
function writeExternName(buf: ByteBuffer, name: String) {
buf.writeByte(0x00);
writeName(buf, name);
}
function primOpcodeOf(tag: TypeTag): i32 {
if (tag == TypeTag.Bool) { return 0x7f; }
if (tag == TypeTag.S8) { return 0x7e; }
if (tag == TypeTag.U8) { return 0x7d; }
if (tag == TypeTag.S16) { return 0x7c; }
if (tag == TypeTag.U16) { return 0x7b; }
if (tag == TypeTag.S32) { return 0x7a; }
if (tag == TypeTag.U32) { return 0x79; }
if (tag == TypeTag.S64) { return 0x78; }
if (tag == TypeTag.U64) { return 0x77; }
if (tag == TypeTag.F32) { return 0x76; }
if (tag == TypeTag.F64) { return 0x75; }
if (tag == TypeTag.Char) { return 0x74; }
if (tag == TypeTag.String) { return 0x73; }
return -1;
}
/**
* Where a `use`d name comes from: the qualified name of the interface
* that declares it, and the name it has there (a `use` may rename).
*/
final class UseHop {
source: String;
typeName: String;
new(this.source, this.typeName);
}
/** One interface the document defines, under its import name. */
final class RegisteredInterface {
/** The name the component imports it by: `ns:pkg/iface@version`. */
qualifiedName: String;
items: Array<InterfaceItem>;
/**
* The package the interface was declared in. A bare `use foo` from
* inside it resolves against this package, not the document's main
* one — nested packages have their own name spaces.
*/
packageName: PackageName | null;
new(this.qualifiedName, this.items, this.packageName = null);
}
/**
* Where declarations land while one signature's types are encoded.
*
* An *instance* scope buffers instance declarations — `0x01` type,
* `0x04` export — to become one instance type, and its indices are
* local to it. The *component* scope (for a world-level function's
* types) writes each type as a component-level type section instead,
* and its indices are the component's. `#declareType` is the one place
* that knows the difference.
*/
final class Scope {
/** Buffered instance declarations; unused at component level. */
decls = new ByteBuffer();
var declCount = 0;
var typeCount = 0;
/** WIT type name → the local index its *export* created. */
named = new HashMap<String, i32>();
/**
* The named indices that are resources. A resource name in value
* position means `own` of it — `open: func() -> bucket` returns a
* handle — so `#encodeType` has to know which lookups to wrap, and
* a `use`d resource is still one.
*/
resourceIndices = new HashMap<i32, boolean>();
/** Structural key of an anonymous type → its index here. */
anon = new HashMap<String, i32>();
/**
* The interface's type definitions not encoded yet, by name: a
* reference to one encodes it on the spot, so an interface may
* declare its types in any order — upstream WASI does, and the
* encoding's own order is first use.
*/
pending = new HashMap<String, TypeDef>();
var atComponentLevel = false;
/**
* Component-level only: the interface whose declarations resolve
* named types this scope meets, each alias-exported from the
* imported instance on first use. Set for a canon builtin's type —
* a `future<result<option<trailers>, error-code>>` names the
* interface's types from outside any instance scope.
*/
var aliasSource: RegisteredInterface | null = null;
/**
* Set while encoding into a nested component (an exported
* interface's): declared types go to its sections and count in its
* own index space, and a named type of the interface is imported
* into it on first use rather than aliased.
*/
var nested: NestedComponent | null = null;
/**
* The nested component's hooks, installed by its encoder: where a
* declared type goes, and how a named type is met. Closures rather
* than calls on `nested`, because a program that never builds a
* nested component (the encoder's own round-trip tool) never
* constructs the class, and the compiler refuses a method call on
* a class it never constructed even on a path that cannot run
* (issue #447); a closure that is never created reaches nothing.
*/
var nestedDeclare: ((body: ByteBuffer) => void) | null = null;
var nestedNamed: ((name: String) => i32) | null = null;
}
/**
* A type a nested component imports from the enclosing one: the
* import's name, and the enclosing component's type index the
* instantiation supplies for it.
*/
export final class NestedTypeImport {
name: String;
outerIndex: i32;
new(this.name, this.outerIndex);
}
/**
* An exported interface realized as a nested component, the shape an
* exported resource needs: a component's own exports name a resource
* (`export "surface" (type $r)`), and a `[method]surface.size` export
* is validated against the names in that context, which an instance
* built from a bag of exports never has. The nested component imports
* each resource as a subtype of `resource` and each non-resource type
* as `eq` of a local copy, imports the enclosing component's lifted
* functions at types naming those, exports the resources and fresh
* copies of the other types under their names, and exports each
* function with a type naming the exported ones — what wit-component
* emits. `funcImports` are the function import names, one per export
* name the encoding was asked for, in that order.
*/
export final class NestedExport {
bytes = new ByteBuffer();
typeImports = new GrowableArray<NestedTypeImport>();
funcImports = new GrowableArray<String>();
}
/** A nested component under construction. */
final class NestedComponent {
out: NestedExport;
var funcCount = 0;
/** The interface's own non-resource types imported so far, to
* export again once the resources have their names. */
ownTypes = new GrowableArray<String>();
/** Whether the export phase has begun: a named type met now is
* exported as a fresh copy rather than imported. */
var exporting = false;
new(this.out);
section(id: i32, payload: ByteBuffer): void {
this.out.bytes.writeByte(id);
this.out.bytes.writeULEB128(payload.length);
this.out.bytes.writeBuffer(payload);
}
}
/**
* A resource the program provides, in the order its type was encoded:
* the k-th one's destructor is core function k. The emitter keeps that
* promise with a shim core module it instantiates before anything
* else — a table of function references and one trampoline per slot,
* aliased as the first core functions — and fills the table with the
* program's destructor exports once the program instance exists. The
* indirection is what lets the resource type name a destructor that
* lives in an instance which cannot exist yet: the program's core
* module imports `resource.new` for the type, so the type comes first.
*/
export final class DtorSlot {
qualified: String;
name: String;
new(this.qualified, this.name);
}
/** What `encodeWorld` produced. */
/** One type an exported interface declares itself: its name in the
* interface, and the component-level type index it was encoded at. */
export final class ExportedTypeIndex {
name: String;
index: i32;
new(this.name, this.index);
}
export final class EncodedWorld {
/** The component-head sections, in order. */
pieces = new GrowableArray<SectionPiece>();
/**
* The types each exported interface declares itself, by the
* interface's qualified name, in encoding order. Encoded at
* component level as a function type of the interface first names
* them; the exported instance exports each under its name, so the
* interface reads back with its own types.
*/
exportedTypes = new HashMap<String, GrowableArray<ExportedTypeIndex>>();
/** The program's resources with a destructor slot each (`DtorSlot`). */
dtorSlots = new GrowableArray<DtorSlot>();
/** How many component-level types the pieces defined. */
var typeCount = 0;
/** How many instances the pieces imported. */
var instanceCount = 0;
/** How many component-level functions the pieces imported. */
var funcImportCount = 0;
/**
* Each imported interface's component-level instance index, by its
* qualified name. Interfaces are imported in dependency order, not
* request order, so a consumer aliasing functions out of an instance
* looks the index up rather than assuming it.
*/
instanceIndices = new HashMap<String, i32>();
/** World exports the encoding skipped, for the caller to report. */
skippedExports = new GrowableArray<String>();
}
export final class ComponentTypeEncoder {
#ast: Ast;
#result = new EncodedWorld();
/** Everything importable by qualified name, main package and nested. */
#interfaces = new GrowableArray<RegisteredInterface>();
/** Qualified interface name → component-level instance index. */
#instanceIndex = new HashMap<String, i32>();
/**
* `qualifiedInterface + '#' + typeName` → the component-level type
* index its `alias export` created. One alias serves every interface
* that uses the type.
*/
#aliasedTypes = new HashMap<String, i32>();
new(ast: Ast) : #ast = ast {
this.#registerPackage(ast.packageName, ast.items);
for (let nested in ast.nestedPackages) {
this.#registerPackage(nested.name, nested.items);
}
}
#registerPackage(pkgName: PackageName | null, items: Array<AstItem>): void {
for (let item in items) {
if (item.tag == AstItemTag.Interface) {
let def = item.interfaceDef as InterfaceDef;
this.#interfaces.push(new RegisteredInterface(
qualifiedInterfaceName(pkgName, def.name.name), def.items,
pkgName));
}
}
}
/**
* Encode the world's imports. Interfaces are imported in first-use
* order with their `use` dependencies ahead of them — WIT implies the
* import of anything a used type comes from, so a dependency absent
* from the world's own list still gets an instance. An `include`
* brings the included world's imports and exports
* (expandedWorldItems).
*/
encodeWorld(worldName: String): EncodedWorld {
let world = this.#findWorld(worldName);
for (let item in expandedWorldItems(this.#ast, world)) {
if (item.tag == WorldItemTag.Import) {
this.#encodeWorldImport((item.importItem as Import).kind);
} else if (item.tag == WorldItemTag.Export) {
this.#result.skippedExports.push(externName(
(item.exportItem as Export).kind));
} else if (item.tag == WorldItemTag.Use) {
throw new EncodeError("world-level `use` is not encodable yet");
} else if (item.tag == WorldItemTag.TypeDef) {
throw new EncodeError(
"world-level type definitions are not encodable yet");
} else {
throw new EncodeError("world `include` is not encodable yet");
}
}
return this.#result;
}
#encodeWorldImport(kind: ExternKind): void {
if (kind.tag == ExternKindTag.Path) {
this.#importInterface(this.#resolveInterface(kind.path as UsePath));
} else if (kind.tag == ExternKindTag.Func) {
this.#importWorldFunc((kind.name as Id).name, kind.funcDef as Func);
} else {
// An inline interface: the same encoding, imported under the
// plain name its declaration gave it.
this.#importNamedInterface(new RegisteredInterface(
(kind.name as Id).name, kind.items as GrowableArray<InterfaceItem>));
}
}
/**
* A world-level function import: its types live at component level,
* each in a type section of its own, then the import names the
* functype. Only structural types can appear here — a named type
* would have arrived through world-level `use` or a world type
* definition, both rejected before this runs.
*/
#importWorldFunc(name: String, func: Func): void {
let scope = new Scope();
scope.atComponentLevel = true;
scope.typeCount = this.#result.typeCount;
let funcType = this.#encodeFuncType(scope, func, -1, func.isAsync);
let imp = new ByteBuffer();
imp.writeULEB128(1);
writeExternName(imp, name);
imp.writeByte(0x01); // externdesc: func
imp.writeULEB128(funcType);
this.#result.pieces.push(new SectionPiece(sectionImport, imp));
this.#result.funcImportCount += 1;
}
#resolveInterface(
path: UsePath,
contextPackage: PackageName | null = null
): RegisteredInterface {
let qualified = if (path.tag == UsePathTag.Id) {
// A bare name resolves within the package the `use` sits in;
// only a top-level world's imports resolve against the main one.
qualifiedInterfaceName(
contextPackage ?? this.#ast.packageName,
(path.id as Id).name)
} else {
qualifiedInterfaceName(path.packageId, (path.name as Id).name)
};
for (let r in this.#interfaces) {
if (r.qualifiedName == qualified) {
return r;
}
}
throw new EncodeError("interface '" + qualified +
"' is not defined in this document; cross-document " +
"dependencies are not resolvable yet");
}
#importInterface(reg: RegisteredInterface): void {
if (this.#instanceIndex.has(reg.qualifiedName)) {
return;
}
// Dependencies first: an `alias export` can only name an instance
// that is already imported.
for (let item in reg.items) {
if (item.tag == InterfaceItemTag.Use) {
this.#importInterface(this.#resolveInterface(
(item.use as Use).from, reg.packageName));
}
}
this.#importNamedInterface(reg);
}
#importNamedInterface(reg: RegisteredInterface): void {
let scope = new Scope();
for (let item in reg.items) {
if (item.tag == InterfaceItemTag.TypeDef) {
let td = item.typeDef as TypeDef;
scope.pending[td.name.name] = td;
}
}
for (let item in reg.items) {
if (item.tag == InterfaceItemTag.Use) {
this.#encodeUse(scope, item.use as Use, reg.packageName);
} else if (item.tag == InterfaceItemTag.TypeDef) {
let td = item.typeDef as TypeDef;
// Unless a reference already encoded it.
if (scope.pending.has(td.name.name)) {
this.#encodeTypeDef(scope, td);
}
} else {
this.#encodeInterfaceFunc(scope, item.func as NamedFunc, "", -1);
}
}
let types = new ByteBuffer();
types.writeULEB128(1);
types.writeByte(0x42); // instance type
types.writeULEB128(scope.declCount);
types.writeBuffer(scope.decls);
this.#result.pieces.push(new SectionPiece(sectionType, types));
let instanceTypeIndex = this.#result.typeCount;
this.#result.typeCount += 1;
let imp = new ByteBuffer();
imp.writeULEB128(1);
writeExternName(imp, reg.qualifiedName);
imp.writeByte(0x05); // externdesc: instance
imp.writeULEB128(instanceTypeIndex);
this.#result.pieces.push(new SectionPiece(sectionImport, imp));
this.#instanceIndex[reg.qualifiedName] = this.#result.instanceCount;
this.#result.instanceIndices[reg.qualifiedName] =
this.#result.instanceCount;
this.#result.instanceCount += 1;
}
/**
* A `use`: each named type is aliased out of its source instance at
* component level (once, however many interfaces use it), aliased
* back in through `outer`, and re-exported under its local name —
* which may differ, `use` renames.
*/
#encodeUse(
scope: Scope,
use: Use,
contextPackage: PackageName | null
): void {
let source = this.#resolveInterface(use.from, contextPackage);
for (let n in use.names) {
let componentIndex =
this.#usedTypeIndex(new UseHop(source.qualifiedName, n.name.name));
scope.decls.writeByte(0x02); // instancedecl: alias
scope.decls.writeByte(0x03); // sort: type
scope.decls.writeByte(0x02); // target: outer
scope.decls.writeULEB128(1); // count 1: the enclosing component
scope.decls.writeULEB128(componentIndex);
scope.declCount += 1;
let inner = scope.typeCount;
scope.typeCount += 1;
let asName = n.asName;
let localName = asName?.name ?? n.name.name;
let exported = this.#exportType(scope, localName, inner);
scope.named[localName] = exported;
if (this.#isResource(source, n.name.name)) {
scope.resourceIndices[exported] = true;
}
}
}
/**
* Whether `name` in `reg` is a resource — directly, through a `use`,
* or through a `type` alias of either. Resource-ness survives every
* hop, and it decides whether a value-position mention is a handle.
*/
/**
* The interface `reg` `use`s `name` from, and the name there, or
* null when `reg` does not `use` it.
*/
#useSourceOf(reg: RegisteredInterface, name: String): UseHop | null {
for (let item in reg.items) {
if (item.tag != InterfaceItemTag.Use) { continue; }
let use = item.use as Use;
for (let n in use.names) {
let asName = n.asName;
let localName =
asName?.name ?? n.name.name;
if (localName == name) {
let source = this.#resolveInterface(use.from, reg.packageName);
return new UseHop(source.qualifiedName, n.name.name);
}
}
}
return null;
}
#isResource(reg: RegisteredInterface, name: String): boolean {
for (let item in reg.items) {
if (item.tag == InterfaceItemTag.TypeDef) {
let td = item.typeDef as TypeDef;
if (td.name.name == name) {
if (td.tag == TypeDefTag.Resource) {
return true;
}
if (td.tag == TypeDefTag.Alias) {
let target = td.aliasType as Type;
if (target.tag == TypeTag.Name) {
return this.#isResource(reg, (target.name as Id).name);
}
}
return false;
}
} else if (item.tag == InterfaceItemTag.Use) {
let use = item.use as Use;
for (let n in use.names) {
let asName = n.asName;
let localName =
asName?.name ?? n.name.name;
if (localName == name) {
return this.#isResource(
this.#resolveInterface(use.from, reg.packageName),
n.name.name);
}
}
}
}
return false;
}
/**
* The component-level type index of `typeName` exported by an
* already-imported interface, alias-exporting it on first use.
* Public for the canon builtins: `resource.drop` takes the imported
* resource's own (nominal) type as its immediate, which only an
* alias can name.
*/
aliasResourceType(qualifiedInterface: String, typeName: String): i32 {
let reg = this.#findRegistered(qualifiedInterface);
if (reg == null || !this.#isResource(
reg, typeName)) {
throw new EncodeError("'" + typeName + "' is not a resource of '" +
qualifiedInterface + "'");
}
if (!this.#instanceIndex.has(qualifiedInterface)) {
// No instance to alias from: the interface is exported, and the
// resource is the program's own — `resource.new` and
// `resource.rep` name its component-level type.
return this.#encodeExportedOwnType(reg,
typeName);
}
return this.#aliasTypeExport(qualifiedInterface, typeName);
}
/**
* The component-level type index of `future<payloadText>`, the
* payload parsed as WIT against `qualifiedInterface`'s declarations
* — named types alias-exported from the imported instance on first
* use, or, for an exported interface, from the imported source its
* `use` names. Public for the canon builtins: the future.* family's
* canon entry carries the future's own component type, and a payload
* like `result<option<trailers>, error-code>` names the interface's
* types from outside any instance scope. An empty `payloadText` is
* the bare `future`; an empty `qualifiedInterface` is a world-level
* function's future, whose payload is structural.
*/
aliasFutureType(qualifiedInterface: String, payloadText: String): i32 {
return this.#aliasEndType(0x65, "future", qualifiedInterface,
payloadText);
}
/**
* The component-level type index of `stream<elementText>`, the
* element parsed against `qualifiedInterface`'s declarations the
* way a future's payload is. Public for the canon builtins: the
* stream.* family's canon entry carries the stream's own type.
*/
aliasStreamType(qualifiedInterface: String, elementText: String): i32 {
return this.#aliasEndType(0x66, "stream", qualifiedInterface,
elementText);
}
/** `future<p>` (0x65) or `stream<e>` (0x66) at component level,
* memoized per interface and payload spelling. */
#aliasEndType(opcode: i32, head: String, qualifiedInterface: String,
payloadText: String): i32 {
let key = `${qualifiedInterface}#${head}<${payloadText}>`;
if (let (true, existing) = this.#aliasedTypes.get(key)) {
return existing;
}
let scope = new Scope();
scope.atComponentLevel = true;
scope.typeCount = this.#result.typeCount;
if (qualifiedInterface != "") {
let reg = this.#findRegistered(qualifiedInterface);
if (reg == null) {
throw new EncodeError(`'${qualifiedInterface}' is not a known interface`);
}
scope.aliasSource = reg;
}
let inner = if (payloadText != "") {
this.#encodeType(scope, parseTypeText(payloadText))
} else {
-1
};
let body = new ByteBuffer();
body.writeByte(opcode);
if (payloadText != "") {
body.writeByte(0x01);
writeValType(body, inner);
} else {
body.writeByte(0x00);
}
let index = this.#declareType(scope, body);
this.#aliasedTypes[key] = index;
return index;
}
/**
* The component-level valtype — a primitive's code, or a type
* index — of the WIT type `typeText`. Parsed against
* `qualifiedInterface`'s declarations when one is named, its named
* types alias-exported from the imported instance on first use;
* at the component's own level when the name is empty, where only
* structural types can appear. Public for the canon builtins: a
* typed `task.return` carries the result type of the export it
* returns for.
*/
encodeTypeText(qualifiedInterface: String, typeText: String): i32 {
let key = `${qualifiedInterface}#type:${typeText}`;
if (let (true, existing) = this.#aliasedTypes.get(key)) {
return existing;
}
let scope = new Scope();
scope.atComponentLevel = true;
scope.typeCount = this.#result.typeCount;
if (qualifiedInterface != "") {
// Imported or exported: an exported interface's named types
// reach it through `use`, and `#namedIndex` follows the use to
// the imported source.
let reg = this.#findRegistered(qualifiedInterface);
if (reg == null) {
throw new EncodeError(`'${qualifiedInterface}' is not a known interface`);
}
scope.aliasSource = reg;
}
let code = this.#encodeType(scope, parseTypeText(typeText));
this.#aliasedTypes[key] = code;
return code;
}
/**
* The component-level function type of `funcName` in the exported
* interface `qualifiedInterface`, for the lift of the core function
* implementing it. Its named types come through the interface's
* `use`s, alias-exported from the imported sources; a type the
* exported interface declares itself is not encodable yet.
*/
encodeExportedInterfaceFuncType(
qualifiedInterface: String,
funcName: String
): i32 {
let reg = this.#findRegistered(qualifiedInterface);
if (reg == null) {
throw new EncodeError(`'${qualifiedInterface}' is not a known interface`);
}
for (let item in reg.items) {
if (item.tag != InterfaceItemTag.Func) { continue; }
let nf = item.func as NamedFunc;
if (nf.name.name != funcName) { continue; }
let scope = new Scope();
scope.atComponentLevel = true;
scope.typeCount = this.#result.typeCount;
scope.aliasSource = reg;
return this.#encodeFuncType(scope, nf.func, -1, nf.func.isAsync);
}
// A resource's function, exported under its mangled name: the
// program's resource type is encoded (or found) at component
// level, and a method's `self` is a borrow of it.
let found = resourceFuncNamed(reg.items, funcName);
if (found != null) {
let rf = found.rf;
let scope = new Scope();
scope.atComponentLevel = true;
scope.typeCount = this.#result.typeCount;
scope.aliasSource = reg;
let resourceIndex = this.#namedIndex(scope,
found.resourceName);
if (rf.tag == ResourceFuncTag.Constructor) {
return this.#constructorFuncType(scope, rf.func.func, resourceIndex);
}
if (rf.tag == ResourceFuncTag.Method) {
let borrowIndex = this.#handleType(scope, 0x68, resourceIndex);
return this.#encodeFuncType(scope, rf.func.func, borrowIndex,
rf.func.func.isAsync);
}
return this.#encodeFuncType(scope, rf.func.func, -1,
rf.func.func.isAsync);
}
throw new EncodeError("'" + qualifiedInterface +
"' declares no function '" + funcName + "'");
}
/** Whether the interface `qualified` declares a resource of its own. */
interfaceDeclaresResource(qualified: String): boolean {
let reg = this.#findRegistered(qualified);
if (reg == null) {
return false;
}
for (let item in reg.items) {
if (item.tag == InterfaceItemTag.TypeDef &&
(item.typeDef as TypeDef).tag == TypeDefTag.Resource) {
return true;
}
}
return false;
}
/**
* The nested component realizing the exported interface
* `qualifiedInterface` (see `NestedExport`), with the functions the
* program exports under `exportNames` — every function of the
* interface, in the order the emitter lifts them.
*/
encodeExportedInterfaceComponent(qualifiedInterface: String,
exportNames: Array<String>): NestedExport {
let regOpt = this.#findRegistered(qualifiedInterface);
if (regOpt == null) {
throw new EncodeError(`'${qualifiedInterface}' is not a known interface`);
}
let reg = regOpt;
let out = new NestedExport();
let nested = new NestedComponent(out);
out.bytes.writeU32(0x6D736100); // \0asm
out.bytes.writeU32(0x0001000D); // version 0x0d, layer 1: a component
let scope = new Scope();
scope.nested = nested;
scope.aliasSource = reg;
scope.nestedDeclare = (body: ByteBuffer) => {
let section = new ByteBuffer();
section.writeULEB128(1);
section.writeBuffer(body);
nested.section(sectionType, section);
};
scope.nestedNamed = (name: String) =>
this.#nestedNamedIndex(scope, name);
// 1. Every resource the interface declares or `use`s, imported as
// a subtype of `resource`; the enclosing component's own resource
// type, or its alias of an imported instance's, instantiates it.
let resources = new GrowableArray<String>();
for (let item in reg.items) {
if (item.tag == InterfaceItemTag.TypeDef) {
let td = item.typeDef as TypeDef;
if (td.tag == TypeDefTag.Resource) {
resources.push(td.name.name);
}
} else if (item.tag == InterfaceItemTag.Use) {
for (let n in (item.use as Use).names) {
let asName = n.asName;
let localName =
asName?.name ?? n.name.name;
if (this.#isResource(reg, localName)) {
resources.push(localName);
}
}
}
}
for (let r in resources) {
let hop = this.#useSourceOf(reg, r);
let outerIndex = if (hop == null) {
this.#encodeExportedOwnType(reg, r)
} else {
this.#usedTypeIndex(hop)
};
let imp = new ByteBuffer();
imp.writeULEB128(1);
writeExternName(imp, "import-type-" + r);
imp.writeByte(0x03); // externdesc: type
imp.writeByte(0x01); // typebound: sub resource
nested.section(sectionImport, imp);
let index = scope.typeCount;
scope.typeCount += 1;
scope.named[r] = index;
scope.resourceIndices[index] = true;
out.typeImports.push(new NestedTypeImport("import-type-" + r, outerIndex));
}
// 2. The functions, imported at types naming the imported
// resources (an import may name only imported types).
for (let name in exportNames) {
let typeIndex = this.#nestedFuncType(scope, reg, name);
let importName = nestedFuncImportName(name);
let imp = new ByteBuffer();
imp.writeULEB128(1);
writeExternName(imp, importName);
imp.writeByte(0x01); // externdesc: func
imp.writeULEB128(typeIndex);
nested.section(sectionImport, imp);
out.funcImports.push(importName);
nested.funcCount += 1;
}
// 3. The exports: the resources under their names — which is what
// names them for the method-style exports — then fresh copies of
// the interface's other types, then each function at a type naming
// the exported ones, ascribed on the export.
nested.exporting = true;
scope.anon.clear();
for (let name in nested.ownTypes) {
scope.named.delete(name);
}
for (let r in resources) {
let imported = scope.named[r];
let index = this.#nestedExportType(scope, r, imported);
scope.named[r] = index;
scope.resourceIndices[index] = true;
}
let ownTypes = new GrowableArray<String>();
for (let name in nested.ownTypes) {
ownTypes.push(name);
}
for (let name in ownTypes) {
this.#namedIndex(scope, name);
}
for (var i = 0; i < exportNames.length; i += 1) {
let ascribed = this.#nestedFuncType(scope, reg, exportNames[i]);
let exp = new ByteBuffer();
exp.writeULEB128(1);
writeExternName(exp, exportNames[i]);
exp.writeByte(0x01); // sort: func
exp.writeULEB128(i);
exp.writeByte(0x01); // an ascribed type follows
exp.writeByte(0x01); // externdesc: func
exp.writeULEB128(ascribed);
nested.section(sectionExport, exp);
}
return out;
}
/** Exports nested type `index` under `name`; the export's own index. */
#nestedExportType(scope: Scope, name: String, index: i32): i32 {
let nested = scope.nested as NestedComponent;
let exp = new ByteBuffer();
exp.writeULEB128(1);
writeExternName(exp, name);
exp.writeByte(0x03); // sort: type
exp.writeULEB128(index);
exp.writeByte(0x00); // no ascribed type
nested.section(sectionExport, exp);
let exported = scope.typeCount;
scope.typeCount += 1;
return exported;
}
/**
* A named non-resource type met inside a nested component: its
* structure declared there, resolved against the interface that
* declares it, then imported as `eq` of that declaration (the
* enclosing component's type instantiates it) — or, in the export
* phase, exported as a fresh copy under its name.
*/
#nestedNamedIndex(scope: Scope, name: String): i32 {
let nested = scope.nested as NestedComponent;
let reg = scope.aliasSource as RegisteredInterface;
if (this.#isResource(reg, name)) {
throw new EncodeError("resource '" + name + "' of '" +
reg.qualifiedName + "' was not imported into its exported instance");
}
var owner = reg;
var tdName = name;
var outerIndex = -1;
let hop = this.#useSourceOf(reg, name);
if (hop == null) {
if (!this.#declaresType(reg, name)) {
throw new EncodeError("'" + reg.qualifiedName +
"' declares no type '" + name + "'");
}
outerIndex = this.#encodeExportedOwnType(reg, name);
} else {
let h = hop;
let source = this.#findRegistered(h.source);
if (source == null) {
throw new EncodeError(`'${h.source}' is not a known interface`);
}
owner = source;
tdName = h.typeName;
outerIndex = this.#usedTypeIndex(h);
}
var found: TypeDef | null = null;
for (let item in owner.items) {
if (item.tag != InterfaceItemTag.TypeDef) { continue; }
let td = item.typeDef as TypeDef;
if (td.name.name == tdName) { found = td; }
}
if (found == null) {
throw new EncodeError("'" + owner.qualifiedName +
"' declares no type '" + tdName + "'");
}
let td = found;
let savedSource = scope.aliasSource;
scope.aliasSource = owner;
var local = -1;
if (td.tag == TypeDefTag.Alias) {
let target = td.aliasType as Type;
if (target.tag == TypeTag.Name) {
local = this.#namedIndex(scope, (target.name as Id).name);
} else {
let encoded = this.#encodeType(scope, target);
if (encoded < 0) {
let body = new ByteBuffer();
body.writeByte(0 - encoded);
local = this.#declareType(scope, body);
} else {
local = encoded;
}
}
} else {
local = this.#encodeTypeBody(scope, td);
}
scope.aliasSource = savedSource;
if (nested.exporting) {
let index = this.#nestedExportType(scope, name, local);
scope.named[name] = index;
return index;
}
let imp = new ByteBuffer();
imp.writeULEB128(1);
writeExternName(imp, "import-type-" + name);
imp.writeByte(0x03); // externdesc: type
imp.writeByte(0x00); // typebound: eq
imp.writeULEB128(local);
nested.section(sectionImport, imp);
let index = scope.typeCount;
scope.typeCount += 1;
scope.named[name] = index;
nested.out.typeImports.push(
new NestedTypeImport("import-type-" + name, outerIndex));
if (hop == null) {
nested.ownTypes.push(name);
}
return index;
}
/**
* The function type of the export `name` of `reg` in `scope` — a
* free function's, or a resource function's found by its mangled
* name, with a constructor's implicit `own` result and a method's
* `self` borrow.
*/
#nestedFuncType(scope: Scope, reg: RegisteredInterface,
name: String): i32 {
for (let item in reg.items) {
if (item.tag != InterfaceItemTag.Func) { continue; }
let nf = item.func as NamedFunc;
if (nf.name.name == name) {
return this.#encodeFuncType(scope, nf.func, -1, nf.func.isAsync);
}
}
let found = resourceFuncNamed(reg.items, name);
if (found == null) {
throw new EncodeError("'" + reg.qualifiedName +
"' declares no function '" + name + "'");
}
let rf = found.rf;
let resourceIndex = scope.named[found.resourceName];
if (rf.tag == ResourceFuncTag.Constructor) {
return this.#constructorFuncType(scope, rf.func.func, resourceIndex);
}
if (rf.tag == ResourceFuncTag.Method) {
let borrowIndex = this.#handleType(scope, 0x68, resourceIndex);
return this.#encodeFuncType(scope, rf.func.func, borrowIndex,
rf.func.func.isAsync);
}
return this.#encodeFuncType(scope, rf.func.func, -1, rf.func.func.isAsync);
}
/** A constructor's function type: its parameters, and `own` of the
* resource as the result. */
#constructorFuncType(scope: Scope, func: Func, resourceIndex: i32): i32 {
let ownIndex = this.#handleType(scope, 0x69, resourceIndex);
let paramCodes = new GrowableArray<i32>();
for (let p in func.params) {
paramCodes.push(this.#encodeType(scope, p.type));
}
let body = new ByteBuffer();
body.writeByte(0x40);
body.writeULEB128(func.params.length);
for (var i = 0; i < func.params.length; i += 1) {
writeName(body, func.params[i].name.name);
writeValType(body, paramCodes[i]);
}
body.writeByte(0x00);
writeValType(body, ownIndex);
return this.#declareType(scope, body);
}
/**
* The component-level function type of the world's function export
* `exportName`, for the lift of the core function implementing it.
* Its types are structural, like a world-level import's: a named
* type would need world-level `use` encoding.
*/
encodeWorldExportFuncType(worldName: String, exportName: String): i32 {
let world = this.#findWorld(worldName);
for (let item in expandedWorldItems(this.#ast, world)) {
if (item.tag != WorldItemTag.Export) { continue; }
let kind = (item.exportItem as Export).kind;
if (kind.tag != ExternKindTag.Func) { continue; }
if ((kind.name as Id).name != exportName) { continue; }
let func = kind.funcDef as Func;
let scope = new Scope();
scope.atComponentLevel = true;
scope.typeCount = this.#result.typeCount;
return this.#encodeFuncType(scope, func, -1, func.isAsync);
}
throw new EncodeError("world '" + worldName +
"' exports no function named '" + exportName + "'");
}
#findWorld(worldName: String): WorldDef {
for (let item in this.#ast.items) {
if (item.tag == AstItemTag.World) {
let def = item.worldDef as WorldDef;
if (def.name.name == worldName) {
return def;
}
}
}
throw new EncodeError(
`no world named '${worldName}' in this document`);
}
/** The registered interface named `qualified`, or null. */
#findRegistered(qualified: String): RegisteredInterface | null {
for (let reg in this.#interfaces) {
if (reg.qualifiedName == qualified) {
return reg;
}
}
return null;
}
/**
* The component-level type index of the type a `use` hop names: an
* alias out of the source's instance when the source is imported,
* or, when the source is an exported interface, its own declaration
* at component level (`#encodeExportedOwnType`), following a further
* `use` of the source's first. An exported interface may `use` a
* type another exported interface declares, as a plugin kind uses
* the resources of the views it vends.
*/
#usedTypeIndex(hop: UseHop): i32 {
if (this.#instanceIndex.has(hop.source)) {
return this.#aliasTypeExport(hop.source, hop.typeName);
}
let source = this.#findRegistered(hop.source);
if (source == null) {
throw new EncodeError(`'${hop.source}' is not a known interface`);
}
let further = this.#useSourceOf(source, hop.typeName);
if (further != null) {
return this.#usedTypeIndex(further);
}
return this.#encodeExportedOwnType(source, hop.typeName);
}
#aliasTypeExport(qualifiedInterface: String, typeName: String): i32 {
let key = `${qualifiedInterface}#${typeName}`;
if (let (true, existing) = this.#aliasedTypes.get(key)) {
return existing;
}
if (!this.#instanceIndex.has(qualifiedInterface)) {
throw new EncodeError("'" + qualifiedInterface +
"' is not imported yet, so nothing can use its types");
}
let alias = new ByteBuffer();
alias.writeULEB128(1);
alias.writeByte(0x03); // sort: type
alias.writeByte(0x00); // target: instance export
alias.writeULEB128(this.#instanceIndex[qualifiedInterface]);
writeName(alias, typeName);
this.#result.pieces.push(new SectionPiece(sectionAlias, alias));
let index = this.#result.typeCount;
this.#result.typeCount += 1;
this.#aliasedTypes[key] = index;
return index;
}
/** Export local type `index` under `name`; the export's own index. */
#exportType(scope: Scope, name: String, index: i32): i32 {
scope.decls.writeByte(0x04); // instancedecl: export
writeExternName(scope.decls, name);
scope.decls.writeByte(0x03); // externdesc: type
scope.decls.writeByte(0x00); // typebound: eq
scope.decls.writeULEB128(index);
scope.declCount += 1;
let exported = scope.typeCount;
scope.typeCount += 1;
return exported;
}
/** Declare an anonymous type from `body`; the index it gets. */
#declareType(scope: Scope, body: ByteBuffer): i32 {
let nestedDeclare = scope.nestedDeclare;
if (nestedDeclare != null) {
nestedDeclare(body);
} else if (scope.atComponentLevel) {
let section = new ByteBuffer();
section.writeULEB128(1);
section.writeBuffer(body);
this.#result.pieces.push(new SectionPiece(sectionType, section));
this.#result.typeCount += 1;
} else {
scope.decls.writeByte(0x01); // instancedecl: type
scope.decls.writeBuffer(body);
scope.declCount += 1;
}
let index = scope.typeCount;
scope.typeCount += 1;
return index;
}
#encodeTypeDef(scope: Scope, td: TypeDef): void {
let name = td.name.name;
scope.pending.delete(name);
if (td.tag == TypeDefTag.Resource) {
// A resource has no structure to declare — the export itself is
// the declaration, and `sub resource` is its bound.
scope.decls.writeByte(0x04);
writeExternName(scope.decls, name);
scope.decls.writeByte(0x03);
scope.decls.writeByte(0x01); // typebound: sub resource
scope.declCount += 1;
let resourceIndex = scope.typeCount;
scope.typeCount += 1;
scope.named[name] = resourceIndex;
scope.resourceIndices[resourceIndex] = true;
for (let rf in td.resourceFuncs as GrowableArray<ResourceFunc>) {
this.#encodeResourceFunc(scope, rf, name, resourceIndex);
}
return;
}
var code = 0;
if (td.tag == TypeDefTag.Record || td.tag == TypeDefTag.Variant ||
td.tag == TypeDefTag.Enum || td.tag == TypeDefTag.Flags) {
code = this.#encodeTypeBody(scope, td);
} else {
// `type name = t`: encode the target, and export an index for it.
// A primitive target still needs a declared type to bound the
// export to — `eq` takes an index, not an opcode. A named target
// is looked up raw so that `type b = bucket` aliases the resource
// itself rather than an `own` of it.
let target = td.aliasType as Type;
var isResource = false;
if (target.tag == TypeTag.Name) {
code = this.#namedIndex(scope, (target.name as Id).name);
isResource = scope.resourceIndices.has(code);
} else {
let encoded = this.#encodeType(scope, target);
if (encoded < 0) {
let body = new ByteBuffer();
body.writeByte(0 - encoded);
code = this.#declareType(scope, body);
} else {
code = encoded;
}
}
let exportedAlias = this.#exportType(scope, name, code);
scope.named[name] = exportedAlias;
if (isResource) {
scope.resourceIndices[exportedAlias] = true;
}
return;
}
scope.named[name] = this.#exportType(scope, name, code);
}
/** The declared index of a record, variant, enum or flags body in
* `scope`, its parts encoded first. */
#encodeTypeBody(scope: Scope, td: TypeDef): i32 {
var code = 0;
if (td.tag == TypeDefTag.Record) {
let fields = td.fields as GrowableArray<Field>;
let fieldCodes = new GrowableArray<i32>();
for (let f in fields) {
fieldCodes.push(this.#encodeType(scope, f.type));
}
let body = new ByteBuffer();
body.writeByte(0x72);
body.writeULEB128(fields.length);
for (var i = 0; i < fields.length; i += 1) {
writeName(body, fields[i].name.name);
writeValType(body, fieldCodes[i]);
}
code = this.#declareType(scope, body);
} else if (td.tag == TypeDefTag.Variant) {
let cases = td.cases as GrowableArray<Case>;
let caseCodes = new GrowableArray<i32>();
for (let c in cases) {
let payload = c.type;
caseCodes.push(
if (payload == null) 0 else this.#encodeType(scope, payload));
}
let body = new ByteBuffer();
body.writeByte(0x71);
body.writeULEB128(cases.length);
for (var i = 0; i < cases.length; i += 1) {
writeName(body, cases[i].name.name);
if (cases[i].type == null) {
body.writeByte(0x00); // no payload
} else {
body.writeByte(0x01);
writeValType(body, caseCodes[i]);
}
body.writeByte(0x00); // refines: none (the format still asks)
}
code = this.#declareType(scope, body);
} else if (td.tag == TypeDefTag.Enum) {
let cases = td.enumCases as GrowableArray<EnumCaseDef>;
let body = new ByteBuffer();
body.writeByte(0x6d);
body.writeULEB128(cases.length);
for (let c in cases) {
writeName(body, c.name.name);
}
code = this.#declareType(scope, body);
} else {
let flags = td.flags as GrowableArray<FlagDef>;
let body = new ByteBuffer();
body.writeByte(0x6e);
body.writeULEB128(flags.length);
for (let f in flags) {
writeName(body, f.name.name);
}
code = this.#declareType(scope, body);
}
return code;
}
/**
* A type expression, as a value-type code. Named constructors were
* handled by `#encodeTypeDef` — this resolves references to them and
* builds the anonymous ones, one declaration per distinct shape.
*/
#encodeType(scope: Scope, t: Type): i32 {
let prim = primOpcodeOf(t.tag);
if (prim >= 0) {
return primCode(prim);
}
if (t.tag == TypeTag.Name) {
let index = this.#namedIndex(scope, (t.name as Id).name);
if (scope.resourceIndices.has(index)) {
// A resource name in value position is a handle: `-> bucket`
// returns `own<bucket>`. The explicit `own`/`borrow` arms below
// are the ones that look the name up raw.
return this.#handleType(scope, 0x69, index);
}
return index;
}
if (t.tag == TypeTag.Future || t.tag == TypeTag.Stream) {
// `stream<T>`/`future<T>` — a handle to one end. The payload is
// optional in the grammar (`0x66 t?`), and the absent form is a
// real type (`future` alone signals completion), encoded as a
// present/absent byte like a defaulted case payload.
let opcode = if (t.tag == TypeTag.Stream) 0x66 else 0x65;
let innerType = t.inner;
var inner = -1;
var key = i32ToString(opcode) + "(";
if (innerType != null) {
inner = this.#encodeType(scope, innerType);
key = key + i32ToString(inner);
}
key = key + ")";
if (let (true, existing) = scope.anon.get(key)) {
return existing;
}
let body = new ByteBuffer();
body.writeByte(opcode);
if (innerType != null) {
body.writeByte(0x01);
writeValType(body, inner);
} else {
body.writeByte(0x00);
}
let index = this.#declareType(scope, body);
scope.anon[key] = index;
return index;
}
if (t.tag == TypeTag.Map) {
throw new EncodeError("map types are not encodable yet");
}
if (t.tag == TypeTag.ErrorContext) {
throw new EncodeError("error-context types are not encodable yet");
}
if (t.tag == TypeTag.List && t.fixedLength >= 0) {
throw new EncodeError("fixed-length lists are not encodable yet");
}
if (t.tag == TypeTag.List || t.tag == TypeTag.Option) {
let inner = this.#encodeType(scope, t.inner as Type);
let opcode = if (t.tag == TypeTag.List) 0x70 else 0x6b;
let key = `${i32ToString(opcode)}(${i32ToString(inner)})`;
if (let (true, existing) = scope.anon.get(key)) {
return existing;
}
let body = new ByteBuffer();
body.writeByte(opcode);
writeValType(body, inner);
let index = this.#declareType(scope, body);
scope.anon[key] = index;
return index;
}
if (t.tag == TypeTag.Own || t.tag == TypeTag.Borrow) {
let inner = t.inner as Type;
if (inner.tag != TypeTag.Name) {
throw new EncodeError("own/borrow take a resource by name");
}
let resource = this.#namedIndex(scope, (inner.name as Id).name);
let opcode = if (t.tag == TypeTag.Own) 0x69 else 0x68;
return this.#handleType(scope, opcode, resource);
}
if (t.tag == TypeTag.Tuple) {
let members = t.types as GrowableArray<Type>;
let codes = new GrowableArray<i32>();
var key = "tuple(";
for (let m in members) {
let c = this.#encodeType(scope, m);
codes.push(c);
key = `${key}${i32ToString(c)},`;
}
key = key + ")";
if (let (true, existing) = scope.anon.get(key)) {
return existing;
}
let body = new ByteBuffer();
body.writeByte(0x6f);
body.writeULEB128(codes.length);
for (let c in codes) {
writeValType(body, c);
}
let index = this.#declareType(scope, body);
scope.anon[key] = index;
return index;
}
if (t.tag == TypeTag.Result) {
let ok = t.okType;
let err = t.errType;
let okCode = if (ok == null) 0 else this.#encodeType(scope, ok);
let errCode = if (err == null) 0 else this.#encodeType(scope, err);
let key = "result(" + (if (ok == null) "" else i32ToString(okCode)) +
"," + (if (err == null) "" else i32ToString(errCode)) + ")";
if (let (true, existing) = scope.anon.get(key)) {
return existing;
}
let body = new ByteBuffer();
body.writeByte(0x6a);
if (ok == null) {
body.writeByte(0x00);
} else {
body.writeByte(0x01);
writeValType(body, okCode);
}
if (err == null) {
body.writeByte(0x00);
} else {
body.writeByte(0x01);
writeValType(body, errCode);
}
let index = this.#declareType(scope, body);
scope.anon[key] = index;
return index;
}
throw new EncodeError("unhandled type tag in the WIT encoder");
}
/**
* A function type declaration; the index it gets. `selfBorrow` is a
* borrow handle's index for a method and -1 otherwise.
*/
#encodeFuncType(
scope: Scope,
func: Func,
selfBorrow: i32,
isAsync: boolean
): i32 {
let paramCodes = new GrowableArray<i32>();
for (let p in func.params) {
paramCodes.push(this.#encodeType(scope, p.type));
}
let result = func.result;
let resultCode =
if (result == null) 0 else this.#encodeType(scope, result);
let body = new ByteBuffer();
body.writeByte(if (isAsync) 0x43 else 0x40);
body.writeULEB128(
func.params.length + (if (selfBorrow >= 0) 1 else 0));
if (selfBorrow >= 0) {
writeName(body, "self");
writeValType(body, selfBorrow);
}
for (var i = 0; i < func.params.length; i += 1) {
writeName(body, func.params[i].name.name);
writeValType(body, paramCodes[i]);
}
if (result == null) {
body.writeByte(0x01); // the named-results arm of resultlist,
body.writeByte(0x00); // holding none
} else {
body.writeByte(0x00); // one unnamed result
writeValType(body, resultCode);
}
return this.#declareType(scope, body);
}
#exportFunc(scope: Scope, name: String, typeIndex: i32): void {
scope.decls.writeByte(0x04);
writeExternName(scope.decls, name);
scope.decls.writeByte(0x01); // externdesc: func
scope.decls.writeULEB128(typeIndex);
scope.declCount += 1;
}
#encodeInterfaceFunc(
scope: Scope,
nf: NamedFunc,
exportPrefix: String,
selfBorrow: i32
): void {
let typeIndex =
this.#encodeFuncType(scope, nf.func, selfBorrow, nf.func.isAsync);
this.#exportFunc(scope, exportPrefix + nf.name.name, typeIndex);
}
#encodeResourceFunc(
scope: Scope,
rf: ResourceFunc,
resourceName: String,
resourceIndex: i32
): void {
if (rf.tag == ResourceFuncTag.Constructor) {
// A constructor's declared result is nothing; its real one is
// `own` of the resource it builds.
let ownIndex = this.#handleType(scope, 0x69, resourceIndex);
let func = rf.func.func;
let paramCodes = new GrowableArray<i32>();
for (let p in func.params) {
paramCodes.push(this.#encodeType(scope, p.type));
}
let body = new ByteBuffer();
body.writeByte(0x40);
body.writeULEB128(func.params.length);
for (var i = 0; i < func.params.length; i += 1) {
writeName(body, func.params[i].name.name);
writeValType(body, paramCodes[i]);
}
body.writeByte(0x00);
writeValType(body, ownIndex);
let typeIndex = this.#declareType(scope, body);
this.#exportFunc(scope, "[constructor]" + resourceName, typeIndex);
} else if (rf.tag == ResourceFuncTag.Method) {
let borrowIndex = this.#handleType(scope, 0x68, resourceIndex);
this.#encodeInterfaceFunc(scope, rf.func,
`[method]${resourceName}.`, borrowIndex);
} else {
this.#encodeInterfaceFunc(scope, rf.func,
`[static]${resourceName}.`, -1);
}
}
/** The index `name` exports here, with no handle wrapping. */
#namedIndex(scope: Scope, name: String): i32 {
if (let (true, index) = scope.named.get(name)) {
return index;
}
let nestedNamed = scope.nestedNamed;
if (nestedNamed != null) {
return nestedNamed(name);
}
if (let (true, td) = scope.pending.get(name)) {
// Declared later in the interface: encode it now, first use
// being the encoding order.
this.#encodeTypeDef(scope, td);
return scope.named[name];
}
let source = scope.aliasSource;
if (source != null) {
let reg = source;
if (!this.#declaresType(reg, name)) {
throw new EncodeError("'" + reg.qualifiedName +
"' declares no type '" + name + "'");
}
// An imported interface's types alias out of its instance. An
// exported interface has no instance to alias from; a type it
// `use`s comes from its source instead, under the source's own
// name for it: an alias out of an imported source's instance, or
// an exported source's own component-level declaration.
var index = -1;
if (this.#instanceIndex.has(reg.qualifiedName)) {
index = this.#aliasTypeExport(reg.qualifiedName, name);
} else {
let hop = this.#useSourceOf(reg, name);
if (hop == null) {
// The exported interface's own declaration: encoded at
// component level, and exported from its instance.
index = this.#encodeExportedOwnType(reg, name);
} else {
index = this.#usedTypeIndex(hop);
}
}
// The alias appended a component-level type; a component-level
// scope counts the same index space, so it catches up.
scope.typeCount = this.#result.typeCount;
scope.named[name] = index;
if (this.#isResource(reg, name)) {
scope.resourceIndices[index] = true;
}
return index;
}
if (scope.atComponentLevel) {
throw new EncodeError("a world-level function names type '" +
name + "', which needs world-level `use` encoding");
}
throw new EncodeError(`type '${name}' is not declared in this interface`);
}
/**
* The component-level type index of `name`, a type the exported
* interface `reg` declares itself, encoding it on first use — its
* body as a component-level type, its named parts resolved against
* the interface the same way (a record's enum field, a variant's
* record payload) — and recording it for the instance to export. A
* resource is a component-level resource type whose representation
* is an `i32` — the index into the entry wrapper's table of the
* program's instances — which the canon `resource.new` and
* `resource.rep` builtins mint handles for and read back. Its
* destructor is a shim trampoline (`DtorSlot`): the program's own
* destructor lives in an instance that cannot exist before this type
* does, since the core module imports `resource.new` for it.
*/
#encodeExportedOwnType(reg: RegisteredInterface, name: String): i32 {
let key = `${reg.qualifiedName}#own:${name}`;
if (let (true, existing) = this.#aliasedTypes.get(key)) {
return existing;
}
var found: TypeDef | null = null;
for (let item in reg.items) {
if (item.tag != InterfaceItemTag.TypeDef) { continue; }
let td = item.typeDef as TypeDef;
if (td.name.name == name) { found = td; }
}
if (found == null) {
throw new EncodeError(`'${reg.qualifiedName}' declares no type '${name}'`);
}
let td = found;
let scope = new Scope();
scope.atComponentLevel = true;
scope.typeCount = this.#result.typeCount;
scope.aliasSource = reg;
var index = -1;
if (td.tag == TypeDefTag.Resource) {
// The destructor is core function `slot`: the emitter's shim
// trampoline for this resource (see `DtorSlot`).
let slot = this.#result.dtorSlots.length;
this.#result.dtorSlots.push(new DtorSlot(reg.qualifiedName, name));
let body = new ByteBuffer();
body.writeByte(0x3f); // resource
body.writeByte(0x7f); // rep: i32
body.writeByte(0x01); // a destructor:
body.writeULEB128(slot);
index = this.#declareType(scope, body);
} else if (td.tag == TypeDefTag.Alias) {
let target = td.aliasType as Type;
if (target.tag == TypeTag.Name) {
index = this.#namedIndex(scope, (target.name as Id).name);
} else {
let encoded = this.#encodeType(scope, target);
if (encoded < 0) {
// A primitive alias still needs a declared type for the
// instance to export under the name.
let body = new ByteBuffer();
body.writeByte(0 - encoded);
index = this.#declareType(scope, body);
} else {
index = encoded;
}
}
} else {
index = this.#encodeTypeBody(scope, td);
}
this.#aliasedTypes[key] = index;
let list = if (let (true, l) = this.#result.exportedTypes.get(
reg.qualifiedName)) l else new GrowableArray<ExportedTypeIndex>();
list.push(new ExportedTypeIndex(name, index));
this.#result.exportedTypes[reg.qualifiedName] = list;
return index;
}
/** Whether `reg` declares `name` — as a type definition or a `use`d
* name — so an alias export of it can be valid. */
#declaresType(reg: RegisteredInterface, name: String): boolean {
for (let item in reg.items) {
if (item.tag == InterfaceItemTag.TypeDef) {
if ((item.typeDef as TypeDef).name.name == name) {
return true;
}
} else if (item.tag == InterfaceItemTag.Use) {
for (let n in (item.use as Use).names) {
let asName = n.asName;
let localName =
asName?.name ?? n.name.name;
if (localName == name) {
return true;
}
}
}
}
return false;
}
/** An `own`/`borrow` of `resourceIndex`, deduplicated like any anon. */
#handleType(scope: Scope, opcode: i32, resourceIndex: i32): i32 {
let key = `${i32ToString(opcode)}(${i32ToString(resourceIndex)})`;
if (let (true, existing) = scope.anon.get(key)) {
return existing;
}
let body = new ByteBuffer();
body.writeByte(opcode);
body.writeULEB128(resourceIndex); // an index position: unsigned
let index = this.#declareType(scope, body);
scope.anon[key] = index;
return index;
}
}
/** `ns:pkg/name@version`, or the bare name when there is no package. */
export function qualifiedInterfaceName(
pkg: PackageName | null,
interfaceName: String
): String {
if (pkg == null) {
return interfaceName;
}
let p = pkg;
var name = `${p.namespace.name}:${p.name.name}/${interfaceName}`;
let version = p.version;
if (version != null) {
name = `${name}@${version}`;
}
return name;
}
function externName(kind: ExternKind): String {
if (kind.tag == ExternKindTag.Path) {
return (kind.path as UsePath).getName().name;
}
return (kind.name as Id).name;
}
// ============================================================================
// Canonical flattening metadata
// ============================================================================
/**
* How a WIT type crosses the core boundary: how many flat core values
* it occupies, and whether it needs linear memory to cross at all.
*
* This is the *counting* half of the canonical ABI's `flatten` — enough
* to decide two things a `canon lower` depends on: whether the options
* must name a memory and a realloc (a `string` or `list` anywhere in
* the signature), and whether the result is returned indirectly
* (flattened results exceeding one mean the caller passes a return
* area's address as a trailing `i32` parameter, and so does a
* parameter list flattening past sixteen).
*/
export final class WitFlatMeta {
// No field initializers: a defaulted `this.x` parameter on a field
// that also has an initializer fails ZIR lowering ("auto-box to
// any") — see elematic/zena#102.
var flatCount: i32;
var needsMemory: boolean;
new(this.flatCount = 0, this.needsMemory = false);
}
/** One function's flattening, plus whether the lookup found it at all. */
export final class WitFuncMeta {
var paramFlatCount = 0;
var resultFlatCount = 0;
/** Whether lowering this function needs the canonical memory options. */
var needsMemory = false;
/** Whether the WIT declares the function `async`. */
var isAsync = false;
}
/** One interface, as the flattening walker sees the document. */
final class FlatIface {
name: String;
items: Array<InterfaceItem>;
new(this.name, this.items);
}
function flatMetaOfType(
interfaces: Array<FlatIface>,
owner: FlatIface,
t: Type
): WitFlatMeta {
let prim = primOpcodeOf(t.tag);
if (prim >= 0) {
if (t.tag == TypeTag.String) {
return new WitFlatMeta(2, true);
}
return new WitFlatMeta(1, false);
}
if (t.tag == TypeTag.List) {
return new WitFlatMeta(2, true);
}
if (t.tag == TypeTag.Own || t.tag == TypeTag.Borrow) {
return new WitFlatMeta(1, false);
}
if (t.tag == TypeTag.Tuple) {
let meta = new WitFlatMeta();
for (let m in t.types as GrowableArray<Type>) {
let inner = flatMetaOfType(interfaces, owner, m);
meta.flatCount += inner.flatCount;
if (inner.needsMemory) { meta.needsMemory = true; }
}
return meta;
}
if (t.tag == TypeTag.Option) {
let inner = flatMetaOfType(interfaces, owner, t.inner as Type);
return new WitFlatMeta(1 + inner.flatCount, inner.needsMemory);
}
if (t.tag == TypeTag.Result) {
// A variant of two cases: the discriminant, then the larger payload
// (the join's *count* is the maximum; the exact core types do not
// matter for what this decides).
var payload = 0;
var mem = false;
let ok = t.okType;
if (ok != null) {
let m = flatMetaOfType(interfaces, owner, ok);
payload = m.flatCount;
if (m.needsMemory) { mem = true; }
}
let err = t.errType;
if (err != null) {
let m = flatMetaOfType(interfaces, owner, err);
if (m.flatCount > payload) { payload = m.flatCount; }
if (m.needsMemory) { mem = true; }
}
return new WitFlatMeta(1 + payload, mem);
}
if (t.tag == TypeTag.Name) {
return flatMetaOfName(interfaces, owner, (t.name as Id).name);
}
// stream/future: a handle end, one core i32, no memory of its own —
// the real answer, not a fallback. map/error-context: the encoder
// still refuses those before metadata is asked for; one word keeps a
// caller that asks anyway from being lied to about memory.
return new WitFlatMeta(1, false);
}
function flatMetaOfName(
interfaces: Array<FlatIface>,
owner: FlatIface,
name: String
): WitFlatMeta {
for (let item in owner.items) {
if (item.tag == InterfaceItemTag.TypeDef) {
let td = item.typeDef as TypeDef;
if (td.name.name != name) { continue; }
if (td.tag == TypeDefTag.Resource) {
// A resource name in value position is a handle.
return new WitFlatMeta(1, false);
}
if (td.tag == TypeDefTag.Enum || td.tag == TypeDefTag.Flags) {
return new WitFlatMeta(1, false);
}
if (td.tag == TypeDefTag.Record) {
let meta = new WitFlatMeta();
for (let f in td.fields as GrowableArray<Field>) {
let inner = flatMetaOfType(interfaces, owner, f.type);
meta.flatCount += inner.flatCount;
if (inner.needsMemory) { meta.needsMemory = true; }
}
return meta;
}
if (td.tag == TypeDefTag.Variant) {
var payload = 0;
var mem = false;
for (let c in td.cases as GrowableArray<Case>) {
let payloadType = c.type;
if (payloadType != null) {
let m = flatMetaOfType(interfaces, owner, payloadType);
if (m.flatCount > payload) { payload = m.flatCount; }
if (m.needsMemory) { mem = true; }
}
}
return new WitFlatMeta(1 + payload, mem);
}
return flatMetaOfType(interfaces, owner, td.aliasType as Type);
} else if (item.tag == InterfaceItemTag.Use) {
let use = item.use as Use;
for (let n in use.names) {
let asName = n.asName;
let localName =
asName?.name ?? n.name.name;
if (localName != name) { continue; }
// The wanted interface, package-qualified. A bare `use foo`
// means the OWNER's package's `foo` — matching by trailing
// name alone resolved wasi:http/client's `use types` to
// wasi:cli/types, whichever registered first — and a
// package-path use spells its package outright.
let sourceName = use.from.getName().name;
let from = use.from;
var wantPackage = "";
if (from is PackageUsePath) {
let p = from.packageId as PackageName;
wantPackage = `${p.namespace.name}:${p.name.name}`;
} else {
var slashAt = -1;
for (var i = 0; i < owner.name.length; i += 1) {
if (owner.name.getByteAt(i) == 47) { slashAt = i; } // '/'
}
if (slashAt > 0) {
wantPackage = owner.name.sliceBytes(0, slashAt);
}
}
let want = `${wantPackage}/${sourceName}`;
for (let iface in interfaces) {
if (iface.name == want || iface.name.startsWith(want + "@")) {
return flatMetaOfName(interfaces, iface, n.name.name);
}
}
}
}
}
var known = "";
for (let iface in interfaces) {
known = `${known} ${iface.name}`;
}
throw new EncodeError("flattening cannot resolve type '" + name +
"' (interfaces:" + known + ")");
}
function funcMetaOf(
interfaces: Array<FlatIface>,
owner: FlatIface,
func: Func,
selfParams: i32
) {
let meta = new WitFuncMeta();
meta.isAsync = func.isAsync;
meta.paramFlatCount = selfParams;
for (let p in func.params) {
let m = flatMetaOfType(interfaces, owner, p.type);
meta.paramFlatCount += m.flatCount;
if (m.needsMemory) { meta.needsMemory = true; }
}
let result = func.result;
if (result != null) {
let m = flatMetaOfType(interfaces, owner, result);
meta.resultFlatCount = m.flatCount;
if (m.needsMemory) { meta.needsMemory = true; }
}
if (meta.paramFlatCount > 16 || meta.resultFlatCount > 1) {
// Spilled parameters land in memory; an indirect result needs a
// return area. Either way the options must say where.
meta.needsMemory = true;
}
if (meta.isAsync &&
(meta.resultFlatCount > 0 || meta.paramFlatCount > 4)) {
// The async lowering spills any result through a return area, and
// parameters past four core values through one pointer.
meta.needsMemory = true;
}
return meta;
}
/**
* The flattening of one function of one interface, by the names a core
* module imports them under — the qualified interface, and the field
* (`get-stdout`, `[method]output-stream.blocking-write-and-flush`).
* Null when the interface or the function is not in the document,
* which callers treat as its own loud error.
*/
/** Every interface of the document, main package and nested. */
function registeredFlatIfaces(ast: Ast) {
let interfaces = new GrowableArray<FlatIface>();
let register = (pkg: PackageName | null, items: Array<AstItem>) => {
for (let item in items) {
if (item.tag == AstItemTag.Interface) {
let def = item.interfaceDef as InterfaceDef;
interfaces.push(new FlatIface(
qualifiedInterfaceName(pkg, def.name.name), def.items));
}
}
};
register(ast.packageName, ast.items);
for (let nested in ast.nestedPackages) {
register(nested.name, nested.items);
}
return interfaces;
}
/**
* An export's flattening: the lift moves parameters and result
* through memory when a type of theirs does, or when either spills
* past sixteen core values. An async import's result spills through a
* return area; an async export's goes through `task.return`, whose
* flat parameters carry it, so the import rule does not apply.
*/
function exportMetaOf(
interfaces: Array<FlatIface>,
owner: FlatIface,
func: Func,
selfParams: i32 = 0
) {
let meta = new WitFuncMeta();
meta.isAsync = func.isAsync;
meta.paramFlatCount = selfParams;
for (let p in func.params) {
let m = flatMetaOfType(interfaces, owner, p.type);
meta.paramFlatCount += m.flatCount;
if (m.needsMemory) { meta.needsMemory = true; }
}
let result = func.result;
if (result != null) {
let m = flatMetaOfType(interfaces, owner, result);
meta.resultFlatCount = m.flatCount;
if (m.needsMemory) { meta.needsMemory = true; }
}
if (meta.paramFlatCount > 16 || meta.resultFlatCount > 16) {
meta.needsMemory = true;
}
return meta;
}
/**
* The flattening of the world's function export `exportName`, or null
* when the world exports no function by that name. A world-level
* function's types are structural, so they resolve against no
* interface.
*
* The memory need is an export's, not an import's: the lift moves
* parameters and result through memory when a type of theirs does, or
* when either spills past sixteen core values. An async import's
* result spills through a return area; an async export's goes through
* `task.return`, whose flat parameters carry it.
*/
export function worldFuncFlatMeta(
ast: Ast,
worldName: String,
exportName: String
): WitFuncMeta | null {
let interfaces = new GrowableArray<FlatIface>();
for (let item in ast.items) {
if (item.tag == AstItemTag.Interface) {
let def = item.interfaceDef as InterfaceDef;
interfaces.push(new FlatIface(
qualifiedInterfaceName(ast.packageName, def.name.name),
def.items));
}
}
let owner = new FlatIface("", new GrowableArray<InterfaceItem>());
for (let item in ast.items) {
if (item.tag != AstItemTag.World) { continue; }
let def = item.worldDef as WorldDef;
if (def.name.name != worldName) { continue; }
for (let wi in expandedWorldItems(ast, def)) {
if (wi.tag != WorldItemTag.Export) { continue; }
let kind = (wi.exportItem as Export).kind;
if (kind.tag != ExternKindTag.Func) { continue; }
if ((kind.name as Id).name != exportName) { continue; }
return exportMetaOf(interfaces, owner, kind.funcDef as Func);
}
}
return null;
}
/**
* The flattening of `funcName` in the exported interface
* `interfaceName`, or null when no such function exists. The memory
* need is an export's, as `worldFuncFlatMeta` computes it.
*/
export function interfaceExportFlatMeta(
ast: Ast,
interfaceName: String,
funcName: String
): WitFuncMeta | null {
let interfaces = registeredFlatIfaces(ast);
for (let iface in interfaces) {
if (iface.name != interfaceName) { continue; }
for (let item in iface.items) {
if (item.tag != InterfaceItemTag.Func) { continue; }
let nf = item.func as NamedFunc;
if (nf.name.name == funcName) {
return exportMetaOf(interfaces, iface, nf.func);
}
}
// A resource's function under its mangled export name: a method's
// `self` is one core value, and a constructor returns the handle.
let found = resourceFuncNamed(iface.items, funcName);
if (found != null) {
let rf = found.rf;
let selfParams = if (rf.tag == ResourceFuncTag.Method) 1 else 0;
let meta = exportMetaOf(interfaces, iface, rf.func.func, selfParams);
if (rf.tag == ResourceFuncTag.Constructor) {
meta.resultFlatCount = 1; // the own handle
}
return meta;
}
}
return null;
}
/** A resource's function found by its mangled export name. */
final class NamedResourceFunc {
resourceName: String;
rf: ResourceFunc;
new(this.resourceName, this.rf);
}
/**
* The resource function `items` exports as `fieldName` — a
* `[constructor]r`, `[method]r.f` or `[static]r.f` — or null.
*/
function resourceFuncNamed(items: Array<InterfaceItem>,
fieldName: String): NamedResourceFunc | null {
for (let item in items) {
if (item.tag != InterfaceItemTag.TypeDef) { continue; }
let td = item.typeDef as TypeDef;
if (td.tag != TypeDefTag.Resource) { continue; }
let resourceName = td.name.name;
for (let rf in td.resourceFuncs as GrowableArray<ResourceFunc>) {
let exported = if (rf.tag == ResourceFuncTag.Constructor) {
"[constructor]" + resourceName
} else if (rf.tag == ResourceFuncTag.Method) {
`[method]${resourceName}.${rf.func.name.name}`
} else {
`[static]${resourceName}.${rf.func.name.name}`
};
if (exported == fieldName) {
return new NamedResourceFunc(resourceName, rf);
}
}
}
return null;
}
export function funcFlatMeta(
ast: Ast,
interfaceName: String,
fieldName: String
): WitFuncMeta | null {
let interfaces = new GrowableArray<FlatIface>();
let register = (pkg: PackageName | null, items: Array<AstItem>) => {
for (let item in items) {
if (item.tag == AstItemTag.Interface) {
let def = item.interfaceDef as InterfaceDef;
interfaces.push(new FlatIface(
qualifiedInterfaceName(pkg, def.name.name), def.items));
}
}
};
register(ast.packageName, ast.items);
for (let nested in ast.nestedPackages) {
register(nested.name, nested.items);
}
for (let iface in interfaces) {
if (iface.name != interfaceName) { continue; }
for (let item in iface.items) {
if (item.tag == InterfaceItemTag.Func) {
let nf = item.func as NamedFunc;
if (nf.name.name == fieldName) {
return funcMetaOf(interfaces, iface, nf.func, 0);
}
} else if (item.tag == InterfaceItemTag.TypeDef) {
let td = item.typeDef as TypeDef;
if (td.tag != TypeDefTag.Resource) { continue; }
let resourceName = td.name.name;
for (let rf in td.resourceFuncs as GrowableArray<ResourceFunc>) {
var exported = "";
var selfParams = 0;
if (rf.tag == ResourceFuncTag.Constructor) {
exported = "[constructor]" + resourceName;
} else if (rf.tag == ResourceFuncTag.Method) {
exported = `[method]${resourceName}.${rf.func.name.name}`;
selfParams = 1;
} else {
exported = `[static]${resourceName}.${rf.func.name.name}`;
}
if (exported != fieldName) { continue; }
let meta =
funcMetaOf(interfaces, iface, rf.func.func, selfParams);
if (rf.tag == ResourceFuncTag.Constructor) {
meta.resultFlatCount = 1; // the own handle
}
return meta;
}
}
}
return null;
}
return null;
}
/**
* The items of `world`, a world of the document's main package, with
* every `include` expanded in place: the included world's imports and
* exports, its own includes expanded too, in order. An include names a
* world of the including world's package by a bare name, or of another
* package by path. An item that an included world names an interface by
* a bare name means that world's package's interface, so its path comes
* back qualified with the package. An import or export that two
* includes both bring is kept once, as WIT merges them. An item gated
* `@unstable(feature = ...)` is left out, as WIT tooling leaves it out
* while no feature is enabled: `wasi:clocks/imports` gates `timezone`,
* which hosts do not provide.
*/
export function expandedWorldItems(ast: Ast, world: WorldDef): GrowableArray<WorldItem> {
let out = new GrowableArray<WorldItem>();
appendWorldItems(ast, world, ast.packageName, false, out,
new GrowableArray<String>(), 0);
return out;
}
function appendWorldItems(ast: Ast, world: WorldDef, pkg: PackageName | null,
included: boolean, out: GrowableArray<WorldItem>, seen: GrowableArray<String>,
depth: i32): void {
if (depth > 32) {
throw new EncodeError(`world '${world.name.name}' includes itself`);
}
for (let item in world.items) {
if (item.tag == WorldItemTag.Include) {
let inc = item.include as Include;
if (isUnstable(inc.docs)) { continue; }
if (inc.names.length > 0) {
throw new EncodeError("an `include` that renames with `with` is not encodable yet");
}
let from = inc.from;
if (from.tag == UsePathTag.Id) {
let name = (from.id as Id).name;
appendWorldItems(ast, findPackageWorld(ast, pkg, name), pkg, true, out, seen,
depth + 1);
} else {
let fromPkg = from.packageId as PackageName;
appendWorldItems(ast, findPackageWorld(ast, fromPkg, (from.name as Id).name),
fromPkg, true, out, seen, depth + 1);
}
continue;
}
if (item.tag != WorldItemTag.Import && item.tag != WorldItemTag.Export) {
out.push(item);
continue;
}
let isImport = item.tag == WorldItemTag.Import;
let docs = if (isImport) (item.importItem as Import).docs
else (item.exportItem as Export).docs;
if (isUnstable(docs)) { continue; }
let kind = if (isImport) (item.importItem as Import).kind
else (item.exportItem as Export).kind;
let key = `${if (isImport) 'import' else 'export'} ${externKey(kind, pkg)}`;
var known = false;
for (let k in seen) {
if (k == key) { known = true; }
}
if (known) { continue; }
seen.push(key);
let path = kind.path;
if (!included || kind.tag != ExternKindTag.Path || path == null ||
path.tag != UsePathTag.Id || pkg == null) {
out.push(item);
continue;
}
let qualified = ExternKind.fromPath(UsePath.fromPackage(pkg, path.id as Id));
out.push(if (isImport) {
WorldItem.fromImport(new Import((item.importItem as Import).docs, qualified))
} else {
WorldItem.fromExport(new Export((item.exportItem as Export).docs, qualified))
});
}
}
/** Whether an item is gated behind a feature with `@unstable`. */
function isUnstable(docs: Docs): boolean {
let attributes = docs.attributes;
if (attributes == null) {
return false;
}
for (let attribute in attributes) {
if (attribute.tag == AttributeTag.Unstable) {
return true;
}
}
return false;
}
/** What identifies an import or export: its qualified interface, or its name. */
function externKey(kind: ExternKind, pkg: PackageName | null): String {
let path = kind.path;
if (kind.tag == ExternKindTag.Path && path != null) {
return if (path.tag == UsePathTag.Id) {
qualifiedInterfaceName(pkg, (path.id as Id).name)
} else {
qualifiedInterfaceName(path.packageId, (path.name as Id).name)
};
}
return (kind.name as Id).name;
}
/** The world named `name` in package `pkg`: the main one, or a nested one. */
function findPackageWorld(ast: Ast, pkg: PackageName | null, name: String): WorldDef {
let wanted = qualifiedInterfaceName(pkg, name);
if (qualifiedInterfaceName(ast.packageName, name) == wanted) {
for (let item in ast.items) {
if (item.tag == AstItemTag.World && (item.worldDef as WorldDef).name.name == name) {
return item.worldDef as WorldDef;
}
}
}
for (let nested in ast.nestedPackages) {
if (qualifiedInterfaceName(nested.name, name) != wanted) { continue; }
for (let item in nested.items) {
if (item.tag == AstItemTag.World && (item.worldDef as WorldDef).name.name == name) {
return item.worldDef as WorldDef;
}
}
}
throw new EncodeError(`no world '${wanted}' to include in this document`);
}
/** The names of the worlds the document's main package defines. */
export function worldNames(ast: Ast): Array<String> {
let names = new GrowableArray<String>();
for (let item in ast.items) {
if (item.tag == AstItemTag.World) {
names.push((item.worldDef as WorldDef).name.name);
}
}
return names;
}
/** A world's encoding, plus the bytes as a complete component. */
export final class TypesOnlyComponent {
bytes: ByteBuffer;
encoded: EncodedWorld;
new(this.bytes, this.encoded);
}
/**
* The pieces as a complete, importing-only component: the head sections
* with nothing behind them. Valid on its own — which is the point, as
* `wasm-tools component wit` will read the world back out of it.
*/
export function encodeTypesOnlyComponent(
ast: Ast,
worldName: String
): TypesOnlyComponent {
let encoder = new ComponentTypeEncoder(ast);
let encoded = encoder.encodeWorld(worldName);
let out = new ByteBuffer();
out.writeU32(0x6D736100); // \0asm
out.writeU32(0x0001000D); // version 0x0d, layer 1: a component
for (let piece in encoded.pieces) {
out.writeByte(piece.id);
out.writeULEB128(piece.payload.length);
out.writeBuffer(piece.payload);
}
return new TypesOnlyComponent(out, encoded);
}
| Version | Published | Dependencies | Approved by |
|---|---|---|---|
| 0.0.1-preview.1 | 2026-11-19 | none |
|