@macroforge/mcp-server 0.1.32 → 0.1.34

package/docs/builtin-macros/serialize.md

@@ -1,91 +1,210 @@
 # Serialize
+  *The `Serialize` macro generates JSON serialization methods with **cycle detection** and object identity tracking. This enables serialization of complex object graphs including circular references.*
+ ## Basic Usage
+ **Before:**
+```
+/** @derive(Serialize) */
+class User {
+    name: string;
+    age: number;
+    createdAt: Date;
+
+    constructor(name: string, age: number) {
+        this.name = name;
+        this.age = age;
+        this.createdAt = new Date();
+    }
+}
+```  
+**After:**
+```
+import { SerializeContext } from 'macroforge/serde';
 
-*The `Serialize` macro generates a `toJSON()` method that converts your object to a JSON-compatible format with automatic handling of complex types like Date, Map, Set, and nested objects.*
-
-## Basic Usage
-
-<MacroExample before={data.examples.basic.before} after={data.examples.basic.after} />
-
-```typescript
+class User {
+    name: string;
+    age: number;
+    createdAt: Date;
+
+    constructor(name: string, age: number) {
+        this.name = name;
+        this.age = age;
+        this.createdAt = new Date();
+    }
+
+    toStringifiedJSON(): string {
+        const ctx = SerializeContext.create();
+        return JSON.stringify(this.__serialize(ctx));
+    }
+
+    toObject(): Record<string, unknown> {
+        const ctx = SerializeContext.create();
+        return this.__serialize(ctx);
+    }
+
+    __serialize(ctx: SerializeContext): Record<string, unknown> {
+        const existingId = ctx.getId(this);
+        if (existingId !== undefined) {
+            return {
+                __ref: existingId
+            };
+        }
+        const __id = ctx.register(this);
+        const result: Record<string, unknown> = {
+            __type: 'User',
+            __id
+        };
+        result['name'] = this.name;
+        result['age'] = this.age;
+        result['createdAt'] = this.createdAt.toISOString();
+        return result;
+    }
+}
+``` ```
 const user = new User("Alice", 30);
 console.log(JSON.stringify(user));
 // {"name":"Alice","age":30,"createdAt":"2024-01-15T10:30:00.000Z"}
+``` ## Automatic Type Handling
+ Serialize automatically handles various TypeScript types:
+ | Type | Serialization |
+| --- | --- |
+| `string`, `number`, `boolean` | Direct copy |
+| `Date` | `.toISOString()` |
+| `T[]` | Maps items, calling `toJSON()` if available |
+| `Map<K, V>` | `Object.fromEntries()` |
+| `Set<T>` | `Array.from()` |
+| Nested objects | Calls `toJSON()` if available |
+ ## Serde Options
+ Use the `@serde` decorator for fine-grained control over serialization:
+ ### Renaming Fields
+ **Before:**
 ```
+/** @derive(Serialize) */
+class User {
+    /** @serde({ rename: "user_id" }) */
+    id: string;
 
-## Automatic Type Handling
-
-Serialize automatically handles various TypeScript types:
-
-| `string`, `number`, `boolean` 
-| Direct copy 
-
-| `Date` 
-| `.toISOString()` 
-
-| `T[]` 
-| Maps items, calling `toJSON()` if available 
-
-| `Map<K, V>` 
-| `Object.fromEntries()` 
-
-| `Set<T>` 
-| `Array.from()` 
-
-| Nested objects 
-| Calls `toJSON()` if available
-
-## Serde Options
-
-Use the `@serde` decorator for fine-grained control over serialization:
-
-### Renaming Fields
-
-<MacroExample before={data.examples.rename.before} after={data.examples.rename.after} />
+    /** @serde({ rename: "full_name" }) */
+    name: string;
+}
+```  
+**After:**
+```
+import { SerializeContext } from 'macroforge/serde';
 
