@macroforge/mcp-server 0.1.17 → 0.1.21

package/docs/builtin-macros/partial-eq.md

@@ -4,18 +4,9 @@
 
 ## Basic Usage
 
-```typescript
-/** @derive(PartialEq) */
-class Point {
-  x: number;
-  y: number;
-
-  constructor(x: number, y: number) {
-    this.x = x;
-    this.y = y;
-  }
-}
+<MacroExample before={data.examples.basic.before} after={data.examples.basic.after} />
 
+```typescript
 const p1 = new Point(10, 20);
 const p2 = new Point(10, 20);
 const p3 = new Point(5, 5);
@@ -25,19 +16,6 @@ console.log(p1.equals(p3)); // false (different values)
 console.log(p1 === p2);     // false (different references)
 ```
 
-## Generated Code
-
-The PartialEq macro generates an equals method that compares each field:
-
-```typescript
-equals(other: unknown): boolean {
-    if (this === other) return true;
-    if (!(other instanceof Point)) return false;
-    const typedOther = other as Point;
-    return this.x === typedOther.x && this.y === typedOther.y;
-}
-```
-
 ## How It Works
 
 The PartialEq macro performs field-by-field comparison using these strategies:
@@ -60,22 +38,9 @@ The PartialEq macro performs field-by-field comparison using these strategies:
 
 Use `@partialEq(skip)` to exclude a field from equality comparison:
 
-```typescript
-/** @derive(PartialEq) */
-class User {
-  id: number;
-  name: string;
-
-  /** @partialEq(skip) */
-  createdAt: Date;  // Not compared
-
-  constructor(id: number, name: string, createdAt: Date) {
-    this.id = id;
-    this.name = name;
-    this.createdAt = createdAt;
-  }
-}
+<MacroExample before={data.examples.skip.before} after={data.examples.skip.after} />
 
+```typescript
 const user1 = new User(1, "Alice", new Date("2024-01-01"));
 const user2 = new User(1, "Alice", new Date("2024-12-01"));
 
@@ -86,27 +51,18 @@ console.log(user1.equals(user2)); // true (createdAt is skipped)
 
 The generated `equals()` method accepts `unknown` and performs runtime type checking:
 
-```typescript
-/** @derive(PartialEq) */
+<InteractiveMacro code={`/** @derive(PartialEq) */
 class User {
   name: string;
   constructor(name: string) {
     this.name = name;
   }
-}
-
-/** @derive(PartialEq) */
-class Admin {
-  name: string;
-  constructor(name: string) {
-    this.name = name;
-  }
-}
+}`} />
 
+```typescript
 const user = new User("Alice");
-const admin = new Admin("Alice");
 
-console.log(user.equals(admin)); // false (different types)
+console.log(user.equals(new User("Alice"))); // true
 console.log(user.equals("Alice")); // false (not a User instance)
 ```
 
@@ -114,8 +70,7 @@ console.log(user.equals("Alice")); // false (not a User instance)
 
 For objects with nested fields, PartialEq recursively calls `equals()` if available:
 
-```typescript
-/** @derive(PartialEq) */
+<InteractiveMacro code={`/** @derive(PartialEq) */
 class Address {
   city: string;
   zip: string;
@@ -135,8 +90,9 @@ class Person {
     this.name = name;
     this.address = address;
   }
-}
+}`} />
 
+```typescript
 const addr1 = new Address("NYC", "10001");
 const addr2 = new Address("NYC", "10001");
 
@@ -146,47 +102,13 @@ const p2 = new Person("Alice", addr2);
 console.log(p1.equals(p2)); // true (deep equality via Address.equals)
 ```
 
-## With Arrays
-
-```typescript
-/** @derive(PartialEq) */
-class Team {
-  name: string;
-  members: string[];
-
-  constructor(name: string, members: string[]) {
-    this.name = name;
-    this.members = members;
-  }
-}
-
-const t1 = new Team("Alpha", ["Alice", "Bob"]);
-const t2 = new Team("Alpha", ["Alice", "Bob"]);
-const t3 = new Team("Alpha", ["Alice", "Charlie"]);
-
-console.log(t1.equals(t2)); // true
-console.log(t1.equals(t3)); // false
-```
-
 ## Interface Support
 
 PartialEq works with interfaces. For interfaces, a namespace is generated with an `equals` function:
 
-```typescript
-/** @derive(PartialEq) */
-interface Point {
-  x: number;
-  y: number;
-}
-
-// Generated:
-// export namespace Point {
-//   export function equals(self: Point, other: Point): boolean {
-//     if (self === other) return true;
-//     return self.x === other.x && self.y === other.y;
-//   }
-// }
+<MacroExample before={data.examples.interface.before} after={data.examples.interface.after} />
 
