@macroforge/mcp-server 0.1.33 → 0.1.35

package/docs/builtin-macros/default.md

@@ -1,138 +1,102 @@
 # Default
 
-*The `Default` macro generates a static `defaultValue()` factory method that creates instances with default field values. It works like Rust's `#[derive(Default)]` trait.*
+The `Default` macro generates a static `defaultValue()` factory method that creates
+instances with default values. This is analogous to Rust's `Default` trait, providing
+a standard way to create "zero" or "empty" instances of types.
 
-## Basic Usage
+## Generated Output
 
-<MacroExample before={data.examples.basic.before} after={data.examples.basic.after} />
+| Type | Generated Code | Description |
+|------|----------------|-------------|
+| Class | `static defaultValue(): ClassName` | Static factory method |
+| Enum | `defaultValueEnumName(): EnumName` | Standalone function returning marked variant |
+| Interface | `defaultValueInterfaceName(): InterfaceName` | Standalone function returning object literal |
+| Type Alias | `defaultValueTypeName(): TypeName` | Standalone function with type-appropriate default |
 
-```typescript
-const config = Config.defaultValue();
-console.log(config.host);    // ""
-console.log(config.port);    // 0
-console.log(config.enabled); // false
-```
-
-## Automatic Default Values
-
-Like Rust's `Default` trait, the macro automatically determines default values for primitive types and common collections:
-
-| `string` | `""` | `String::default()` 
-
-| `number` | `0` | `i32::default()` 
-
-| `boolean` | `false` | `bool::default()` 
-
-| `bigint` | `0n` | `i64::default()` 
-
-| `T[]` / `Array<T>` | `[]` | `Vec::default()` 
-
-| `Map<K, V>` | `new Map()` | `HashMap::default()` 
-
-| `Set<T>` | `new Set()` | `HashSet::default()` 
-
-| `Date` | `new Date()` | — 
-
-| `T | null` / `T | undefined` | `null` | `Option::default()` 
-
-| Custom types | **Error** | **Error** (needs `impl Default`)
-
-## Nullable Types (like Rust's Option)
-
-Just like Rust's `Option<T>` defaults to `None`, nullable TypeScript types automatically default to `null`:
-
-<MacroExample before={data.examples.nullable.before} after={data.examples.nullable.after} />
-
-```typescript
-const user = User.defaultValue();
-console.log(user.name);     // ""
-console.log(user.email);    // null (nullable type)
-console.log(user.age);      // 0
-console.log(user.metadata); // null (nullable type)
-```
-
-## Custom Types Require @default
-
-Just like Rust requires `impl Default` for custom types, Macroforge requires the `@default()` decorator on fields with non-primitive types:
-
-<MacroExample before={data.examples.customType.before} after={data.examples.customType.after} />
-
-<p class="text-red-500 text-sm mt-2">
-Without `@default` on custom type fields, the macro will emit an error:
-</p>
+## Configuration
 
-```text
-// Error: @derive(Default) cannot determine default for non-primitive fields.
-// Add @default(value) to: settings, permissions
-```
+The `functionNamingStyle` option in `macroforge.json` controls naming:
+- `"suffix"` (default): Suffixes with type name (e.g., `defaultValueMyType`)
+- `"prefix"`: Prefixes with type name (e.g., `myTypeDefaultValue`)
+- `"generic"`: Uses TypeScript generics (e.g., `defaultValue<T extends MyType>`)
+- `"namespace"`: Legacy namespace wrapping
 
-## Custom Default Values
+## Default Values by Type
 
-Use the `@default()` decorator to specify custom default values for any field:
+The macro uses Rust-like default semantics:
 
-<MacroExample before={data.examples.custom.before} after={data.examples.custom.after} />
+| Type | Default Value |
+|------|---------------|
+| `string` | `""` (empty string) |
+| `number` | `0` |
+| `boolean` | `false` |
+| `bigint` | `0n` |
+| `T[]` | `[]` (empty array) |
+| `Array<T>` | `[]` (empty array) |
+| `Map<K,V>` | `new Map()` |
+| `Set<T>` | `new Set()` |
+| `Date` | `new Date()` (current time) |
+| `T \| null` | `null` |
+| `CustomType` | `CustomType.defaultValue()` (recursive) |
 
