@macroforge/mcp-server 0.1.37 → 0.1.39

package/docs/builtin-macros/deserialize/overview.md

@@ -1,16 +1,21 @@
 # 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 | `classNameDeserialize(input)` + `static deserialize(input)` | Standalone function + static factory method |
+| Enum | `enumNameDeserialize(input)`, `enumNameDeserializeWithContext(data)`, `enumNameIs(value)` | Standalone functions |
+| Interface | `interfaceNameDeserialize(input)`, etc. | Standalone functions |
+| Type Alias | `typeNameDeserialize(input)`, etc. | Standalone functions |
 
-```typescript
-const json = '{"name":"Alice","age":30,"createdAt":"2024-01-15T10:30:00.000Z"}';
-const user = User.fromJSON(JSON.parse(json));
+## Return Type
 
-console.log(user.name);                    // "Alice"
-console.log(user.age);                     // 30
-console.log(user.createdAt instanceof Date); // true
-```
+All public deserialization methods return `Result<T, Array<{ field: string; message: string }>>`:
+
+- `Result.ok(value)` - Successfully deserialized value
+- `Result.err(errors)` - Array of validation errors with field names and messages

package/docs/builtin-macros/deserialize/union-type-deserialization.md

@@ -0,0 +1,27 @@
+## Union Type Deserialization
+
+Union types are deserialized based on their member types:
+
+### Literal Unions
+For unions of literal values (`"A" | "B" | 123`), the value is validated against
+the allowed literals directly.
+
+### Primitive Unions
+For unions containing primitive types (`string | number`), the deserializer uses
+`typeof` checks to validate the value type. No `__type` discriminator is needed.
+
+### 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 `deserializeWithContext` method.
+
+### 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.
+
+### 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)

package/docs/builtin-macros/deserialize/validation.md

@@ -0,0 +1,34 @@
+## Validation
+
+The macro supports 30+ validators via `@serde(validate(...))`:
+
+### 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
+
+### Number Validators
+- `gt(n)`, `gte(n)`, `lt(n)`, `lte(n)`, `between(min, max)` - Range checks
+- `int`, `positive`, `nonNegative`, `finite` - Number properties
+
+### Array Validators
+- `minItems(n)`, `maxItems(n)`, `itemsCount(n)` - Collection size
+
+### Date Validators
+- `validDate`, `afterDate("ISO")`, `beforeDate("ISO")` - Date validation
+
+## Field-Level Options
+
+The `@serde` decorator supports:
+
+- `skip` / `skipDeserializing` - 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
+
+## Container-Level Options
+
+- `denyUnknownFields` - Error on unrecognized JSON properties
+- `renameAll = "camelCase"` - Apply naming convention to all fields