+```typescript
 const p1: Point = { x: 10, y: 20 };
 const p2: Point = { x: 10, y: 20 };
 const p3: Point = { x: 5, y: 5 };
@@ -199,21 +121,9 @@ console.log(Point.equals(p1, p3)); // false
 
 PartialEq works with enums. For enums, strict equality comparison is used:
 
-```typescript
-/** @derive(PartialEq) */
-enum Status {
-  Active = "active",
-  Inactive = "inactive",
-  Pending = "pending",
-}
-
-// Generated:
-// export namespace Status {
-//   export function equals(a: Status, b: Status): boolean {
-//     return a === b;
-//   }
-// }
+<MacroExample before={data.examples.enum.before} after={data.examples.enum.after} />
 
+```typescript
 console.log(Status.equals(Status.Active, Status.Active));   // true
 console.log(Status.equals(Status.Active, Status.Inactive)); // false
 ```
@@ -222,21 +132,9 @@ console.log(Status.equals(Status.Active, Status.Inactive)); // false
 
 PartialEq works with type aliases. For object types, field-by-field comparison is used:
 
-```typescript
-/** @derive(PartialEq) */
-type Point = {
-  x: number;
-  y: number;
-};
-
-// Generated:
-// export namespace Point {
-//   export function equals(a: Point, b: Point): boolean {
-//     if (a === b) return true;
-//     return a.x === b.x && a.y === b.y;
-//   }
-// }
+<MacroExample before={data.examples.typeAlias.before} after={data.examples.typeAlias.after} />
 
+```typescript
 const p1: Point = { x: 10, y: 20 };
 const p2: Point = { x: 10, y: 20 };
 
@@ -245,10 +143,10 @@ console.log(Point.equals(p1, p2)); // true
 
 For union types, strict equality is used:
 
-```typescript
-/** @derive(PartialEq) */
-type ApiStatus = "loading" | "success" | "error";
+<InteractiveMacro code={`/** @derive(PartialEq) */
+type ApiStatus = "loading" | "success" | "error";`} />
 
+```typescript
 console.log(ApiStatus.equals("success", "success")); // true
 console.log(ApiStatus.equals("success", "error"));   // false
 ```
@@ -257,8 +155,7 @@ console.log(ApiStatus.equals("success", "error"));   // false
 
 ### Finding Items in Arrays
 
-```typescript
-/** @derive(PartialEq) */
+<InteractiveMacro code={`/** @derive(PartialEq) */
 class Product {
   sku: string;
   name: string;
@@ -267,8 +164,9 @@ class Product {
     this.sku = sku;
     this.name = name;
   }
-}
+}`} />
 
+```typescript
 const products = [
   new Product("A1", "Widget"),
   new Product("B2", "Gadget"),
@@ -285,8 +183,7 @@ console.log(found); // Product { sku: "B2", name: "Gadget" }
 
 When using objects as keys in Map-like structures, combine PartialEq with Hash:
 
-```typescript
-/** @derive(PartialEq, Hash) */
+<InteractiveMacro code={`/** @derive(PartialEq, Hash) */
 class Key {
   id: number;
   type: string;
@@ -295,8 +192,9 @@ class Key {
     this.id = id;
     this.type = type;
   }
-}
+}`} />
 
+```typescript
 const k1 = new Key(1, "user");
 const k2 = new Key(1, "user");
 

package/docs/builtin-macros/partial-ord.md

@@ -4,16 +4,9 @@
 
 ## Basic Usage
 
-```typescript
-/** @derive(PartialOrd) */
-class Temperature {
-  celsius: number;
-
-  constructor(celsius: number) {
-    this.celsius = celsius;
-  }
-}
+<MacroExample before={data.examples.basic.before} after={data.examples.basic.after} />
 
+```typescript
 const t1 = new Temperature(20);
 const t2 = new Temperature(30);
 const t3 = new Temperature(20);
@@ -26,22 +19,6 @@ console.log(t1.compareTo(t3)); // 0  (t1 == t3)
 console.log(t1.compareTo("not a Temperature")); // null
 ```
 
-## Generated Code
-
-The PartialOrd macro generates a compareTo method with runtime type checking:
-
-```typescript
-compareTo(other: unknown): number | null {
-    if (this === other) return 0;
-    if (!(other instanceof Temperature)) return null;
-    const typedOther = other as Temperature;
-    const cmp0 = (this.celsius < typedOther.celsius ? -1 : this.celsius > typedOther.celsius ? 1 : 0);
-    if (cmp0 === null) return null;
-    if (cmp0 !== 0) return cmp0;
-    return 0;
-}
-```
-
 ## Return Values
 
 The `compareTo()` method returns:
@@ -78,22 +55,9 @@ The PartialOrd macro compares fields in declaration order with type checking:
 
 Use `@ord(skip)` to exclude a field from ordering comparison:
 
-```typescript
-/** @derive(PartialOrd) */
-class Item {
-  price: number;
-  name: string;
-
-  /** @ord(skip) */
-  description: string;  // Not used for ordering
-
-  constructor(price: number, name: string, description: string) {
-    this.price = price;
-    this.name = name;
-    this.description = description;
-  }
-}
+<MacroExample before={data.examples.skip.before} after={data.examples.skip.after} />
 
+```typescript
 const i1 = new Item(10, "Widget", "A useful widget");
 const i2 = new Item(10, "Widget", "Different description");
 
