Crate macroforge_ts_syn

Expand description

§macroforge_ts_syn

TypeScript syntax types for compile-time macro code generation.

This crate provides a syn-like API for parsing and manipulating TypeScript code, enabling macro authors to work with TypeScript AST in a familiar way. It is the core infrastructure crate for the Macroforge TypeScript macro system.

§Overview

The crate is organized into several modules:

abi - Application Binary Interface types for stable macro communication
[derive] - Derive input types that mirror Rust’s syn::DeriveInput
errors - Error types and diagnostics for macro expansion
lower - AST lowering from SWC types to IR representations
parse - TypeScript parsing utilities wrapping SWC
quote_helpers - Macros for ergonomic code generation
stream - Parsing stream abstraction similar to syn::parse::ParseBuffer

§Architecture

The crate follows a layered architecture:

┌─────────────────────────────────────────────────────────────┐
│                    User-Facing API                          │
│  (DeriveInput, TsStream, parse_ts_macro_input!)             │
├─────────────────────────────────────────────────────────────┤
│                    Lowering Layer                           │
│  (lower_classes, lower_interfaces, lower_enums, ...)        │
├─────────────────────────────────────────────────────────────┤
│                    IR Types (ABI Stable)                    │
│  (ClassIR, InterfaceIR, EnumIR, TypeAliasIR, ...)           │
├─────────────────────────────────────────────────────────────┤
│                    SWC Parser                               │
│  (swc_core for TypeScript/JavaScript parsing)               │
└─────────────────────────────────────────────────────────────┘

§Usage Example

Here’s how to use this crate in a derive macro:

use macroforge_ts_syn::{parse_ts_macro_input, DeriveInput, MacroResult, Patch, Data, MacroContextIR};

// This function signature shows a typical derive macro entry point
pub fn my_derive_macro(ctx: MacroContextIR) -> MacroResult {
    // Parse the input using the syn-like API
    let input = parse_ts_macro_input!(ctx);

    // Access type information
    println!("Processing type: {}", input.name());

    // Match on the type kind
    match &input.data {
        Data::Class(class) => {
            for field in class.fields() {
                println!("Field: {}", field.name);
            }
        }
        Data::Interface(_iface) => {
            // Handle interface...
        }
        Data::Enum(_enum_) => {
            // Handle enum...
        }
        Data::TypeAlias(_alias) => {
            // Handle type alias...
        }
    }

    // Generate code and return patches
    MacroResult::ok()
}

§Helper Macros

This crate provides several helper macros for working with SWC AST nodes:

[ident!] - Create an identifier with optional formatting
[private_ident!] - Create a private (marked) identifier
stmt_block! - Create a block statement from statements
fn_expr! - Create an anonymous function expression
member_expr! - Create a member access expression (obj.prop)
assign_stmt! - Create an assignment statement
fn_assign! - Create a function assignment (obj.prop = function() {…})
proto_method! - Create a prototype method assignment

§Feature Flags

swc - Enables SWC integration and the helper macros (enabled by default)

§Re-exports

For convenience, the crate re-exports commonly used SWC types when the swc feature is enabled:

swc_core - The full SWC core crate
swc_common - Common SWC types (Span, SourceMap, etc.)
swc_ecma_ast - ECMAScript/TypeScript AST types
quote! - SWC’s quote macro for AST generation

Re-exports§

pub use import_registry::ImportRegistry;
pub use import_registry::clear_registry;
pub use import_registry::install_registry;
pub use import_registry::take_registry;
pub use import_registry::with_registry;
pub use import_registry::with_registry_mut;
pub use swc_core;
pub use abi::*;
pub use derive::*;
pub use errors::*;
pub use lower::*;
pub use stream::*;

Modules§

__internal: Internal module for virtual completion helpers.
abi: Application Binary Interface (ABI) types for stable macro communication.
config: Macroforge Configuration Types
derive: syn-like derive input types for TypeScript macros.
errors: Error types for the macro system.
import_registry: Import Registry
lower: AST lowering from SWC types to IR representations.
parse: Low-level TypeScript parsing utilities.
quote
quote_helpers: Helper macros for ergonomic code generation.
stream: A syn-like parsing API for TypeScript using SWC.
swc_common
swc_ecma_ast

Macros§

assign_stmt: Creates an assignment expression statement (lhs = rhs;).
fn_assign: Creates a function assignment statement (obj.prop = function(params) { body };).
fn_expr: Creates an anonymous function expression with the given body statements.
member_expr: Creates a member access expression (obj.prop).
parse_ts_macro_input: Parse a TsStream into a DeriveInput, returning early with an error MacroResult on failure.
proto_method: Creates a method assignment on a class prototype.
quote: Supported output types
stmt_block: Creates a block statement ({ ... }) from a vector of statements.
stmt_block_from_vec: Converts a Vec<Stmt> into a single block statement for use in ts_quote!.
stmt_vec: Wraps a Vec<Stmt> in a StmtVec for use with ts_quote!.
ts_ident: Creates an SWC Ident with a dummy span.
ts_private_ident: Creates a private (marked) SWC Ident.

Structs§

StmtVec: A wrapper type for passing a Vec<Stmt> to be used inline in function bodies.
TsExpr: Wrapper for swc_core::ecma::ast::Expr that implements [Display] and ToTsString.
TsIdent: Wrapper for swc_core::ecma::ast::Ident that implements [Display].
TsStmt: Wrapper for swc_core::ecma::ast::Stmt that implements [Display].
TsTypeWrapper: Wrapper for swc_core::ecma::ast::TsType that implements [Display].

Traits§

ToTsExpr: Converts common Rust values into SWC Expr nodes.
ToTsIdent: Converts common Rust values into SWC Ident nodes.
ToTsStmt: Converts common Rust values into SWC Stmt nodes.
ToTsString: Trait for converting values to TypeScript string representations.
ToTsType: Converts common Rust values into SWC TsType nodes.
ToTsTypeName: Trait for converting values to type name strings.

Functions§

emit_expr: Emits an expression to a string representation.
emit_module_items: Emits a list of module items to a TypeScript source string.
emit_stmt: Emits a statement to a string representation.
emit_ts_type: Emits a TypeScript type to a string representation.
expr_to_string: Converts an expression to its TypeScript string representation.
extend_module_item_body: Extends the body of a function or class with additional statements.
ident_to_string: Converts an identifier to its TypeScript string representation.
parse_ts_to_module_items: Parses a TypeScript string into a Vec of ModuleItems.
stmt_to_string: Converts a statement to its TypeScript string representation.
to_ts_expr: Convert a value into a TypeScript Expr.
to_ts_ident: Convert a value into a TypeScript Ident.
to_ts_stmt: Convert a value into a TypeScript Stmt.
to_ts_type: Convert a value into a TypeScript TsType.
type_to_string: Converts a type to its TypeScript string representation.