@macroforge/mcp-server 0.1.32 → 0.1.34

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

@@ -1,12 +1,40 @@
 # PartialOrd
+  *The `PartialOrd` macro generates a `compareTo()` method for **partial ordering** comparison. This is analogous to Rust's `PartialOrd` trait, enabling comparison between values where some pairs may be incomparable.*
+ ## Basic Usage
+ **Before:**
+```
+/** @derive(PartialOrd) */
+class Temperature {
+    celsius: number;
 
-*The `PartialOrd` macro generates a `compareTo()` method that implements partial ordering, returning `-1`, `0`, `1`, or `null` for incomparable values.*
-
-## Basic Usage
-
-<MacroExample before={data.examples.basic.before} after={data.examples.basic.after} />
-
-```typescript
+    constructor(celsius: number) {
+        this.celsius = celsius;
+    }
+}
+```  
+**After:**
+```
+import { Option } from 'macroforge/utils';
+
+class Temperature {
+    celsius: number;
+
+    constructor(celsius: number) {
+        this.celsius = celsius;
+    }
+
+    compareTo(other: unknown): Option<number> {
+        if (this === other) return Option.some(0);
+        if (!(other instanceof Temperature)) return Option.none();
+        const typedOther = other as Temperature;
+        const cmp0 =
+            this.celsius < typedOther.celsius ? -1 : this.celsius > typedOther.celsius ? 1 : 0;
+        if (cmp0 === null) return Option.none();
+        if (cmp0 !== 0) return Option.some(cmp0);
+        return Option.some(0);
+    }
+}
+``` ```
 const t1 = new Temperature(20);
 const t2 = new Temperature(30);
 const t3 = new Temperature(20);
@@ -17,67 +45,88 @@ console.log(t1.compareTo(t3)); // 0  (t1 == t3)
 
 // Returns null for incomparable types
 console.log(t1.compareTo("not a Temperature")); // null
+``` ## 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:
+ **Before:**
 ```
-
-## 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:
-
-<MacroExample before={data.examples.skip.before} after={data.examples.skip.after} />
-
-```typescript
+/** @derive(PartialOrd) */
+class Item {
+    price: number;
+    name: string;
+
+    /** @ord(skip) */
+    description: string;
+
+    constructor(price: number, name: string, description: string) {
+        this.price = price;
+        this.name = name;
+        this.description = description;
+    }
+}
+```  
+**After:**
+```
+import { Option } from 'macroforge/utils';
+
+class Item {
+    price: number;
+    name: string;
+
+    description: string;
+
+    constructor(price: number, name: string, description: string) {
+        this.price = price;
+        this.name = name;
+        this.description = description;
+    }
+
+    compareTo(other: unknown): Option<number> {
+        if (this === other) return Option.some(0);
+        if (!(other instanceof Item)) return Option.none();
+        const typedOther = other as Item;
+        const cmp0 = this.price < typedOther.price ? -1 : this.price > typedOther.price ? 1 : 0;
+        if (cmp0 === null) return Option.none();
+        if (cmp0 !== 0) return Option.some(cmp0);
+        const cmp1 = this.name.localeCompare(typedOther.name);
+        if (cmp1 === null) return Option.none();
+        if (cmp1 !== 0) return Option.some(cmp1);
+        return Option.some(0);
+    }
+}
+``` ```
 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:
+ **Source:**
 ```
-
-## Handling Null Results
-
-When using PartialOrd, always handle the `null` case:
-
-<InteractiveMacro code={`/** @derive(PartialOrd) */
+/** @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) {
@@ -94,22 +143,19 @@ function safeCompare(a: Value, b: unknown): string {
 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:
+ **Source:**
 ```
-
-## Sorting with PartialOrd
-
-When sorting, handle `null` values appropriately:
-
-<InteractiveMacro code={`/** @derive(PartialOrd) */
+/** @derive(PartialOrd) */
 class Score {
   value: number;
 
   constructor(value: number) {
     this.value = value;
   }
-}`} />
-
-```typescript
+}
+```  ```
 const scores = [
   new Score(100),
   new Score(50),
@@ -119,54 +165,120 @@ const scores = [
 // 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:
+ **Before:**
 ```
+/** @derive(PartialOrd) */
+interface Measurement {
+    value: number;
+    unit: string;
+}
+```  
+**After:**
+```
+import { Option } from 'macroforge/utils';
 
-## Interface Support
-
-PartialOrd works with interfaces. For interfaces, a namespace is generated with a `compareTo` function:
-
-<MacroExample before={data.examples.interface.before} after={data.examples.interface.after} />
+interface Measurement {
+    value: number;
+    unit: string;
+}
 
-```typescript
+export namespace Measurement {
+    export function compareTo(self: Measurement, other: Measurement): Option<number> {
+        if (self === other) return Option.some(0);
+        const cmp0 = self.value < other.value ? -1 : self.value > other.value ? 1 : 0;
+        if (cmp0 === null) return Option.none();
+        if (cmp0 !== 0) return Option.some(cmp0);
+        const cmp1 = self.unit.localeCompare(other.unit);
+        if (cmp1 === null) return Option.none();
+        if (cmp1 !== 0) return Option.some(cmp1);
+        return Option.some(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:
+ **Before:**
 ```
+/** @derive(PartialOrd) */
+enum Size {
+    Small = 1,
+    Medium = 2,
+    Large = 3
+}
+```  
+**After:**
+```
+import { Option } from 'macroforge/utils';
 
-## Enum Support
-
-PartialOrd works with enums:
-
-<MacroExample before={data.examples.enum.before} after={data.examples.enum.after} />
+enum Size {
+    Small = 1,
+    Medium = 2,
+    Large = 3
+}
 
-```typescript
+export namespace Size {
+    export function compareTo(a: Size, b: Size): Option<number> {
+        if (typeof a === 'number' && typeof b === 'number') {
+            return Option.some(a < b ? -1 : a > b ? 1 : 0);
+        }
+        if (typeof a === 'string' && typeof b === 'string') {
+            return Option.some(a.localeCompare(b));
+        }
+        return a === b ? Option.some(0) : Option.none();
+    }
+}
+``` ```
 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:
+ **Before:**
 ```
-
-## Type Alias Support
-
-PartialOrd works with type aliases:
-
-<MacroExample before={data.examples.typeAlias.before} after={data.examples.typeAlias.after} />
-
-```typescript
+/** @derive(PartialOrd) */
+type Interval = {
+    start: number;
+    end: number;
+};
+```  
+**After:**
+```
+import { Option } from 'macroforge/utils';
+
+type Interval = {
+    start: number;
+    end: number;
+};
+
+export namespace Interval {
+    export function compareTo(a: Interval, b: Interval): Option<number> {
+        if (a === b) return Option.some(0);
+        const cmp0 = a.start < b.start ? -1 : a.start > b.start ? 1 : 0;
+        if (cmp0 === null) return Option.none();
+        if (cmp0 !== 0) return Option.some(cmp0);
+        const cmp1 = a.end < b.end ? -1 : a.end > b.end ? 1 : 0;
+        if (cmp1 === null) return Option.none();
+        if (cmp1 !== 0) return Option.some(cmp1);
+        return Option.some(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
+ **Source:**
 ```
-
-## 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
-
-<InteractiveMacro code={`// PartialOrd is safer for public APIs that accept unknown input
+// PartialOrd is safer for public APIs that accept unknown input
 /** @derive(PartialOrd) */
 class SafeValue {
   data: number;
@@ -179,9 +291,8 @@ 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