Crate macroforge_ts 

Macroforge TypeScript Macro Engine

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): An output-agnostic trait-based interface (MacroforgeApi) that defines all macro operations.
• 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, { keep_decorators: false });

From WASM

import init, { expand_sync } from './pkg/macroforge_ts.js';
await init();
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 compatibility 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 serde_json;

pub extern crate serde_wasm_bindgen;

pub extern crate wasm_bindgen;

pub use api_types::ExpandOptions;

pub use api_types::ExpandResult;

pub use api_types::GeneratedRegionResult;

pub use api_types::ImportSourceResult;

pub use api_types::JsDiagnostic;

pub use api_types::LoadConfigResult;

pub use api_types::MacroDiagnostic;

pub use api_types::MappingSegmentResult;

pub use api_types::ProcessFileOptions;

pub use api_types::ScanOptions;

pub use api_types::ScanResult;

pub use api_types::SourceMappingResult;

pub use api_types::SpanResult;

pub use api_types::SyntaxCheckResult;

pub use api_types::TransformResult;

pub use bindings_wasm::check_syntax as wasm_check_syntax;

pub use bindings_wasm::clear_config_cache as wasm_clear_config_cache;

pub use bindings_wasm::derive_decorator as wasm_derive_decorator;

pub use bindings_wasm::expand_sync as wasm_expand_sync;

pub use bindings_wasm::load_config as wasm_load_config;

pub use bindings_wasm::parse_import_sources as wasm_parse_import_sources;

pub use bindings_wasm::scan_project_sync as wasm_scan_project_sync;

pub use bindings_wasm::transform_sync as wasm_transform_sync;

pub use manifest::DecoratorManifestEntry;

pub use manifest::MacroManifest;

pub use manifest::MacroManifestEntry;

pub use macroforge_ts_syn as ts_syn;

Modules

abi

Application Binary Interface (ABI) types for stable macro communication.

api

api_types

bindings_wasm

builtin

Built-in Derive Macros for Macroforge

debug

Debug logging for external macros. Writes to .macroforge/debug.log relative to the project root. Use: macroforge_ts::debug::log("tag", "message") or macroforge_ts::debug_log!("tag", "...") Debug logging for external macros.

host

TypeScript Macro Host

macros

Macro attributes and quote templates Use: use macroforge_ts::macros::*;

swc_ecma_ast

Macros

debug_log

Log a formatted message.

ident

if_node

if_node_else

if_swc

if_wasm

if_wasm_else

private_ident

register_macro_package

Registers a macro package with the global package registry.

Functions

__macroforge_ffi_free^⚠

Free a buffer allocated by an FFI function. Must be called by the host after reading the output.

__macroforge_ffi_get_manifest^⚠

Returns the full MacroManifest as JSON via FFI. Linked into every macro package automatically since they depend on macroforge_ts. Uses inventory to collect all #[ts_macro_derive] registrations in the crate.

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).

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.