-```typescript
-const config = ServerConfig.defaultValue();
-console.log(config.host);      // "localhost"
-console.log(config.port);      // 8080
-console.log(config.enabled);   // true
-console.log(config.logLevels); // ["info", "error"]
-```
+## Field-Level Options
 
-## Interface Support
+The `@default` decorator allows specifying explicit default values:
 
-Default also works with interfaces. For interfaces, a namespace is generated with a `defaultValue()` function:
+- `@default(42)` - Use 42 as the default
+- `@default("hello")` - Use "hello" as the default
+- `@default([])` - Use empty array as the default
+- `@default({ value: "test" })` - Named form for complex values
 
-<MacroExample before={data.examples.interface.before} after={data.examples.interface.after} />
+## Example
 
 ```typescript
-const origin = Point.defaultValue();
-console.log(origin); // { x: 0, y: 0 }
+@derive(Default)
+class UserSettings {
+    @default("light")
+    theme: string;
+
+    @default(10)
+    pageSize: number;
+
+    notifications: boolean;  // Uses type default: false
+}
+
+// Generated:
+// static defaultValue(): UserSettings {
+//     const instance = new UserSettings();
+//     instance.theme = "light";
+//     instance.pageSize = 10;
+//     instance.notifications = false;
+//     return instance;
+// }
 ```
 
-## Enum Support
+## Enum Defaults
 
-Default works with enums. For enums, it returns the first variant as the default value:
-
-<MacroExample before={data.examples.enum.before} after={data.examples.enum.after} />
+For enums, mark one variant with `@default`:
 
 ```typescript
-const defaultStatus = Status.defaultValue();
-console.log(defaultStatus); // "pending"
+@derive(Default)
+enum Status {
+    @default
+    Pending,
+    Active,
+    Completed
+}
+
+// Generated:
+// export namespace Status {
+//     export function defaultValue(): Status {
+//         return Status.Pending;
+//     }
+// }
 ```
 
-## Type Alias Support
-
-Default works with type aliases. For object types, it creates an object with default field values:
+## Error Handling
 
-<MacroExample before={data.examples.typeAlias.before} after={data.examples.typeAlias.after} />
-
-```typescript
-const dims = Dimensions.defaultValue();
-console.log(dims); // { width: 0, height: 0 }
-```
-
-## Combining with Other Macros
-
-<InteractiveMacro code={`/** @derive(Default, Debug, Clone, PartialEq) */
-class User {
-  /** @default("Anonymous") */
-  name: string;
-
-  /** @default(0) */
-  age: number;
-
-  constructor(name: string, age: number) {
-    this.name = name;
-    this.age = age;
-  }
-}`} />
-
-```typescript
-const user1 = User.defaultValue();
-const user2 = user1.clone();
+The macro will return an error if:
 
-console.log(user1.toString());    // User { name: "Anonymous", age: 0 }
-console.log(user1.equals(user2)); // true
-```
+- A non-primitive field lacks `@default` and has no known default
+- An enum has no variant marked with `@default`
+- A union type has no `@default` on a variant

package/docs/builtin-macros/deserialize.md

@@ -1,317 +1,137 @@
 # Deserialize
 
-*The `Deserialize` macro generates a static `fromJSON()` method that parses JSON data into your class with runtime validation and automatic type conversion.*
+The `Deserialize` macro generates JSON deserialization methods with **cycle and
+forward-reference support**, plus comprehensive runtime validation. This enables
+safe parsing of complex JSON structures including circular references.
 
-## Basic Usage
+## Generated Output
 
-<MacroExample before={data.examples.basic.before} after={data.examples.basic.after} />
+| Type | Generated Code | Description |
+|------|----------------|-------------|
+| Class | `static fromStringifiedJSON()`, `static fromObject()`, `static __deserialize()` | Static factory methods |
+| Enum | `fromStringifiedJSONEnumName(json)`, `__deserializeEnumName(data)`, `isEnumName(value)` | Standalone functions |
+| Interface | `fromStringifiedJSONInterfaceName(json)`, `fromObjectInterfaceName(obj)`, etc. | Standalone functions |
+| Type Alias | `fromStringifiedJSONTypeName(json)`, `fromObjectTypeName(obj)`, etc. | Standalone functions |
 
