macroforge_ts

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

Overview

This crate provides a TypeScript macro expansion engine that brings Rust-like derive macros to TypeScript. It supports multiple output targets via feature flags:

• wasm: (Default) Universal WebAssembly module via wasm-bindgen for browser and edge environments.
• node: Optional native Node.js bindings via NAPI-RS.

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:

• Unified API (api module): CoreEngine, the output-agnostic facade that both bindings delegate to. (The MacroforgeApi trait sketches the same surface but is currently not implemented by anything.)
• Target Bindings:
  • bindings_napi: Node.js specific entry points using NAPI-RS.
  • bindings_wasm: Universal entry points using wasm-bindgen.
• Position Mapping (api_types::SourceMappingResult): 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.).

Usage

From Node.js

const { expandSync } = require('macroforge');
const result = expandSync(code, filepath, { keepDecorators: false });

From WASM

import init, { expandSync } from './pkg/macroforge_ts.js';
await init();
const result = expandSync(code, filepath, { keepDecorators: 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 compatibility infrastructure

Installation

Add this to your Cargo.toml:

[dependencies]
macroforge_ts = "0.1.80"

Key Exports

Structs

• CoreEngine - Output-agnostic facade over the macro engine.
• 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.
• ... and 12 more

Functions

• __macroforge_ffi_free - Free a buffer allocated by an FFI function.
• __macroforge_ffi_get_manifest - Returns the full MacroManifest as JSON via FFI.
• check_syntax -
• parse_import_sources -
• derive_decorator -
• load_config -
• clear_config_cache -
• transform_sync -
• expand_sync -
• expand - Async macro expansion.
• ... and 19 more

Traits

• MacroforgeApi - Trait sketch of the output-agnostic macro API surface.

API Reference

See the full API documentation on the Macroforge website.

License

MIT