@macroforge/mcp-server 0.1.17

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

@@ -0,0 +1,306 @@
+# PartialEq
+
+*The `PartialEq` macro generates an `equals()` method for value-based equality comparison between objects.*
+
+## Basic Usage
+
+```typescript
+/** @derive(PartialEq) */
+class Point {
+  x: number;
+  y: number;
+
+  constructor(x: number, y: number) {
+    this.x = x;
+    this.y = y;
+  }
+}
+
+const p1 = new Point(10, 20);
+const p2 = new Point(10, 20);
+const p3 = new Point(5, 5);
+
+console.log(p1.equals(p2)); // true (same values)
+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:
+
+- **Primitives** (string, number, boolean, null, undefined) → Strict equality (`===`)
+
+- **Date** → Compares timestamps via `getTime()`
+
+- **Array** → Length check + element-by-element comparison
+
+- **Map** → Size check + entry comparison
+
+- **Set** → Size check + membership verification
+
+- **Objects** → Calls `equals()` if available, otherwise `===`
+
+## Field Options
+
+### @partialEq(skip)
+
+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;
+  }
+}
+
+const user1 = new User(1, "Alice", new Date("2024-01-01"));
+const user2 = new User(1, "Alice", new Date("2024-12-01"));
+
+console.log(user1.equals(user2)); // true (createdAt is skipped)
+```
+
+## Type Safety
+
+The generated `equals()` method accepts `unknown` and performs runtime type checking:
+
+```typescript
+/** @derive(PartialEq) */
+class User {
+  name: string;
+  constructor(name: string) {
+    this.name = name;
+  }
+}
+
+/** @derive(PartialEq) */
+class Admin {
+  name: string;
+  constructor(name: string) {
+    this.name = name;
+  }
+}
+
+const user = new User("Alice");
+const admin = new Admin("Alice");
+
+console.log(user.equals(admin)); // false (different types)
+console.log(user.equals("Alice")); // false (not a User instance)
+```
+
+## With Nested Objects
+
+For objects with nested fields, PartialEq recursively calls `equals()` if available:
+
+```typescript
+/** @derive(PartialEq) */
+class Address {
+  city: string;
+  zip: string;
+
+  constructor(city: string, zip: string) {
+    this.city = city;
+    this.zip = zip;
+  }
+}
+
+/** @derive(PartialEq) */
+class Person {
+  name: string;
+  address: Address;
+
+  constructor(name: string, address: Address) {
+    this.name = name;
+    this.address = address;
+  }
+}
+
+const addr1 = new Address("NYC", "10001");
+const addr2 = new Address("NYC", "10001");
+
+const p1 = new Person("Alice", addr1);
+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;
+//   }
+// }
+
+const p1: Point = { x: 10, y: 20 };
+const p2: Point = { x: 10, y: 20 };
+const p3: Point = { x: 5, y: 5 };
+
+console.log(Point.equals(p1, p2)); // true
+console.log(Point.equals(p1, p3)); // false
+```
+
+## Enum Support
+
+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;
+//   }
+// }
+
+console.log(Status.equals(Status.Active, Status.Active));   // true
+console.log(Status.equals(Status.Active, Status.Inactive)); // false
+```
+
+## Type Alias Support
+
+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;
+//   }
+// }
+
+const p1: Point = { x: 10, y: 20 };
+const p2: Point = { x: 10, y: 20 };
+
+console.log(Point.equals(p1, p2)); // true
+```
+
+For union types, strict equality is used:
+
+```typescript
+/** @derive(PartialEq) */
+type ApiStatus = "loading" | "success" | "error";
+
+console.log(ApiStatus.equals("success", "success")); // true
+console.log(ApiStatus.equals("success", "error"));   // false
+```
+
+## Common Patterns
+
+### Finding Items in Arrays
+
+```typescript
+/** @derive(PartialEq) */
+class Product {
+  sku: string;
+  name: string;
+
+  constructor(sku: string, name: string) {
+    this.sku = sku;
+    this.name = name;
+  }
+}
+
+const products = [
+  new Product("A1", "Widget"),
+  new Product("B2", "Gadget"),
+  new Product("C3", "Gizmo")
+];
+
+const target = new Product("B2", "Gadget");
+const found = products.find(p => p.equals(target));
+
+console.log(found); // Product { sku: "B2", name: "Gadget" }
+```
+
+### Use with Hash
+
+When using objects as keys in Map-like structures, combine PartialEq with Hash:
+
+```typescript
+/** @derive(PartialEq, Hash) */
+class Key {
+  id: number;
+  type: string;
+
+  constructor(id: number, type: string) {
+    this.id = id;
+    this.type = type;
+  }
+}
+
+const k1 = new Key(1, "user");
+const k2 = new Key(1, "user");
+
+// Equal objects should have equal hash codes
+console.log(k1.equals(k2));                   // true
+console.log(k1.hashCode() === k2.hashCode()); // true
+```

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