-```typescript
-const json = '{"name":"Alice","age":30,"createdAt":"2024-01-15T10:30:00.000Z"}';
-const user = User.fromJSON(JSON.parse(json));
+## Configuration
 
-console.log(user.name);                    // "Alice"
-console.log(user.age);                     // 30
-console.log(user.createdAt instanceof Date); // true
-```
+The `functionNamingStyle` option in `macroforge.json` controls naming:
+- `"suffix"` (default): Suffixes with type name (e.g., `fromStringifiedJSONMyType`)
+- `"prefix"`: Prefixes with type name (e.g., `myTypeFromStringifiedJSON`)
+- `"generic"`: Uses TypeScript generics (e.g., `fromStringifiedJSON<T extends MyType>`)
+- `"namespace"`: Legacy namespace wrapping
 
-## Runtime Validation
+## Return Type
 
-Deserialize validates the input data and throws descriptive errors:
+All public deserialization methods return `Result<T, Array<{ field: string; message: string }>>`:
 
-<InteractiveMacro code={`/** @derive(Deserialize) */
-class User {
-  name: string;
-  email: string;
-}`} />
+- `Result.ok(value)` - Successfully deserialized value
+- `Result.err(errors)` - Array of validation errors with field names and messages
 
-```typescript
-// Missing required field
-User.fromJSON({ name: "Alice" });
-// Error: User.fromJSON: missing required field "email"
+## Cycle/Forward-Reference Support
 
-// Wrong type
-User.fromJSON("not an object");
-// Error: User.fromJSON: expected an object, got string
+Uses deferred patching to handle references:
 
-// Array instead of object
-User.fromJSON([1, 2, 3]);
-// Error: User.fromJSON: expected an object, got array
-```
+1. When encountering `{ "__ref": id }`, returns a `PendingRef` marker
+2. Continues deserializing other fields
+3. After all objects are created, `ctx.applyPatches()` resolves all pending references
 
-## Automatic Type Conversion
+References only apply to object-shaped, serializable values. The generator avoids probing for
+`__ref` on primitive-like fields (including literal unions and `T | null` where `T` is primitive-like),
+and it parses `Date` / `Date | null` from ISO strings without treating them as references.
 
-Deserialize automatically converts JSON types to their TypeScript equivalents:
+## Validation
 
-| string/number/boolean 
-| `string`/`number`/`boolean` 
-| Direct assignment 
+The macro supports 30+ validators via `@serde(validate(...))`:
 
-| ISO string 
-| `Date` 
-| `new Date(string)` 
+### String Validators
+- `email`, `url`, `uuid` - Format validation
+- `minLength(n)`, `maxLength(n)`, `length(n)` - Length constraints
+- `pattern("regex")` - Regular expression matching
+- `nonEmpty`, `trimmed`, `lowercase`, `uppercase` - String properties
 
-| array 
-| `T[]` 
-| Maps items with auto-detection 
+### Number Validators
+- `gt(n)`, `gte(n)`, `lt(n)`, `lte(n)`, `between(min, max)` - Range checks
+- `int`, `positive`, `nonNegative`, `finite` - Number properties
 
-| object 
-| `Map<K, V>` 
-| `new Map(Object.entries())` 
+### Array Validators
+- `minItems(n)`, `maxItems(n)`, `itemsCount(n)` - Collection size
 
-| array 
-| `Set<T>` 
-| `new Set(array)` 
+### Date Validators
+- `validDate`, `afterDate("ISO")`, `beforeDate("ISO")` - Date validation
 
-| object 
-| Nested class 
-| Calls `fromJSON()` if available
+## Field-Level Options
 
-## Serde Options
+The `@serde` decorator supports:
 
-Use the `@serde` decorator to customize deserialization:
-
-### Renaming Fields
-
-<MacroExample before={data.examples.rename.before} after={data.examples.rename.after} />
-
-```typescript
-const user = User.fromJSON({ user_id: "123", full_name: "Alice" });
-console.log(user.id);   // "123"
-console.log(user.name); // "Alice"
-```
+- `skip` / `skip_deserializing` - Exclude field from deserialization
+- `rename = "jsonKey"` - Read from different JSON property
+- `default` / `default = expr` - Use default value if missing
+- `flatten` - Read fields from parent object level
+- `validate(...)` - Apply validators
 