-```typescript
+class User {
+    id: string;
+
+    name: string;
+
+    toStringifiedJSON(): string {
+        const ctx = SerializeContext.create();
+        return JSON.stringify(this.__serialize(ctx));
+    }
+
+    toObject(): Record<string, unknown> {
+        const ctx = SerializeContext.create();
+        return this.__serialize(ctx);
+    }
+
+    __serialize(ctx: SerializeContext): Record<string, unknown> {
+        const existingId = ctx.getId(this);
+        if (existingId !== undefined) {
+            return {
+                __ref: existingId
+            };
+        }
+        const __id = ctx.register(this);
+        const result: Record<string, unknown> = {
+            __type: 'User',
+            __id
+        };
+        result['user_id'] = this.id;
+        result['full_name'] = this.name;
+        return result;
+    }
+}
+``` ```
 const user = new User();
 user.id = "123";
 user.name = "Alice";
 console.log(JSON.stringify(user));
 // {"user_id":"123","full_name":"Alice"}
+``` ### Skipping Fields
+ **Before:**
 ```
+/** @derive(Serialize) */
+class User {
+    name: string;
+    email: string;
 
-### Skipping Fields
-
-<MacroExample before={data.examples.skip.before} after={data.examples.skip.after} />
-
-<Alert type="tip" title="skip vs skip_serializing">
-Use `skip: true` to exclude from both serialization and deserialization.
-Use `skip_serializing: true` to only skip during serialization.
-</Alert>
-
-### Rename All Fields
+    /** @serde({ skip: true }) */
+    password: string;
 
-Apply a naming convention to all fields at the container level:
+    /** @serde({ skip_serializing: true }) */
+    internalId: string;
+}
+```  
+**After:**
+```
+import { SerializeContext } from 'macroforge/serde';
 
-<InteractiveMacro code={`/** @derive(Serialize) */
+class User {
+    name: string;
+    email: string;
+
+    password: string;
+
+    internalId: string;
+
+    toStringifiedJSON(): string {
+        const ctx = SerializeContext.create();
+        return JSON.stringify(this.__serialize(ctx));
+    }
+
+    toObject(): Record<string, unknown> {
+        const ctx = SerializeContext.create();
+        return this.__serialize(ctx);
+    }
+
+    __serialize(ctx: SerializeContext): Record<string, unknown> {
+        const existingId = ctx.getId(this);
+        if (existingId !== undefined) {
+            return {
+                __ref: existingId
+            };
+        }
+        const __id = ctx.register(this);
+        const result: Record<string, unknown> = {
+            __type: 'User',
+            __id
+        };
+        result['name'] = this.name;
+        result['email'] = this.email;
+        return result;
+    }
+}
+```  **skip vs skip_serializing Use `skip: true` to exclude from both serialization and deserialization.
+Use `skip_serializing: true` to only skip during serialization. ### Rename All Fields
+ Apply a naming convention to all fields at the container level:
+ ****Source:**
+```
+/** @derive(Serialize) */
 /** @serde({ rename_all: "camelCase" }) */
 class ApiResponse {
   user_name: string;
   created_at: Date;
   is_active: boolean;
-}`} />
-
-Supported conventions:
-
-- `camelCase`
-
-- `snake_case`
-
-- `PascalCase`
-
-- `SCREAMING_SNAKE_CASE`
-
-- `kebab-case`
-
-### Flattening Nested Objects
-
-<InteractiveMacro code={`/** @derive(Serialize) */
+}
+```  Supported conventions:
+ - `camelCase`
+ - `snake_case`
+ - `PascalCase`
+ - `SCREAMING_SNAKE_CASE`
+ - `kebab-case`
+ ### Flattening Nested Objects
+ **Source:**
+```
+/** @derive(Serialize) */
 class Address {
   city: string;
   zip: string;
@@ -97,49 +216,69 @@ class User {
 
   /** @serde({ flatten: true }) */
   address: Address;
-}`} />
-
-```typescript
+}
+```  ```
 const user = new User();
 user.name = "Alice";
 user.address = { city: "NYC", zip: "10001" };
 console.log(JSON.stringify(user));
 // {"name":"Alice","city":"NYC","zip":"10001"}
+``` ## All Options
+ ### Container Options (on class/interface)
+ | Option | Type | Description |
+| --- | --- | --- |
+| `rename_all` | `string` | Apply naming convention to all fields |
+ ### Field Options (on properties)
+ | Option | Type | Description |
+| --- | --- | --- |
+| `rename` | `string` | Use a different JSON key |
+| `skip` | `boolean` | Exclude from serialization and deserialization |
+| `skip_serializing` | `boolean` | Exclude from serialization only |
+| `flatten` | `boolean` | Merge nested object fields into parent |
+ ## Interface Support
+ Serialize also works with interfaces. For interfaces, a namespace is generated with a `toJSON` function:
+ **Before:**
 ```
+/** @derive(Serialize) */
+interface ApiResponse {
+    status: number;
+    message: string;
+    timestamp: Date;
+}
+```  
+**After:**
+```
+import { SerializeContext } from 'macroforge/serde';
 
