@r4ai/typst-ast-node 0.2.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # typst-ast
 
-A WebAssembly library that parses [Typst](https://typst.app/) source code and returns its AST as a JSON-serializable object. Built with Rust and [`typst-syntax`](https://crates.io/crates/typst-syntax), distributed as npm packages via `wasm-pack`.
+A WebAssembly library that parses [Typst](https://typst.app/) source code and returns its CST/AST as a JSON-serializable object. Built with Rust and [`typst-syntax`](https://crates.io/crates/typst-syntax), distributed as npm packages via `wasm-pack`.
 
 ## Packages
 
@@ -14,14 +14,27 @@ A WebAssembly library that parses [Typst](https://typst.app/) source code and re
 ### Browser
 
 ```ts
-import init, { parse } from "@r4ai/typst-ast-web";
+import init, { parse, parseAst } from "@r4ai/typst-ast-web";
 
 await init();
 
-const result = parse("= Hello\n\nThis is *typst*.", { mode: "markup" });
-console.log(result);
+// CST (Concrete Syntax Tree)
+const cst = parse("= Hello\n\nThis is *typst*.", { mode: "markup" });
+console.log(cst);
 // {
-//   root: { kind: "Markup", range: [0, 26], text: null, children: [...] },
+//   root: { kind: "Markup", range: [0, 25], children: [...] },
+//   errors: []
+// }
+
+// AST (Abstract Syntax Tree)
+const ast = parseAst("= Hello\n\nThis is *typst*.", { mode: "markup" });
+console.log(ast);
+// {
+//   root: [
+//     { kind: "heading", ... },
+//     { kind: "parbreak", ... },
+//     ...
+//   ],
 //   errors: []
 // }
 ```
@@ -29,44 +42,60 @@ console.log(result);
 ### Node.js
 
 ```ts
-import { parse } from "@r4ai/typst-ast-node";
+import { parse, parseAst } from "@r4ai/typst-ast-node";
 
-const result = parse("#let x = 1 + 2", { mode: "code" });
-console.log(result);
+const cst = parse("#let x = 1 + 2", { mode: "code" });
+const ast = parseAst("#let x = 1 + 2", { mode: "code" });
 ```
 
 ### API
 
-#### `parse(text, options?)`
-
-Parses Typst source text and returns the AST.
-
-**Parameters**
+Both functions accept the same parameters:
 
 - `text: string` — Typst source code to parse
 - `options.mode?: "markup" | "code" | "math"` — Parse mode (default: `"markup"`)
 
-**Return value**
+#### `parse(text, options?)`
+
+Returns the CST (Concrete Syntax Tree) — a lossless syntax tree that preserves all tokens including whitespace and punctuation.
 
 ```ts
-type ParseResult = {
-  root: Node;
+interface ParseResult {
+  root: SyntaxNode;
   errors: ParseError[];
-};
+}
 
-type Node = {
-  kind: string; // SyntaxKind variant name (e.g. "Markup", "Heading", "Strong")
-  range: [number, number]; // [start, end] byte offsets
-  text: string | null; // leaf node text, null for inner nodes
-  children: Node[];
-};
-
-type ParseError = {
-  message: string;
+interface SyntaxNode {
+  kind: string;
   range: [number, number];
-};
+  text?: string;
+  children: SyntaxNode[];
+}
+```
+
+#### `parseAst(text, options?)`
+
+Returns the AST (Abstract Syntax Tree) — a typed, semantic tree where each node is a tagged union discriminated by `kind`. Unlike the CST, the AST extracts semantic information (e.g. heading depth, function callee, binary operator) into dedicated fields.
+
+```ts
+interface ParseAstResult {
+  root: AstExpr[];
+  errors: ParseError[];
+}
+
+// AstExpr is a discriminated union of 59 node types.
+// Examples:
+type AstExpr =
+  | { kind: "text"; range: [number, number] | null; text: string }
+  | { kind: "heading"; range: [number, number] | null; depth: number; body: AstExpr[] }
+  | { kind: "strong"; range: [number, number] | null; body: AstExpr[] }
+  | { kind: "funcCall"; range: [number, number] | null; callee: AstExpr; args: AstArg[] }
+  | { kind: "binary"; range: [number, number] | null; op: AstBinOp; lhs: AstExpr; rhs: AstExpr }
+  | // ... and 54 more variants
 ```
 
+See [`src/types.ts`](./src/types.ts) for the full type definitions.
+
 ## Development
 
 ### Prerequisites

package/package.json

@@ -3,7 +3,7 @@
   "collaborators": [
     "r4ai"
   ],
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/typst_ast.d.ts

@@ -28,6 +28,574 @@ text: string,
 options?: ParseOptions,
 ): ParseResult;
 
+// --- AST types ---
+
+export type Range = [number, number] | null;
+
+export type AstExpr =
+| AstText
+| AstSpace
+| AstLinebreak
+| AstParbreak
+| AstEscape
+| AstShorthand
+| AstSmartQuote
+| AstStrong
+| AstEmph
+| AstRaw
+| AstLink
+| AstLabel
+| AstRef
+| AstHeading
+| AstListItem
+| AstEnumItem
+| AstTermItem
+| AstEquation
+| AstMath
+| AstMathText
+| AstMathIdent
+| AstMathShorthand
+| AstMathAlignPoint
+| AstMathDelimited
+| AstMathAttach
+| AstMathPrimes
+| AstMathFrac
+| AstMathRoot
+| AstIdent
+| AstNone
+| AstAuto
+| AstBool
+| AstInt
+| AstFloat
+| AstNumeric
+| AstStr
+| AstCodeBlock
+| AstContentBlock
+| AstParenthesized
+| AstArray
+| AstDict
+| AstUnary
+| AstBinary
+| AstFieldAccess
+| AstFuncCall
+| AstClosure
+| AstLetBinding
+| AstDestructAssignment
+| AstSetRule
+| AstShowRule
+| AstContextual
+| AstConditional
+| AstWhileLoop
+| AstForLoop
+| AstModuleImport
+| AstModuleInclude
+| AstLoopBreak
+| AstLoopContinue
+| AstFuncReturn;
+
+// Markup
+
+export interface AstText {
+    kind: "text";
+    range: Range;
+    text: string;
+}
+
+export interface AstSpace {
+    kind: "space";
+    range: Range;
+}
+
+export interface AstLinebreak {
+    kind: "linebreak";
+    range: Range;
+}
+
+export interface AstParbreak {
+    kind: "parbreak";
+    range: Range;
+}
+
+export interface AstEscape {
+    kind: "escape";
+    range: Range;
+    character: string;
+}
+
+export interface AstShorthand {
+    kind: "shorthand";
+    range: Range;
+    character: string;
+}
+
+export interface AstSmartQuote {
+    kind: "smartQuote";
+    range: Range;
+    double: boolean;
+}
+
+export interface AstStrong {
+    kind: "strong";
+    range: Range;
+    body: AstExpr[];
+}
+
+export interface AstEmph {
+    kind: "emph";
+    range: Range;
+    body: AstExpr[];
+}
+
+export interface AstRaw {
+    kind: "raw";
+    range: Range;
+    lines: string[];
+    lang: string | null;
+    block: boolean;
+}
+
+export interface AstLink {
+    kind: "link";
+    range: Range;
+    url: string;
+}
+
+export interface AstLabel {
+    kind: "label";
+    range: Range;
+    name: string;
+}
+
+export interface AstRef {
+    kind: "ref";
+    range: Range;
+    target: string;
+    supplement: AstExpr[] | null;
+}
+
+export interface AstHeading {
+    kind: "heading";
+    range: Range;
+    depth: number;
+    body: AstExpr[];
+}
+
+export interface AstListItem {
+    kind: "listItem";
+    range: Range;
+    body: AstExpr[];
+}
+
+export interface AstEnumItem {
+    kind: "enumItem";
+    range: Range;
+    number: number | null;
+    body: AstExpr[];
+}
+
+export interface AstTermItem {
+    kind: "termItem";
+    range: Range;
+    term: AstExpr[];
+    description: AstExpr[];
+}
+
+export interface AstEquation {
+    kind: "equation";
+    range: Range;
+    body: AstExpr[];
+    block: boolean;
+}
+
+// Math
+
+export interface AstMath {
+    kind: "math";
+    range: Range;
+    body: AstExpr[];
+}
+
+export type AstMathTextKind =
+| { kind: "character"; value: string }
+| { kind: "number"; value: string };
+
+export interface AstMathText {
+    kind: "mathText";
+    range: Range;
+    text: AstMathTextKind;
+}
+
+export interface AstMathIdent {
+    kind: "mathIdent";
+    range: Range;
+    name: string;
+}
+
+export interface AstMathShorthand {
+    kind: "mathShorthand";
+    range: Range;
+    character: string;
+}
+
+export interface AstMathAlignPoint {
+    kind: "mathAlignPoint";
+    range: Range;
+}
+
+export interface AstMathDelimited {
+    kind: "mathDelimited";
+    range: Range;
+    open: AstExpr;
+    body: AstExpr[];
+    close: AstExpr;
+}
+
+export interface AstMathAttach {
+    kind: "mathAttach";
+    range: Range;
+    base: AstExpr;
+    bottom: AstExpr | null;
+    top: AstExpr | null;
+    primes: number | null;
+}
+
+export interface AstMathPrimes {
+    kind: "mathPrimes";
+    range: Range;
+    count: number;
+}
+
+export interface AstMathFrac {
+    kind: "mathFrac";
+    range: Range;
+    num: AstExpr;
+    denom: AstExpr;
+}
+
+export interface AstMathRoot {
+    kind: "mathRoot";
+    range: Range;
+    index: number | null;
+    radicand: AstExpr;
+}
+
+// Literals
+
+export interface AstIdent {
+    kind: "ident";
+    range: Range;
+    name: string;
+}
+
+export interface AstNone {
+    kind: "none";
+    range: Range;
+}
+
+export interface AstAuto {
+    kind: "auto";
+    range: Range;
+}
+
+export interface AstBool {
+    kind: "bool";
+    range: Range;
+    value: boolean;
+}
+
+export interface AstInt {
+    kind: "int";
+    range: Range;
+    value: number;
+}
+
+export interface AstFloat {
+    kind: "float";
+    range: Range;
+    value: number;
+}
+
+export type AstUnit =
+| "pt"
+| "mm"
+| "cm"
+| "in"
+| "rad"
+| "deg"
+| "em"
+| "fr"
+| "percent";
+
+export interface AstNumeric {
+    kind: "numeric";
+    range: Range;
+    value: number;
+    unit: AstUnit;
+}
+
+export interface AstStr {
+    kind: "str";
+    range: Range;
+    value: string;
+}
+
+// Code structures
+
+export interface AstCodeBlock {
+    kind: "codeBlock";
+    range: Range;
+    body: AstExpr[];
+}
+
+export interface AstContentBlock {
+    kind: "contentBlock";
+    range: Range;
+    body: AstExpr[];
+}
+
+export interface AstParenthesized {
+    kind: "parenthesized";
+    range: Range;
+    expr: AstExpr;
+}
+
+export type AstArrayItem =
+| { kind: "pos"; expr: AstExpr }
+| { kind: "spread"; expr: AstExpr; sinkIdent: string | null };
+
+export interface AstArray {
+    kind: "array";
+    range: Range;
+    items: AstArrayItem[];
+}
+
+export type AstDictItem =
+| { kind: "named"; name: string; expr: AstExpr }
+| { kind: "keyed"; key: AstExpr; expr: AstExpr }
+| { kind: "spread"; expr: AstExpr; sinkIdent: string | null };
+
+export interface AstDict {
+    kind: "dict";
+    range: Range;
+    items: AstDictItem[];
+}
+
+// Operations
+
+export type AstUnOp = "pos" | "neg" | "not";
+
+export type AstBinOp =
+| "add"
+| "sub"
+| "mul"
+| "div"
+| "and"
+| "or"
+| "eq"
+| "neq"
+| "lt"
+| "leq"
+| "gt"
+| "geq"
+| "assign"
+| "in"
+| "notIn"
+| "addAssign"
+| "subAssign"
+| "mulAssign"
+| "divAssign";
+
+export interface AstUnary {
+    kind: "unary";
+    range: Range;
+    op: AstUnOp;
+    expr: AstExpr;
+}
+
+export interface AstBinary {
+    kind: "binary";
+    range: Range;
+    op: AstBinOp;
+    lhs: AstExpr;
+    rhs: AstExpr;
+}
+
+export interface AstFieldAccess {
+    kind: "fieldAccess";
+    range: Range;
+    target: AstExpr;
+    field: string;
+}
+
+export type AstArg =
+| { kind: "pos"; expr: AstExpr }
+| { kind: "named"; name: string; expr: AstExpr }
+| { kind: "spread"; expr: AstExpr; sinkIdent: string | null };
+
+export interface AstFuncCall {
+    kind: "funcCall";
+    range: Range;
+    callee: AstExpr;
+    args: AstArg[];
+}
+
+export type AstParam =
+| { kind: "pos"; pattern: AstPattern }
+| { kind: "named"; name: string; expr: AstExpr }
+| { kind: "spread"; sinkIdent: string | null; sinkExpr: AstExpr | null };
+
+export interface AstClosure {
+    kind: "closure";
+    range: Range;
+    name: string | null;
+    params: AstParam[];
+    body: AstExpr;
+}
+
+// Patterns
+
+export type AstDestructuringItem =
+| { kind: "pattern"; pattern: AstPattern }
+| { kind: "named"; name: string; pattern: AstPattern }
+| { kind: "spread"; sinkIdent: string | null };
+
+export type AstPattern =
+| { kind: "normal"; expr: AstExpr }
+| { kind: "placeholder"; range: Range }
+| { kind: "parenthesized"; expr: AstExpr }
+| {
+    kind: "destructuring";
+    range: Range;
+    items: AstDestructuringItem[];
+};
+
+// Bindings
+
+export type AstLetBindingKind =
+| { kind: "normal"; pattern: AstPattern }
+| { kind: "closure"; name: string };
+
+export interface AstLetBinding {
+    kind: "letBinding";
+    range: Range;
+    bindingKind: AstLetBindingKind;
+    init: AstExpr | null;
+}
+
+export interface AstDestructAssignment {
+    kind: "destructAssignment";
+    range: Range;
+    pattern: AstPattern;
+    value: AstExpr;
+}
+
+// Rules
+
+export interface AstSetRule {
+    kind: "setRule";
+    range: Range;
+    target: AstExpr;
+    args: AstArg[];
+    condition: AstExpr | null;
+}
+
+export interface AstShowRule {
+    kind: "showRule";
+    range: Range;
+    selector: AstExpr | null;
+    transform: AstExpr;
+}
+
+export interface AstContextual {
+    kind: "contextual";
+    range: Range;
+    body: AstExpr;
+}
+
+// Control flow
+
+export interface AstConditional {
+    kind: "conditional";
+    range: Range;
+    condition: AstExpr;
+    ifBody: AstExpr;
+    elseBody: AstExpr | null;
+}
+
+export interface AstWhileLoop {
+    kind: "whileLoop";
+    range: Range;
+    condition: AstExpr;
+    body: AstExpr;
+}
+
+export interface AstForLoop {
+    kind: "forLoop";
+    range: Range;
+    pattern: AstPattern;
+    iterable: AstExpr;
+    body: AstExpr;
+}
+
+// Module
+
+export type AstImportItem =
+| { kind: "simple"; path: string[]; name: string }
+| {
+    kind: "renamed";
+    path: string[];
+    originalName: string;
+    newName: string;
+};
+
+export type AstImports =
+| { kind: "wildcard" }
+| { kind: "items"; items: AstImportItem[] };
+
+export interface AstModuleImport {
+    kind: "moduleImport";
+    range: Range;
+    source: AstExpr;
+    newName: string | null;
+    imports: AstImports | null;
+}
+
+export interface AstModuleInclude {
+    kind: "moduleInclude";
+    range: Range;
+    source: AstExpr;
+}
+
+// Jump
+
+export interface AstLoopBreak {
+    kind: "loopBreak";
+    range: Range;
+}
+
+export interface AstLoopContinue {
+    kind: "loopContinue";
+    range: Range;
+}
+
+export interface AstFuncReturn {
+    kind: "funcReturn";
+    range: Range;
+    body: AstExpr | null;
+}
+
+// Parse AST result
+
+export interface ParseAstResult {
+    root: AstExpr[];
+    errors: ParseError[];
+}
+
+export declare function parseAst(
+text: string,
+options?: ParseOptions,
+): ParseAstResult;
+
 
 
 export function start(): void;

package/typst_ast.js

@@ -16,6 +16,22 @@ function parse(text, options) {
 }
 exports.parse = parse;
 
+/**
+ * @param {string} text
+ * @param {any} options
+ * @returns {any}
+ */
+function parseAst(text, options) {
+    const ptr0 = passStringToWasm0(text, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.parseAst(ptr0, len0, options);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+exports.parseAst = parseAst;
+
 function start() {
     wasm.start();
 }
@@ -93,6 +109,10 @@ function __wbg_get_imports() {
             const ret = Object.entries(arg0);
             return ret;
         },
+        __wbg_fromCodePoint_22365db7b7d6ac39: function() { return handleError(function (arg0) {
+            const ret = String.fromCodePoint(arg0 >>> 0);
+            return ret;
+        }, arguments); },
         __wbg_get_9b94d73e6221f75c: function(arg0, arg1) {
             const ret = arg0[arg1 >>> 0];
             return ret;
@@ -155,12 +175,17 @@ function __wbg_get_imports() {
             const ret = arg0;
             return ret;
         },
-        __wbindgen_cast_0000000000000002: function(arg0, arg1) {
+        __wbindgen_cast_0000000000000002: function(arg0) {
+            // Cast intrinsic for `I64 -> Externref`.
+            const ret = arg0;
+            return ret;
+        },
+        __wbindgen_cast_0000000000000003: function(arg0, arg1) {
             // Cast intrinsic for `Ref(String) -> Externref`.
             const ret = getStringFromWasm0(arg0, arg1);
             return ret;
         },
-        __wbindgen_cast_0000000000000003: function(arg0) {
+        __wbindgen_cast_0000000000000004: function(arg0) {
             // Cast intrinsic for `U64 -> Externref`.
             const ret = BigInt.asUintN(64, arg0);
             return ret;
@@ -181,6 +206,12 @@ function __wbg_get_imports() {
     };
 }
 
+function addToExternrefTable0(obj) {
+    const idx = wasm.__externref_table_alloc();
+    wasm.__wbindgen_externrefs.set(idx, obj);
+    return idx;
+}
+
 function debugString(val) {
     // primitive types
     const type = typeof val;
@@ -272,6 +303,15 @@ function getUint8ArrayMemory0() {
     return cachedUint8ArrayMemory0;
 }
 
+function handleError(f, args) {
+    try {
+        return f.apply(this, args);
+    } catch (e) {
+        const idx = addToExternrefTable0(e);
+        wasm.__wbindgen_exn_store(idx);
+    }
+}
+
 function isLikeNone(x) {
     return x === undefined || x === null;
 }