Ast

Ast carries an ESTree Program, the source text its spans anchor to, optional language metadata, and an optional incremental source map. Every AST-bearing hook receives an Ast.

type AstOptions = {
    program: Program;
    source: string;
    language?: Language;
    map?: SourceMap;
};

class Ast {
    constructor(options: AstOptions);

    get program(): DeepReadonly<Program>;
    get source(): Readonly<string>;
    get language(): Language | void;
    get sourceType(): SourceType;
    get map(): DeepReadonly<SourceMap> | null;

    mutate<Result extends void | Promise<void>>(
        fn: (program: Program) => Result,
    ): Result;
}

ConstructorCopy Anchor Link

MembersCopy Anchor Link

sourceType is a read-through of ast.program.sourceType; it never returns "unambiguous". There is no stored source-type field, so changes made through Ast.mutate are reflected immediately.

When an entry point resolves a grammar, explicit options.language wins over Ast.language, which wins over the file extension.

The program getter is typed as DeepReadonly<Program>, so nested nodes and arrays cannot be changed through it.

mutate returns void for a synchronous callback and Promise<void> for an asynchronous one. The returned value matches the callback, so await ast.mutate(fn) works in both cases.

MutationCopy Anchor Link

Only the transform hook carries mutations forward: mutate args.ast and return { ast: args.ast } to replace the compiler's AST for the rest of the chain. Returning nothing discards the mutation.

The prepare, finalize, and generate hooks receive a snapshot of the compiler's AST. Mutating that snapshot changes only the local instance and does not alter the compiler's AST. A generate hook can pass a mutated AST to createGenerator to generate from it.

ExampleCopy Anchor Link

import type { AstResult } from "telarel";

import { parse } from "telarel";

const { ast }: AstResult = await parse("const x: number = 1;");

ast.mutate((program): void => {
    program.body.length = 0;
});