macroforge_ts

TypeScript macro expansion engine - write compile-time macros in Rust

This crate provides a TypeScript macro expansion engine that brings Rust-like derive macros to TypeScript. It is designed to be used via NAPI bindings from Node.js, enabling compile-time code generation for TypeScript projects.

Overview

Macroforge processes TypeScript source files containing @derive decorators and expands them into concrete implementations. For example, a class decorated with @derive(Debug, Clone) will have toString() and clone() methods automatically generated.

Architecture

The crate is organized into several key components:

• NAPI Bindings (NativePlugin, expand_sync, transform_sync): Entry points for Node.js
• Position Mapping (NativePositionMapper, NativeMapper): Bidirectional source mapping for IDE integration
• Macro Host (host module): Core expansion engine with registry and dispatcher
• Built-in Macros (builtin module): Standard derive macros (Debug, Clone, Serialize, etc.)

Performance Considerations

• Uses a 32MB thread stack to prevent stack overflow during deep SWC AST recursion
• Implements early bailout for files without @derive decorators
• Caches expansion results keyed by filepath and version
• Uses binary search for O(log n) position mapping lookups

Usage from Node.js

const { NativePlugin, expand_sync } = require('macroforge-ts');

// Create a plugin instance with caching
const plugin = new NativePlugin();

// Process a file (uses cache if version matches)
const result = plugin.process_file(filepath, code, { version: '1.0' });

// Or use the sync function directly
const result = expand_sync(code, filepath, { keep_decorators: false });

Re-exports for Macro Authors

This crate re-exports several dependencies for convenience when writing custom macros:

• ts_syn: TypeScript syntax types for AST manipulation
• macros: Macro attributes and quote templates
• swc_core, swc_common, swc_ecma_ast: SWC compiler infrastructure

Installation

Add this to your Cargo.toml:

[dependencies]
macroforge_ts = "0.1.38"

Key Exports

Structs

• TransformResult - Result of transforming TypeScript code through the macro system.
• MacroDiagnostic - A diagnostic message produced during macro expansion.
• MappingSegmentResult - A segment mapping a range in the original source to a range in the expanded source.
• GeneratedRegionResult - A region in the expanded source that was generated by a macro.
• SourceMappingResult - Complete source mapping information for a macro expansion.
• ExpandResult - Result of expanding macros in TypeScript source code.
• ImportSourceResult - Information about an imported identifier from a TypeScript module.
• SyntaxCheckResult - Result of checking TypeScript syntax validity.
• SpanResult - A span (range) in source code, represented as start position and length.
• JsDiagnostic - A diagnostic from the TypeScript/JavaScript compiler or IDE.
• ... and 8 more

Functions

• unchanged - Creates a no-op result with the original code unchanged.
• new - Creates a new position mapper from source mapping data.
• is_empty - Checks if this mapper has no mapping data.
• original_to_expanded - Converts a position in the original source to the corresponding position in expanded source.
• expanded_to_original - Converts a position in the expanded source back to the original source position.
• generated_by - Returns the name of the macro that generated code at the given position.
• map_span_to_original - Maps a span (start + length) from expanded source to original source.
• map_span_to_expanded - Maps a span (start + length) from original source to expanded source.
• is_in_generated - Checks if a position is inside macro-generated code.
• new - Creates a new mapper wrapping the given source mapping.
• ... and 23 more

API Reference

See the full API documentation on the Macroforge website.

License

MIT