-### Default Values
+## Container-Level Options
 
-<MacroExample before={data.examples.default.before} after={data.examples.default.after} />
+- `deny_unknown_fields` - Error on unrecognized JSON properties
+- `rename_all = "camelCase"` - Apply naming convention to all fields
 
-```typescript
-const config = Config.fromJSON({ host: "localhost" });
-console.log(config.port);  // "3000"
-console.log(config.debug); // false
-```
+## Union Type Deserialization
 
-### Skipping Fields
+Union types are deserialized based on their member types:
 
-<InteractiveMacro code={`/** @derive(Deserialize) */
-class User {
-  name: string;
-  email: string;
+### Literal Unions
+For unions of literal values (`"A" | "B" | 123`), the value is validated against
+the allowed literals directly.
 
-  /** @serde({ skip: true }) */
-  cachedData: unknown;
+### Primitive Unions
+For unions containing primitive types (`string | number`), the deserializer uses
+`typeof` checks to validate the value type. No `__type` discriminator is needed.
 
-  /** @serde({ skip_deserializing: true }) */
-  computedField: string;
-}`} />
+### Class/Interface Unions
+For unions of serializable types (`User | Admin`), the deserializer requires a
+`__type` field in the JSON to dispatch to the correct type's `__deserialize` method.
 
-<Alert type="tip" title="skip vs skip_deserializing">
-Use `skip: true` to exclude from both serialization and deserialization.
-Use `skip_deserializing: true` to only skip during deserialization.
-</Alert>
+### Generic Type Parameters
+For generic unions like `type Result<T> = T | Error`, the generic type parameter `T`
+is passed through as-is since its concrete type is only known at the call site.
 
-### Deny Unknown Fields
+### Mixed Unions
+Mixed unions (e.g., `string | Date | User`) check in order:
+1. Literal values
+2. Primitives (via `typeof`)
+3. Date (via `instanceof` or ISO string parsing)
+4. Serializable types (via `__type` dispatch)
+5. Generic type parameters (pass-through)
 
-<InteractiveMacro code={`/** @derive(Deserialize) */
-/** @serde({ deny_unknown_fields: true }) */
-class StrictUser {
-  name: string;
-  email: string;
-}`} />
+## Example
 
 ```typescript
-// This will throw an error
-StrictUser.fromJSON({ name: "Alice", email: "a@b.com", extra: "field" });
-// Error: StrictUser.fromJSON: unknown field "extra"
-```
-
-### Flatten Nested Objects
-
-<InteractiveMacro code={`/** @derive(Deserialize) */
-class Address {
-  city: string;
-  zip: string;
-}
-
-/** @derive(Deserialize) */
+@derive(Deserialize)
+@serde(deny_unknown_fields)
 class User {
-  name: string;
+    id: number;
 
-  /** @serde({ flatten: true }) */
-  address: Address;
-}`} />
+    @serde(validate(email, maxLength(255)))
+    email: string;
 