@@ -104,16 +68,16 @@ console.log(i1.compareTo(i2)); // 0 (description is skipped)
 
 When using PartialOrd, always handle the `null` case:
 
-```typescript
-/** @derive(PartialOrd) */
+<InteractiveMacro code={`/** @derive(PartialOrd) */
 class Value {
   amount: number;
 
   constructor(amount: number) {
     this.amount = amount;
   }
-}
+}`} />
 
+```typescript
 function safeCompare(a: Value, b: unknown): string {
   const result = a.compareTo(b);
   if (result === null) {
@@ -136,16 +100,16 @@ console.log(safeCompare(v, "string"));       // "incomparable"
 
 When sorting, handle `null` values appropriately:
 
-```typescript
-/** @derive(PartialOrd) */
+<InteractiveMacro code={`/** @derive(PartialOrd) */
 class Score {
   value: number;
 
   constructor(value: number) {
     this.value = value;
   }
-}
+}`} />
 
+```typescript
 const scores = [
   new Score(100),
   new Score(50),
@@ -161,25 +125,9 @@ scores.sort((a, b) => a.compareTo(b) ?? 0);
 
 PartialOrd works with interfaces. For interfaces, a namespace is generated with a `compareTo` function:
 
-```typescript
-/** @derive(PartialOrd) */
-interface Measurement {
-  value: number;
-  unit: string;
-}
-
-// Generated:
-// export namespace Measurement {
-//   export function compareTo(self: Measurement, other: Measurement): number | null {
-//     if (self === other) return 0;
-//     const cmp0 = (self.value < other.value ? -1 : self.value > other.value ? 1 : 0);
-//     if (cmp0 !== 0) return cmp0;
-//     const cmp1 = self.unit.localeCompare(other.unit);
-//     if (cmp1 !== 0) return cmp1 < 0 ? -1 : 1;
-//     return 0;
-//   }
-// }
+<MacroExample before={data.examples.interface.before} after={data.examples.interface.after} />
 
+```typescript
 const m1: Measurement = { value: 10, unit: "kg" };
 const m2: Measurement = { value: 10, unit: "lb" };
 
@@ -190,21 +138,9 @@ console.log(Measurement.compareTo(m1, m2)); // 1 (kg > lb alphabetically)
 
 PartialOrd works with enums:
 
-```typescript
-/** @derive(PartialOrd) */
-enum Size {
-  Small = 1,
-  Medium = 2,
-  Large = 3
-}
-
-// Generated:
-// export namespace Size {
-//   export function compareTo(a: Size, b: Size): number | null {
-//     return a < b ? -1 : a > b ? 1 : 0;
-//   }
-// }
+<MacroExample before={data.examples.enum.before} after={data.examples.enum.after} />
 
+```typescript
 console.log(Size.compareTo(Size.Small, Size.Large)); // -1
 console.log(Size.compareTo(Size.Large, Size.Small)); // 1
 ```
@@ -213,25 +149,9 @@ console.log(Size.compareTo(Size.Large, Size.Small)); // 1
 
 PartialOrd works with type aliases:
 
-```typescript
-/** @derive(PartialOrd) */
-type Interval = {
-  start: number;
-  end: number;
-};
-
-// Generated:
-// export namespace Interval {
-//   export function compareTo(a: Interval, b: Interval): number | null {
-//     if (a === b) return 0;
-//     const cmp0 = (a.start < b.start ? -1 : a.start > b.start ? 1 : 0);
-//     if (cmp0 !== 0) return cmp0;
-//     const cmp1 = (a.end < b.end ? -1 : a.end > b.end ? 1 : 0);
-//     if (cmp1 !== 0) return cmp1;
-//     return 0;
-//   }
-// }
+<MacroExample before={data.examples.typeAlias.before} after={data.examples.typeAlias.after} />
 
+```typescript
 const i1: Interval = { start: 0, end: 10 };
 const i2: Interval = { start: 0, end: 20 };
 
@@ -246,8 +166,7 @@ Choose between `Ord` and `PartialOrd` based on your use case:
 
 - **PartialOrd** → Use when comparing with `unknown` types or when some values might be incomparable
 
-```typescript
-// PartialOrd is safer for public APIs that accept unknown input
+<InteractiveMacro code={`// PartialOrd is safer for public APIs that accept unknown input
 /** @derive(PartialOrd) */
 class SafeValue {
   data: number;
@@ -260,8 +179,9 @@ class SafeValue {
     const result = this.compareTo(other);
     return result !== null && result > 0;
   }
-}
+}`} />
 
+```typescript
 const safe = new SafeValue(100);
 console.log(safe.isGreaterThan(new SafeValue(50)));  // true
 console.log(safe.isGreaterThan("invalid"));          // false