@macroforge/mcp-server 0.1.33 → 0.1.35

package/docs/builtin-macros/serialize.md

@@ -1,223 +1,93 @@
 # Serialize
 
-*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.*
+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
+## Generated Methods
 
-<MacroExample before={data.examples.basic.before} after={data.examples.basic.after} />
+| Type | Generated Code | Description |
+|------|----------------|-------------|
+| Class | `toStringifiedJSON()`, `toObject()`, `__serialize(ctx)` | Instance methods |
+| Enum | `toStringifiedJSONEnumName(value)`, `__serializeEnumName` | Standalone functions |
+| Interface | `toStringifiedJSONInterfaceName(value)`, etc. | Standalone functions |
+| Type Alias | `toStringifiedJSONTypeName(value)`, etc. | Standalone functions |
 
-```typescript
-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:
-
-| `string`, `number`, `boolean` 
-| Direct copy 
-
-| `Date` 
-| `.toISOString()` 
-
-| `T[]` 
-| Maps items, calling `toJSON()` if available 
-
-| `Map<K, V>` 
-| `Object.fromEntries()` 
+## Configuration
 
-| `Set<T>` 
-| `Array.from()` 
+The `functionNamingStyle` option in `macroforge.json` controls naming:
+- `"suffix"` (default): Suffixes with type name (e.g., `toStringifiedJSONMyType`)
+- `"prefix"`: Prefixes with type name (e.g., `myTypeToStringifiedJSON`)
+- `"generic"`: Uses TypeScript generics (e.g., `toStringifiedJSON<T extends MyType>`)
+- `"namespace"`: Legacy namespace wrapping
 
-| 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} />
-
-```typescript
-const user = new User();
-user.id = "123";
-user.name = "Alice";
-console.log(JSON.stringify(user));
-// {"user_id":"123","full_name":"Alice"}
-```
+## Cycle Detection Protocol
 
-### Skipping Fields
+The generated code handles circular references using `__id` and `__ref` markers:
 
-<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
-
-Apply a naming convention to all fields at the container level:
-
-<InteractiveMacro code={`/** @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) */
-class Address {
-  city: string;
-  zip: string;
+```json
+{
+    "__type": "User",
+    "__id": 1,
+    "name": "Alice",
+    "friend": { "__ref": 2 }  // Reference to object with __id: 2
 }
-
-/** @derive(Serialize) */
-class User {
-  name: string;
-
-  /** @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)
-
-| `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 
+When an object is serialized:
+1. Check if it's already been serialized (has an `__id`)
+2. If so, return `{ "__ref": existingId }` instead
+3. Otherwise, register the object and serialize its fields
 
-| `skip_serializing` 
-| `boolean` 
-| Exclude from serialization only 
+## Type-Specific Serialization
 
-| `flatten` 
-| `boolean` 
-| Merge nested object fields into parent
+| Type | Serialization Strategy |
+|------|------------------------|
+| Primitives | Direct value |
+| `Date` | `toISOString()` |
+| Arrays | For primitive-like element types, pass through; for `Date`/`Date | null`, map to ISO strings; otherwise map and call `__serialize(ctx)` when available |
+| `Map<K,V>` | For primitive-like values, `Object.fromEntries(map.entries())`; for `Date`/`Date | null`, convert to ISO strings; otherwise call `__serialize(ctx)` per value when available |
+| `Set<T>` | Convert to array; element handling matches `Array<T>` |
+| Nullable | Include `null` explicitly; for primitive-like and `Date` unions the generator avoids runtime `__serialize` checks |
+| Objects | Call `__serialize(ctx)` if available (to support user-defined implementations) |
 
-## Interface Support
+Note: the generator specializes some code paths based on the declared TypeScript type to
+avoid runtime feature detection on primitives and literal unions.
 
-Serialize also works with interfaces. For interfaces, a namespace is generated with a `toJSON` function:
+## Field-Level Options
 
-<MacroExample before={data.examples.interface.before} after={data.examples.interface.after} />
+The `@serde` decorator supports:
 
-```typescript
-const response: ApiResponse = {
-  status: 200,
-  message: "OK",
-  timestamp: new Date()
-};
-
-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):
+- `skip` / `skip_serializing` - Exclude field from serialization
+- `rename = "jsonKey"` - Use different JSON property name
+- `flatten` - Merge nested object's fields into parent
 
-<MacroExample before={data.examples.enum.before} after={data.examples.enum.after} />
+## Example
 
 ```typescript
-console.log(Status.toJSON(Status.Active));  // "active"
-console.log(Status.toJSON(Status.Pending)); // "pending"
-```
-
-Works with numeric enums too:
-
-<InteractiveMacro code={`/** @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:
+@derive(Serialize)
+class User {
+    id: number;
 
-<MacroExample before={data.examples.typeAlias.before} after={data.examples.typeAlias.after} />
+    @serde(rename = "userName")
+    name: string;
 
-```typescript
-const profile: UserProfile = {
-  id: "123",
-  name: "Alice",
-  createdAt: new Date("2024-01-15")
-};
-
-console.log(JSON.stringify(UserProfile.toJSON(profile)));
-// {"id":"123","name":"Alice","createdAt":"2024-01-15T00:00:00.000Z"}
-```
+    @serde(skip_serializing)
+    password: string;
 
-For union types, the value is returned directly:
+    @serde(flatten)
+    metadata: UserMetadata;
+}
 
-<InteractiveMacro code={`/** @derive(Serialize) */
-type ApiStatus = "loading" | "success" | "error";`} />
+// Usage:
+const user = new User();
+const json = user.toStringifiedJSON();
+// => '{"__type":"User","__id":1,"id":1,"userName":"Alice",...}'
 
-```typescript
-console.log(ApiStatus.toJSON("success")); // "success"
+const obj = user.toObject();
+// => { __type: "User", __id: 1, id: 1, userName: "Alice", ... }
 ```
 
-## Combining with Deserialize
+## Required Import
 
-Use both Serialize and Deserialize for complete JSON round-trip support:
-
-<InteractiveMacro code={`/** @derive(Serialize, Deserialize) */
-class User {
-  name: string;
-  createdAt: Date;
-}`} />
-
-```typescript
-// Serialize
-const user = new User();
-user.name = "Alice";
-user.createdAt = new Date();
-const json = JSON.stringify(user);
-
-// Deserialize
-const parsed = User.fromJSON(JSON.parse(json));
-console.log(parsed.createdAt instanceof Date); // true
-```
+The generated code automatically imports `SerializeContext` from `macroforge/serde`.

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)