Crate macroforge_ts

Expand description

§Macroforge TypeScript Macro Engine

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

Re-exports§

pub extern crate inventory;
pub extern crate macroforge_ts_macros;
pub extern crate macroforge_ts_quote;
pub extern crate macroforge_ts_syn;
pub extern crate napi;
pub extern crate napi_derive;
pub extern crate serde_json;

`Re-exports§`

pub use macroforge_ts_syn as ts_syn;
pub use macroforge_ts_syn::swc_core;

`Modules§`

abi: Application Binary Interface (ABI) types for stable macro communication.
builtin: Built-in Derive Macros for Macroforge
host: TypeScript Macro Host
macros: Macro attributes and quote templates Use: use macroforge_ts::macros::*;
swc_common
swc_ecma_ast

`Macros§`

register_macro_package: Registers a macro package with the global package registry.

`Structs§`

DecoratorManifestEntry: Entry for a registered decorator in the manifest.
ExpandOptions: Options for macro expansion.
ExpandResult: Result of expanding macros in TypeScript source code.
GeneratedRegionResult: A region in the expanded source that was generated by a macro.
ImportSourceResult: Information about an imported identifier from a TypeScript module.
JsDiagnostic: A diagnostic from the TypeScript/JavaScript compiler or IDE.
LoadConfigResult: Result of loading a macroforge configuration file.
MacroDiagnostic: A diagnostic message produced during macro expansion.
MacroManifest: Complete manifest of all available macros and decorators.
MacroManifestEntry: Entry for a registered macro in the manifest.
MappingSegmentResult: A segment mapping a range in the original source to a range in the expanded source.
NativeMapper: Wrapper around NativePositionMapper for NAPI compatibility.
NativePlugin: The main plugin class for macro expansion with caching support.
NativePositionMapper: Bidirectional position mapper for translating between original and expanded source positions.
ProcessFileOptions: Options for processing a file through the macro system.
SourceMappingResult: Complete source mapping information for a macro expansion.
SpanResult: A span (range) in source code, represented as start position and length.
SyntaxCheckResult: Result of checking TypeScript syntax validity.
TransformResult: Result of transforming TypeScript code through the macro system.

`Functions§`

check_syntax: Checks if the given TypeScript code has valid syntax.
clear_config_cache: Clears the configuration cache.
debug_descriptors: Returns debug information about all registered macro descriptors (debug API).
debug_get_modules: Returns all registered macro module names (debug API).
debug_lookup: Looks up a macro by module and name (debug API).
derive_decorator: The @Derive decorator function exported to JavaScript/TypeScript.
expand_sync: Synchronously expands macros in TypeScript code.
get_macro_manifest: Returns the complete manifest of all registered macros and decorators.
get_macro_names: Returns the names of all registered macros.
is_macro_package: Checks if any macros are registered in this package.
load_config: Load and parse a macroforge configuration file.
parse_import_sources: Parses import statements from TypeScript code and returns their sources.
transform_sync: Synchronously transforms TypeScript code through the macro expansion system.