Module host 

TypeScript Macro Host

The macro host module provides the core infrastructure for TypeScript macro expansion. It handles the complete lifecycle of macro processing: registration, dispatch, execution, and patch application.

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                      MacroExpander                               │
│  (Main entry point - coordinates the expansion process)         │
└─────────────────────────────────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                     MacroDispatcher                              │
│  (Routes macro calls to implementations with ABI checking)       │
└─────────────────────────────────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                      MacroRegistry                               │
│  (Thread-safe storage of registered macros using DashMap)        │
└─────────────────────────────────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                    PatchApplicator                               │
│  (Applies generated patches with source mapping)                 │
└─────────────────────────────────────────────────────────────────┘

Module Organization

• config - Configuration loading and management (macroforge.json)
• derived - Inventory-based registration for built-in derive macros
• dispatch - Macro call routing and ABI version checking
• error - Error types (MacroError) and Result type alias
• expand - The main MacroExpander that orchestrates expansion
• macros - Helper macros for macro registration
• package_registry - Global registry for macro package registrars
• patch_applicator - Applies code patches with source mapping
• registry - Thread-safe macro storage (MacroRegistry)
• traits - Core traits (Macroforge, MacroPackage)

Key Types

• MacroExpander - Main entry point for macro expansion
• MacroDispatcher - Routes macros to implementations
• MacroRegistry - Stores registered macros
• Macroforge - Trait that all macros must implement
• MacroConfig - Configuration options
• MacroError - Error type for macro operations

Usage Example

use macroforge_ts::host::{MacroExpander, Result};

fn example() -> Result<()> {
    // Create a new expander (registers all built-in macros)
    let expander = MacroExpander::new()?;

    // Parse TypeScript source code
    let source = r#"
        /** @derive(Debug) */
        class User { name: string; }
    "#;

    // Expand macros (handles parsing internally)
    let result = expander.expand_source(source, "file.ts")?;
    println!("Expanded: {}", result.code);
    Ok(())
}

Re-exports

pub use config::CONFIG_CACHE;

pub use config::ForeignTypeConfig;

pub use config::ImportInfo;

pub use config::MacroConfig;

pub use config::MacroforgeConfig;

pub use config::clear_config_cache;

pub use dispatch::MacroDispatcher;

pub use error::MacroError;

pub use error::Result;

pub use expand::ImportCollectionResult;

pub use expand::MacroExpander;

pub use expand::MacroExpansion;

pub use expand::collect_import_sources;

pub use package_registry::MacroPackageRegistration;

pub use patch_applicator::PatchApplicator;

pub use patch_applicator::PatchCollector;

pub use registry::MacroRegistry;

pub use traits::Macroforge;

Modules

config

Configuration loading and management.

derived

Inventory-based registration for built-in derive macros.

dispatch

Macro call dispatching with ABI version checking.

error

Error types for macro operations.

expand

The main macro expansion engine.

macros

Helper macros for macro registration.

package_registry

Global registry for macro package registrars.

patch_applicator

Patch application with source mapping.

registry

Thread-safe macro storage.

traits

Core traits for macro implementations.

Structs

Diagnostic

A diagnostic message from macro expansion.

MacroResult

The result returned by a macro function.

Enums

DiagnosticLevel

The severity level of a diagnostic message.

MacroKind

The kind of macro being executed.

Patch

A code modification operation returned by macros.