@macroforge/mcp-server 0.1.37 → 0.1.39

package/docs/builtin-macros/serialize.md

@@ -8,18 +8,10 @@ including circular references.
 
 | 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 |
-
-## Configuration
-
-The `functionNamingStyle` option in `macroforge.json` controls naming:
-- `"prefix"` (default): Prefixes with type name (e.g., `myTypeToStringifiedJSON`)
-- `"suffix"`: Suffixes with type name (e.g., `toStringifiedJSONMyType`)
-- `"generic"`: Uses TypeScript generics (e.g., `toStringifiedJSON<T extends MyType>`)
-- `"namespace"`: Legacy namespace wrapping
+| Class | `classNameSerialize(value)` + `static serialize(value)` | Standalone function + static wrapper method |
+| Enum | `enumNameSerialize(value)`, `enumNameSerializeWithContext` | Standalone functions |
+| Interface | `interfaceNameSerialize(value)`, etc. | Standalone functions |
+| Type Alias | `typeNameSerialize(value)`, etc. | Standalone functions |
 
 ## Cycle Detection Protocol
 
@@ -45,11 +37,11 @@ When an object is serialized:
 |------|------------------------|
 | 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 |
+| Arrays | For primitive-like element types, pass through; for `Date`/`Date | null`, map to ISO strings; otherwise map and call `SerializeWithContext(ctx)` when available |
+| `Map<K,V>` | For primitive-like values, `Object.fromEntries(map.entries())`; for `Date`/`Date | null`, convert to ISO strings; otherwise call `SerializeWithContext(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) |
+| Nullable | Include `null` explicitly; for primitive-like and `Date` unions the generator avoids runtime `SerializeWithContext` checks |
+| Objects | Call `SerializeWithContext(ctx)` if available (to support user-defined implementations) |
 
 Note: the generator specializes some code paths based on the declared TypeScript type to
 avoid runtime feature detection on primitives and literal unions.
@@ -58,34 +50,144 @@ avoid runtime feature detection on primitives and literal unions.
 
 The `@serde` decorator supports:
 
-- `skip` / `skip_serializing` - Exclude field from serialization
+- `skip` / `skipSerializing` - Exclude field from serialization
 - `rename = "jsonKey"` - Use different JSON property name
 - `flatten` - Merge nested object's fields into parent
 
 ## Example
 
-```typescript
-@derive(Serialize)
+```typescript before
+/** @derive(Serialize) */
 class User {
     id: number;
 
-    @serde(rename = "userName")
+    /** @serde({ rename: "userName" }) */
     name: string;
 
-    @serde(skip_serializing)
+    /** @serde({ skipSerializing: true }) */
     password: string;
 
-    @serde(flatten)
+    /** @serde({ flatten: true }) */
     metadata: UserMetadata;
 }
+```
+
+```typescript after
+import { SerializeContext } from 'macroforge/serde';
+
+class User {
+    id: number;
 
-// Usage:
-const user = new User();
-const json = user.toStringifiedJSON();
-// => '{"__type":"User","__id":1,"id":1,"userName":"Alice",...}'
+    name: string;
+
+    password: string;
+
+    metadata: UserMetadata;
+    /** Serializes a value to a JSON string.
+@param value - The value to serialize
+@returns JSON string representation with cycle detection metadata  */
+
+    static serialize(value: User): string {
+        return userSerialize(value);
+    }
+    /** @internal Serializes with an existing context for nested/cyclic object graphs.
+@param value - The value to serialize
+@param ctx - The serialization context  */
+
+    static serializeWithContext(value: User, ctx: SerializeContext): Record<string, unknown> {
+        return userSerializeWithContext(value, ctx);
+    }
+}
 
-const obj = user.toObject();
-// => { __type: "User", __id: 1, id: 1, userName: "Alice", ... }
+/** Serializes a value to a JSON string.
+@param value - The value to serialize
+@returns JSON string representation with cycle detection metadata */ export function userSerialize(
+    value: User
+): string {
+    const ctx = SerializeContext.create();
+    return JSON.stringify(userSerializeWithContext(value, ctx));
+} /** @internal Serializes with an existing context for nested/cyclic object graphs.
+@param value - The value to serialize
+@param ctx - The serialization context */
+export function userSerializeWithContext(
+    value: User,
+    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: 'User', __id };
+    result['id'] = value.id;
+    result['userName'] = value.name;
+    {
+        const __flattened = userMetadataSerializeWithContext(value.metadata, ctx);
+        const { __type: _, __id: __, ...rest } = __flattened as any;
+        Object.assign(result, rest);
+    }
+    return result;
+}
+```
+
+Generated output:
+
+```typescript
+import { SerializeContext } from 'macroforge/serde';
+
+class User {
+    id: number;
+
+    name: string;
+
+    password: string;
+
+    metadata: UserMetadata;
+    /** Serializes a value to a JSON string.
+@param value - The value to serialize
+@returns JSON string representation with cycle detection metadata  */
+
+    static serialize(value: User): string {
+        return userSerialize(value);
+    }
+    /** @internal Serializes with an existing context for nested/cyclic object graphs.
+@param value - The value to serialize
+@param ctx - The serialization context  */
+
+    static serializeWithContext(value: User, ctx: SerializeContext): Record<string, unknown> {
+        return userSerializeWithContext(value, ctx);
+    }
+}
+
+/** Serializes a value to a JSON string.
+@param value - The value to serialize
+@returns JSON string representation with cycle detection metadata */ export function userSerialize(
+    value: User
+): string {
+    const ctx = SerializeContext.create();
+    return JSON.stringify(userSerializeWithContext(value, ctx));
+} /** @internal Serializes with an existing context for nested/cyclic object graphs.
+@param value - The value to serialize
+@param ctx - The serialization context */
+export function userSerializeWithContext(
+    value: User,
+    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: 'User', __id };
+    result['id'] = value.id;
+    result['userName'] = value.name;
+    {
+        const __flattened = userMetadataSerializeWithContext(value.metadata, ctx);
+        const { __type: _, __id: __, ...rest } = __flattened as any;
+        Object.assign(result, rest);
+    }
+    return result;
+}
 ```
 
 ## Required Import