-```typescript
-// Flat JSON structure
-const user = User.fromJSON({
-  name: "Alice",
-  city: "NYC",
-  zip: "10001"
-});
-console.log(user.address.city); // "NYC"
-```
-
-## All Options
-
-### Container Options (on class/interface)
-
-| `rename_all` 
-| `string` 
-| Apply naming convention to all fields 
-
-| `deny_unknown_fields` 
-| `boolean` 
-| Throw error if JSON has unknown keys
-
-### Field Options (on properties)
-
-| `rename` 
-| `string` 
-| Use a different JSON key 
-
-| `skip` 
-| `boolean` 
-| Exclude from serialization and deserialization 
-
-| `skip_deserializing` 
-| `boolean` 
-| Exclude from deserialization only 
-
-| `default` 
-| `boolean | string` 
-| Use TypeScript default or custom expression if missing 
-
-| `flatten` 
-| `boolean` 
-| Merge nested object fields from parent
-
-## Interface Support
-
-Deserialize also works with interfaces. For interfaces, a namespace is generated with `is` (type guard) and `fromJSON` functions:
-
-<MacroExample before={data.examples.interface.before} after={data.examples.interface.after} />
-
-```typescript
-const json = { status: 200, message: "OK", timestamp: "2024-01-15T10:30:00.000Z" };
+    @serde(default = "guest")
+    name: string;
 
-// Type guard
-if (ApiResponse.is(json)) {
-  console.log(json.status); // TypeScript knows this is ApiResponse
+    @serde(validate(positive))
+    age?: number;
 }
 
-// Deserialize with validation
-const response = ApiResponse.fromJSON(json);
-console.log(response.timestamp instanceof Date); // true
-```
-
-## Enum Support
-
-Deserialize also works with enums. The `fromJSON` function validates that the input matches one of the enum values:
-
-<MacroExample before={data.examples.enum.before} after={data.examples.enum.after} />
-
-```typescript
-const status = Status.fromJSON("active");
-console.log(status); // Status.Active
-
-// Invalid values throw an error
-try {
-  Status.fromJSON("invalid");
-} catch (e) {
-  console.log(e.message); // "Invalid Status value: invalid"
+// Usage:
+const result = User.fromStringifiedJSON('{"id":1,"email":"test@example.com"}');
+if (Result.isOk(result)) {
+    const user = result.value;
+} else {
+    console.error(result.error);  // [{ field: "email", message: "must be a valid email" }]
 }
 ```
 
-Works with numeric enums too:
-
-<InteractiveMacro code={`/** @derive(Deserialize) */
-enum Priority {
-  Low = 1,
-  Medium = 2,
-  High = 3,
-}`} />
-
-```typescript
-const priority = Priority.fromJSON(3);
-console.log(priority); // Priority.High
-```
-
-## Type Alias Support
-
-Deserialize works with type aliases. For object types, validation and type conversion is applied:
-
-<MacroExample before={data.examples.typeAlias.before} after={data.examples.typeAlias.after} />
-
-```typescript
-const json = {
-  id: "123",
-  name: "Alice",
-  createdAt: "2024-01-15T00:00:00.000Z"
-};
-
-const profile = UserProfile.fromJSON(json);
-console.log(profile.createdAt instanceof Date); // true
-```
-
-For union types, basic validation is applied:
-
-<InteractiveMacro code={`/** @derive(Deserialize) */
-type ApiStatus = "loading" | "success" | "error";`} />
-
-```typescript
-const status = ApiStatus.fromJSON("success");
-console.log(status); // "success"
-```
-
-## Combining with Serialize
-
-Use both Serialize and Deserialize for complete JSON round-trip support:
-
-<InteractiveMacro code={`/** @derive(Serialize, Deserialize) */
-/** @serde({ rename_all: "camelCase" }) */
-class UserProfile {
-  user_name: string;
-  created_at: Date;
-  is_active: boolean;
-}`} />
-
-```typescript
-// Create and serialize
-const profile = new UserProfile();
-profile.user_name = "Alice";
-profile.created_at = new Date();
-profile.is_active = true;
-
-const json = JSON.stringify(profile);
-// {"userName":"Alice","createdAt":"2024-...","isActive":true}
-
-// Deserialize back
-const restored = UserProfile.fromJSON(JSON.parse(json));
-console.log(restored.user_name);              // "Alice"
-console.log(restored.created_at instanceof Date); // true
-```
-
-## Error Handling
-
-Handle deserialization errors gracefully:
-
-<InteractiveMacro code={`/** @derive(Deserialize) */
-class User {
-  name: string;
-  email: string;
-}`} />
-
-```typescript
-function parseUser(json: unknown): User | null {
-  try {
-    return User.fromJSON(json);
-  } catch (error) {
-    console.error("Failed to parse user:", error.message);
-    return null;
-  }
-}
+## Required Imports
 
-const user = parseUser({ name: "Alice" });
-// Logs: Failed to parse user: User.fromJSON: missing required field "email"
-// Returns: null
-```
+The generated code automatically imports:
+- `Result` from `macroforge/utils`
+- `DeserializeContext`, `DeserializeError`, `PendingRef` from `macroforge/serde`