@@ -0,0 +1,268 @@
+# PartialOrd
+
+*The `PartialOrd` macro generates a `compareTo()` method that implements partial ordering, returning `-1`, `0`, `1`, or `null` for incomparable values.*
+
+## Basic Usage
+
+```typescript
+/** @derive(PartialOrd) */
+class Temperature {
+  celsius: number;
+
+  constructor(celsius: number) {
+    this.celsius = celsius;
+  }
+}
+
+const t1 = new Temperature(20);
+const t2 = new Temperature(30);
+const t3 = new Temperature(20);
+
+console.log(t1.compareTo(t2)); // -1 (t1 < t2)
+console.log(t2.compareTo(t1)); // 1  (t2 > t1)
+console.log(t1.compareTo(t3)); // 0  (t1 == t3)
+
+// Returns null for incomparable types
+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:
+
+- `-1` → `this` is less than `other`
+
+- `0` → `this` equals `other`
+
+- `1` → `this` is greater than `other`
+
+- `null` → Values are incomparable (e.g., different types)
+
+## Comparison Logic
+
+The PartialOrd macro compares fields in declaration order with type checking:
+
+- `number` / `bigint` → Direct numeric comparison
+
+- `string` → Uses `localeCompare()`
+
+- `boolean` → `false < true`
+
+- `Date` → Compares timestamps; returns `null` if not both Date instances
+
+- `Array` → Lexicographic comparison; returns `null` if not both arrays
+
+- `Object` → Calls `compareTo()` if available
+
+- **Type mismatch** → Returns `null`
+
+## Field Options
+
+### @ord(skip)
+
+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;
+  }
+}
+
+const i1 = new Item(10, "Widget", "A useful widget");
+const i2 = new Item(10, "Widget", "Different description");
+
+console.log(i1.compareTo(i2)); // 0 (description is skipped)
+```
+
+## Handling Null Results
+
+When using PartialOrd, always handle the `null` case:
+
+```typescript
+/** @derive(PartialOrd) */
+class Value {
+  amount: number;
+
+  constructor(amount: number) {
+    this.amount = amount;
+  }
+}
+
+function safeCompare(a: Value, b: unknown): string {
+  const result = a.compareTo(b);
+  if (result === null) {
+    return "incomparable";
+  } else if (result < 0) {
+    return "less than";
+  } else if (result > 0) {
+    return "greater than";
+  } else {
+    return "equal";
+  }
+}
+
+const v = new Value(100);
+console.log(safeCompare(v, new Value(50)));  // "greater than"
+console.log(safeCompare(v, "string"));       // "incomparable"
+```
+
+## Sorting with PartialOrd
+
+When sorting, handle `null` values appropriately:
+
+```typescript
+/** @derive(PartialOrd) */
+class Score {
+  value: number;
+
+  constructor(value: number) {
+    this.value = value;
+  }
+}
+
+const scores = [
+  new Score(100),
+  new Score(50),
+  new Score(75)
+];
+
+// Safe sort that handles null (treats null as equal)
+scores.sort((a, b) => a.compareTo(b) ?? 0);
+// Result: [Score(50), Score(75), Score(100)]
+```
+
+## Interface Support
+
+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;
+//   }
+// }
+
+const m1: Measurement = { value: 10, unit: "kg" };
+const m2: Measurement = { value: 10, unit: "lb" };
+
+console.log(Measurement.compareTo(m1, m2)); // 1 (kg > lb alphabetically)
+```
+
+## Enum Support
+
+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;
+//   }
+// }
+
+console.log(Size.compareTo(Size.Small, Size.Large)); // -1
+console.log(Size.compareTo(Size.Large, Size.Small)); // 1
+```
+
+## Type Alias Support
+
+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;
+//   }
+// }
+
+const i1: Interval = { start: 0, end: 10 };
+const i2: Interval = { start: 0, end: 20 };
+
+console.log(Interval.compareTo(i1, i2)); // -1
+```
+
+## PartialOrd vs Ord
+
+Choose between `Ord` and `PartialOrd` based on your use case:
+
+- **Ord** → Use when all values are always comparable (never returns null)
+
+- **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
+/** @derive(PartialOrd) */
+class SafeValue {
+  data: number;
+  constructor(data: number) {
+    this.data = data;
+  }
+
+  // Can safely compare with any value
+  isGreaterThan(other: unknown): boolean {
+    const result = this.compareTo(other);
+    return result !== null && result > 0;
+  }
+}
+
+const safe = new SafeValue(100);
+console.log(safe.isGreaterThan(new SafeValue(50)));  // true
+console.log(safe.isGreaterThan("invalid"));          // false
+```