-## All Options
-
-### Container Options (on class/interface)
-
-| `rename_all` 
-| `string` 
-| Apply naming convention to all fields
-
-### Field Options (on properties)
-
-| `rename` 
-| `string` 
-| Use a different JSON key 
-
-| `skip` 
-| `boolean` 
-| Exclude from serialization and deserialization 
-
-| `skip_serializing` 
-| `boolean` 
-| Exclude from serialization only 
-
-| `flatten` 
-| `boolean` 
-| Merge nested object fields into parent
-
-## Interface Support
-
-Serialize also works with interfaces. For interfaces, a namespace is generated with a `toJSON` function:
-
-<MacroExample before={data.examples.interface.before} after={data.examples.interface.after} />
+interface ApiResponse {
+    status: number;
+    message: string;
+    timestamp: Date;
+}
 
-```typescript
+export namespace ApiResponse {
+    export function toStringifiedJSON(self: ApiResponse): string {
+        const ctx = SerializeContext.create();
+        return JSON.stringify(__serialize(self, ctx));
+    }
+    export function toObject(self: ApiResponse): Record<string, unknown> {
+        const ctx = SerializeContext.create();
+        return __serialize(self, ctx);
+    }
+    export function __serialize(self: ApiResponse, ctx: SerializeContext): Record<string, unknown> {
+        const existingId = ctx.getId(self);
+        if (existingId !== undefined) {
+            return { __ref: existingId };
+        }
+        const __id = ctx.register(self);
+        const result: Record<string, unknown> = { __type: 'ApiResponse', __id };
+        result['status'] = self.status;
+        result['message'] = self.message;
+        result['timestamp'] = self.timestamp.toISOString();
+        return result;
+    }
+}
+``` ```
 const response: ApiResponse = {
   status: 200,
   message: "OK",
@@ -148,39 +287,94 @@ const response: ApiResponse = {
 
 console.log(JSON.stringify(ApiResponse.toJSON(response)));
 // {"status":200,"message":"OK","timestamp":"2024-01-15T10:30:00.000Z"}
+``` ## Enum Support
+ Serialize also works with enums. The `toJSON` function returns the underlying enum value (string or number):
+ **Before:**
 ```
+/** @derive(Serialize) */
+enum Status {
+    Active = 'active',
+    Inactive = 'inactive',
+    Pending = 'pending'
+}
+```  
+**After:**
+```
+enum Status {
+    Active = 'active',
+    Inactive = 'inactive',
+    Pending = 'pending'
+}
 
-## Enum Support
-
-Serialize also works with enums. The `toJSON` function returns the underlying enum value (string or number):
-
-<MacroExample before={data.examples.enum.before} after={data.examples.enum.after} />
-
-```typescript
+export namespace Status {
+    export function toStringifiedJSON(value: Status): string {
+        return JSON.stringify(value);
+    }
+    export function __serialize(_ctx: SerializeContext): string | number {
+        return value;
+    }
+}
+``` ```
 console.log(Status.toJSON(Status.Active));  // "active"
 console.log(Status.toJSON(Status.Pending)); // "pending"
+``` Works with numeric enums too:
+ **Source:**
 ```