package/docs/concepts/architecture.md

@@ -37,8 +37,8 @@
  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};
+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};
 
 // Also available: raw crate access and SWC modules
 use macroforge_ts::swc_core;

package/docs/concepts/derive-system.md

@@ -25,21 +25,21 @@ class User {
 ```  ### The import macro Statement
  To use macros from external packages, you must declare them with `import macro`:
  ```
-/** import macro { MacroName } from "package-name"; */
+/** import macro { MacroName } from "package-name"; */
 ``` Syntax rules:
  - Must be inside a JSDoc comment (`/** */`)
  - Can appear anywhere in the file (typically at the top)
  - Multiple macros can be imported: `import macro { A, B } from "pkg";`
  - Multiple import statements can be used for different packages
  ```
-/** import macro { JSON, Validate } from "@my/macros"; */
-/** import macro { Builder } from "@other/macros"; */
+/** import macro { JSON, Validate } from "@my/macros"; */
+/** import macro { Builder } from "@other/macros"; */
 
 /** @derive(JSON, Validate, Builder) */
-class User {
+class User {
   name: string;
   email: string;
-}
+}
 ```  **Built-in macros Built-in macros (Debug, Clone, Default, Hash, Ord, PartialEq, PartialOrd, Serialize, Deserialize) do not require an import statement. ### Field Attributes
  Macros can define field-level attributes to customize behavior per field:
  ****Before:**
@@ -78,46 +78,32 @@ class User {
   
   metadata: Record<string, unknown>;
 
-  toString(): string {
-    const parts: string[] = [];
-    parts.push("userId: " + this.id);
-    parts.push("name: " + this.name);
-    parts.push("metadata: " + this.metadata);
-    return "User { " + parts.join(", ") + " }";
-}
-
-  toStringifiedJSON(): string {
-    const ctx = SerializeContext.create();
-    return JSON.stringify(this.__serialize(ctx));
+  static toString(value: User): string {
+    return userToString(value);
 }
+/** Serializes a value to a JSON string.
+@param value - The value to serialize
+@returns JSON string representation with cycle detection metadata  */
 
-  toObject(): Record<string, unknown> {
-    const ctx = SerializeContext.create();
-    return this.__serialize(ctx);
+  static serialize(value: User): string {
+    return userSerialize(value);
 }
+/** @internal Serializes with an existing context for nested/cyclic object graphs.
+@param value - The value to serialize
+@param ctx - The serialization context  */
 
-  __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["name"] = this.name;
-    {
-        const __flattened = record < string, unknown;
-        const { __type: _, __id: __, ...rest } = __flattened as any;
-        Object.assign(result, rest);
-    }
-    return result;
+  static serializeWithContext(value: User, ctx: SerializeContext): Record<string, unknown> {
+    return userSerializeWithContext(value, ctx);
 }
 }
+
+export function userToString(value: User): string {const parts: string[]= []; parts.push("userId: " + value.id); parts.push("name: " + value.name); parts.push("metadata: " + value.metadata); return "User { " + parts.join(", " )+ " }" ; }
+
+/** Serializes a value to a JSON string.
+@param value - The value to serialize
+@returns JSON string representation with cycle detection metadata */export function userSerialize(value: User): string {const ctx = SerializeContext.create(); return JSON.stringify(userSerializeWithContext(value, ctx));}/** @internal Serializes with an existing context for nested/cyclic object graphs.
+@param value - The value to serialize
+@param ctx - The serialization context */export function userSerializeWithContext(value: User, 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: "User" , __id,}; result["user_id" ]= value.id; result["name" ]= value.name; {const __flattened = record<string, unknown>SerializeWithContext(value.metadata, ctx); const {__type: _, __id: __,...rest}= __flattened as any; Object.assign(result, rest);}return result;}
 ``` Syntax rules:
  - Must be inside a JSDoc comment immediately before the field
  - Options use object literal syntax: `@attr({ key: value })`

package/docs/concepts/how-macros-work.md

@@ -18,12 +18,16 @@ class User {
 class User {
     name: string;
 
-    toString(): string {
-        const parts: string[] = [];
-        parts.push('name: ' + this.name);
-        return 'User { ' + parts.join(', ') + ' }';
+    static toString(value: User): string {
+        return userToString(value);
     }
 }
+
+export function userToString(value: User): string {
+    const parts: string[] = [];
+    parts.push('name: ' + value.name);
+    return 'User { ' + parts.join(', ') + ' }';
+}
 ``` ## Zero Runtime Overhead
  Because code generation happens at compile time, there's no:
  - Runtime reflection or metadata

package/docs/custom-macros/custom-overview.md

@@ -8,52 +8,52 @@
  4. Building and publishing as an npm package
  ## Quick Example
  ```
-use macroforge_ts::macros::{ts_macro_derive, body};
-use macroforge_ts::ts_syn::{Data, DeriveInput, MacroforgeError, TsStream, parse_ts_macro_input};
+use macroforge_ts::macros::{ts_macro_derive, body};
+use macroforge_ts::ts_syn::{Data, DeriveInput, MacroforgeError, TsStream, parse_ts_macro_input};
 
 #[ts_macro_derive(
     JSON,
     description = "Generates toJSON() returning a plain object"
 )]
-pub fn derive_json(mut input: TsStream) -> Result<TsStream, MacroforgeError> {
+pub fn derive_json(mut input: TsStream) -> Result&#x3C;TsStream, MacroforgeError> &#123;
     let input = parse_ts_macro_input!(input as DeriveInput);
 
-    match &input.data {
-        Data::Class(class) => {
-            Ok(body! {
-                toJSON(): Record<string, unknown> {
-                    return {
-                        {#for field in class.field_names()}
-                            @{field}: this.@{field},
-                        {/for}
-                    };
-                }
-            })
-        }
+    match &#x26;input.data &#123;
+        Data::Class(class) => &#123;
+            Ok(body! &#123;
+                toJSON(): Record&#x3C;string, unknown> &#123;
+                    return &#123;
+                        &#123;#for field in class.field_names()&#125;
+                            @&#123;field&#125;: this.@&#123;field&#125;,
+                        &#123;/for&#125;
+                    &#125;;
+                &#125;
+            &#125;)
+        &#125;
         _ => Err(MacroforgeError::new(
             input.decorator_span(),
             "@derive(JSON) only works on classes",
         )),
-    }
-}
+    &#125;
+&#125;
 ``` ## Using Custom Macros
  Once your macro package is published, users can import and use it:
  ```
-/** import macro { JSON } from "@my/macros"; */
+/** import macro &#123; JSON &#125; from "@my/macros"; */
 
 /** @derive(JSON) */
-class User {
+class User &#123;
   name: string;
   age: number;
 
-  constructor(name: string, age: number) {
+  constructor(name: string, age: number) &#123;
     this.name = name;
     this.age = age;
-  }
-}
+  &#125;
+&#125;
 
 const user = new User("Alice", 30);
-console.log(user.toJSON()); // { name: "Alice", age: 30 }
+console.log(user.toJSON()); // &#123; name: "Alice", age: 30 &#125;
 ``` > **Note:** The import macro comment tells Macroforge which package provides the macro. ## Getting Started
  Follow these guides to create your own macros:
  - [Set up a Rust macro crate](../docs/custom-macros/rust-setup)

package/docs/custom-macros/rust-setup.md

@@ -25,7 +25,7 @@ crate-type = ["cdylib"]
 
 [dependencies]
 macroforge_ts = "0.1"
-napi = { version = "3", features = ["napi8", "compat-mode"] }
+napi = { version = "3", features = ["napi8", "compat-mode"] }
 napi-derive = "3"
 
 [build-dependencies]
@@ -36,67 +36,67 @@ lto = true
 strip = true
 ``` ## Create build.rs
  ```
-fn main() {
+fn main() {
     napi_build::setup();
-}
+}
 ``` ## Create src/lib.rs
  ```
-use macroforge_ts::macros::{ts_macro_derive, body};
-use macroforge_ts::ts_syn::{
+use macroforge_ts::macros::{ts_macro_derive, body};
+use macroforge_ts::ts_syn::{
     Data, DeriveInput, MacroforgeError, TsStream, parse_ts_macro_input,
-};
+};
 
 #[ts_macro_derive(
     JSON,
     description = "Generates toJSON() returning a plain object"
 )]
-pub fn derive_json(mut input: TsStream) -> Result<TsStream, MacroforgeError> {
+pub fn derive_json(mut input: TsStream) -> Result&#x3C;TsStream, MacroforgeError> &#123;
     let input = parse_ts_macro_input!(input as DeriveInput);
 
-    match &input.data {
-        Data::Class(class) => {
-            Ok(body! {
-                toJSON(): Record<string, unknown> {
-                    return {
-                        {#for field in class.field_names()}
-                            @{field}: this.@{field},
-                        {/for}
-                    };
-                }
-            })
-        }
+    match &#x26;input.data &#123;
+        Data::Class(class) => &#123;
+            Ok(body! &#123;
+                toJSON(): Record&#x3C;string, unknown> &#123;
+                    return &#123;
+                        &#123;#for field in class.field_names()&#125;
+                            @&#123;field&#125;: this.@&#123;field&#125;,
+                        &#123;/for&#125;
+                    &#125;;
+                &#125;
+            &#125;)
+        &#125;
         _ => Err(MacroforgeError::new(
             input.decorator_span(),
             "@derive(JSON) only works on classes",
         )),
-    }
-}
+    &#125;
+&#125;
 ``` ## Create package.json
  ```
-{
+&#123;
   "name": "@my-org/macros",
   "version": "0.1.0",
   "main": "index.js",
   "types": "index.d.ts",
-  "napi": {
+  "napi": &#123;
     "name": "my-macros",
-    "triples": {
+    "triples": &#123;
       "defaults": true
-    }
-  },
+    &#125;
+  &#125;,
   "files": [
     "index.js",
     "index.d.ts",
     "*.node"
   ],
-  "scripts": {
+  "scripts": &#123;
     "build": "napi build --release",
     "prepublishOnly": "napi build --release"
-  },
-  "devDependencies": {
+  &#125;,
+  "devDependencies": &#123;
     "@napi-rs/cli": "^3.0.0-alpha.0"
-  }
-}
+  &#125;
+&#125;
 ``` ## Build the Package
  ```
 # Build the native addon