-
-Works with numeric enums too:
-
-<InteractiveMacro code={`/** @derive(Serialize) */
+/** @derive(Serialize) */
 enum Priority {
   Low = 1,
   Medium = 2,
   High = 3,
-}`} />
-
-```typescript
+}
+```  ```
 console.log(Priority.toJSON(Priority.High)); // 3
+``` ## Type Alias Support
+ Serialize works with type aliases. For object types, fields are serialized with full type handling:
+ **Before:**
 ```
+/** @derive(Serialize) */
+type UserProfile = {
+    id: string;
+    name: string;
+    createdAt: Date;
+};
+```  
+**After:**
+```
+import { SerializeContext } from 'macroforge/serde';
 
-## Type Alias Support
-
-Serialize works with type aliases. For object types, fields are serialized with full type handling:
-
-<MacroExample before={data.examples.typeAlias.before} after={data.examples.typeAlias.after} />
+type UserProfile = {
+    id: string;
+    name: string;
+    createdAt: Date;
+};
 
-```typescript
+export namespace UserProfile {
+    export function toStringifiedJSON(value: UserProfile): string {
+        const ctx = SerializeContext.create();
+        return JSON.stringify(__serialize(value, ctx));
+    }
+    export function toObject(value: UserProfile): Record<string, unknown> {
+        const ctx = SerializeContext.create();
+        return __serialize(value, ctx);
+    }
+    export function __serialize(
+        value: UserProfile,
+        ctx: SerializeContext
+    ): Record<string, unknown> {
+        const existingId = ctx.getId(value);
+        if (existingId !== undefined) {
+            return { __ref: existingId };
+        }
+        const __id = ctx.register(value);
+        const result: Record<string, unknown> = { __type: 'UserProfile', __id };
+        result['id'] = value.id;
+        result['name'] = value.name;
+        result['createdAt'] = value.createdAt;
+        return result;
+    }
+}
+``` ```
 const profile: UserProfile = {
   id: "123",
   name: "Alice",
@@ -189,28 +383,23 @@ const profile: UserProfile = {
 
 console.log(JSON.stringify(UserProfile.toJSON(profile)));
 // {"id":"123","name":"Alice","createdAt":"2024-01-15T00:00:00.000Z"}
+``` For union types, the value is returned directly:
+ **Source:**
 ```
-
-For union types, the value is returned directly:
-
-<InteractiveMacro code={`/** @derive(Serialize) */
-type ApiStatus = "loading" | "success" | "error";`} />
-
-```typescript
+/** @derive(Serialize) */
+type ApiStatus = "loading" | "success" | "error";
+```  ```
 console.log(ApiStatus.toJSON("success")); // "success"
+``` ## Combining with Deserialize
+ Use both Serialize and Deserialize for complete JSON round-trip support:
+ **Source:**
 ```
-
-## Combining with Deserialize
-
-Use both Serialize and Deserialize for complete JSON round-trip support:
-
-<InteractiveMacro code={`/** @derive(Serialize, Deserialize) */
+/** @derive(Serialize, Deserialize) */
 class User {
   name: string;
   createdAt: Date;
-}`} />
-
-```typescript
+}
+```  ```
 // Serialize
 const user = new User();
 user.name = "Alice";

package/docs/concepts/architecture.md

@@ -1,96 +1,41 @@
 # Architecture
-
-*Macroforge is built as a native Node.js module using Rust and NAPI-RS. It leverages SWC for fast TypeScript parsing and code generation.*
-
-## Overview
-
-<ArchitectureDiagram layers={[
-{ title: "Node.js / Vite" },
-{ title: "NAPI-RS Bindings" },
-{ title: "Macro Crates", items: ["macroforge_ts_syn", "macroforge_ts_quote", "macroforge_ts_macros"] },
-{ title: "SWC Core", items: ["TypeScript parsing & codegen"] }
-]} />
-
-## Core Components
-
-### SWC Core
-
-The foundation layer provides:
-
-- Fast TypeScript/JavaScript parsing
-
-- AST representation
-
-- Code generation (AST → source code)
-
-### macroforge_ts_syn
-
-A Rust crate that provides:
-
-- TypeScript-specific AST types
-
-- Parsing utilities for macro input
-
-- Derive input structures (class fields, decorators, etc.)
-
-### macroforge_ts_quote
-
-Template-based code generation similar to Rust's `quote!`:
-
-- `ts_template!` - Generate TypeScript code from templates
-
-- `body!` - Generate class body members
-
-- Control flow: `{"{#for}"}`, `{"{#if}"}`, `{"{$let}"}`
-
-### macroforge_ts_macros
-
-The procedural macro attribute for defining derive macros:
-
-- `#[ts_macro_derive(Name)]` attribute
-
-- Automatic registration with the macro system
-
-- Error handling and span tracking
-
-### NAPI-RS Bindings
-
-Bridges Rust and Node.js:
-
-- Exposes `expandSync`, `transformSync`, etc.
-
-- Provides the `NativePlugin` class for caching
-
-- Handles data marshaling between Rust and JavaScript
-
-## Data Flow
-
-<Flowchart steps={[
-{ title: "1. Source Code", description: "TypeScript with @derive" },
-{ title: "2. NAPI-RS", description: "receives JavaScript string" },
-{ title: "3. SWC Parser", description: "parses to AST" },
-{ title: "4. Macro Expander", description: "finds @derive decorators" },
-{ title: "5. For Each Macro", description: "extract data, run macro, generate AST nodes" },
-{ title: "6. Merge", description: "generated nodes into AST" },
-{ title: "7. SWC Codegen", description: "generates source code" },
-{ title: "8. Return", description: "to JavaScript with source mapping" }
-]} />
-
-## Performance Characteristics
-
-- **Thread-safe**: Each expansion runs in an isolated thread with a 32MB stack
-
-- **Caching**: `NativePlugin` caches results by file version
-
-- **Binary search**: Position mapping uses O(log n) lookups
-
-- **Zero-copy**: SWC's arena allocator minimizes allocations
-
-## Re-exported Crates
-
-For custom macro development, `macroforge_ts` re-exports everything you need:
-
-```rust
+ *Macroforge is built as a native Node.js module using Rust and NAPI-RS. It leverages SWC for fast TypeScript parsing and code generation.*
+ ## Overview
+ <div class="border border-border bg-card p-4 text-center rounded-t-lg  "><div class="font-semibold text-foreground">Node.js / Vite <div class="font-semibold text-foreground">NAPI-RS Bindings <div class="font-semibold text-foreground">Macro Crates <div class="px-3 py-1.5 bg-muted rounded text-sm text-muted-foreground font-mono">macroforge_ts_synmacroforge_ts_quotemacroforge_ts_macros<div class="font-semibold text-foreground">SWC Core <div class="px-3 py-1.5 bg-muted rounded text-sm text-muted-foreground font-mono">TypeScript parsing & codegen ## Core Components
+ ### SWC Core
+ The foundation layer provides:
+ - Fast TypeScript/JavaScript parsing
+ - AST representation
+ - Code generation (AST → source code)
+ ### macroforge_ts_syn
+ A Rust crate that provides:
+ - TypeScript-specific AST types
+ - Parsing utilities for macro input
+ - Derive input structures (class fields, decorators, etc.)
+ ### macroforge_ts_quote
+ Template-based code generation similar to Rust's `quote!`:
+ - `ts_template!` - Generate TypeScript code from templates
+ - `body!` - Generate class body members
+ - Control flow: `{#for}`, `{#if}`, `{$let}`
+ ### macroforge_ts_macros
+ The procedural macro attribute for defining derive macros:
+ - `#[ts_macro_derive(Name)]` attribute
+ - Automatic registration with the macro system
+ - Error handling and span tracking
+ ### NAPI-RS Bindings
+ Bridges Rust and Node.js:
+ - Exposes `expandSync`, `transformSync`, etc.
+ - Provides the `NativePlugin` class for caching
+ - Handles data marshaling between Rust and JavaScript
+ ## Data Flow
+ <div class="w-full max-w-md border border-border rounded-lg bg-card p-4 text-center shadow-sm"><div class="font-semibold text-foreground">1. Source Code TypeScript with @derive  <div class="font-semibold text-foreground">2. NAPI-RS receives JavaScript string  <div class="font-semibold text-foreground">3. SWC Parser parses to AST  <div class="font-semibold text-foreground">4. Macro Expander finds @derive decorators  <div class="font-semibold text-foreground">5. For Each Macro extract data, run macro, generate AST nodes  <div class="font-semibold text-foreground">6. Merge generated nodes into AST  <div class="font-semibold text-foreground">7. SWC Codegen generates source code  <div class="font-semibold text-foreground">8. Return to JavaScript with source mapping  ## Performance Characteristics
+ - **Thread-safe**: Each expansion runs in an isolated thread with a 32MB stack
+ - **Caching**: `NativePlugin` caches results by file version
+ - **Binary search**: Position mapping uses O(log n) lookups
+ - **Zero-copy**: SWC's arena allocator minimizes allocations
+ ## Re-exported Crates
+ For custom macro development, `macroforge_ts` re-exports everything you need:
+ ```
 // Convenient re-exports for macro development
 use macroforge_ts::macros::{ts_macro_derive, body, ts_template, above, below, signature};
 use macroforge_ts::ts_syn::{Data, DeriveInput, MacroforgeError, TsStream, parse_ts_macro_input};
@@ -99,10 +44,6 @@ use macroforge_ts::ts_syn::{Data, DeriveInput, MacroforgeError, TsStream, parse_
 use macroforge_ts::swc_core;
 use macroforge_ts::swc_common;
 use macroforge_ts::swc_ecma_ast;
-```
-
-## Next Steps
-
-- [Write custom macros]({base}/docs/custom-macros)
-
-- [Explore the API reference]({base}/docs/api)
+``` ## Next Steps
+ - [Write custom macros](../../docs/custom-macros)
+ - [Explore the API reference](../../docs/api)