@macroforge/mcp-server 0.1.32 → 0.1.34

package/docs/builtin-macros/hash.md

@@ -1,12 +1,54 @@
 # Hash
-
-*The `Hash` macro generates a `hashCode()` method that computes a numeric hash value based on field values.*
-
-## Basic Usage
-
-<MacroExample before={data.examples.basic.before} after={data.examples.basic.after} />
-
-```typescript
+  *The `Hash` macro generates a `hashCode()` method for computing numeric hash codes. This is analogous to Rust's `Hash` trait and Java's `hashCode()` method, enabling objects to be used as keys in hash-based collections.*
+ ## Basic Usage
+ **Before:**
+```
+/** @derive(Hash) */
+class Point {
+    x: number;
+    y: number;
+
+    constructor(x: number, y: number) {
+        this.x = x;
+        this.y = y;
+    }
+}
+```  
+**After:**
+```
+class Point {
+    x: number;
+    y: number;
+
+    constructor(x: number, y: number) {
+        this.x = x;
+        this.y = y;
+    }
+
+    hashCode(): number {
+        let hash = 17;
+        hash =
+            (hash * 31 +
+                (Number.isInteger(this.x)
+                    ? this.x | 0
+                    : this.x
+                          .toString()
+                          .split('')
+                          .reduce((h, c) => (h * 31 + c.charCodeAt(0)) | 0, 0))) |
+            0;
+        hash =
+            (hash * 31 +
+                (Number.isInteger(this.y)
+                    ? this.y | 0
+                    : this.y
+                          .toString()
+                          .split('')
+                          .reduce((h, c) => (h * 31 + c.charCodeAt(0)) | 0, 0))) |
+            0;
+        return hash;
+    }
+}
+``` ```
 const p1 = new Point(10, 20);
 const p2 = new Point(10, 20);
 const p3 = new Point(5, 5);
@@ -14,52 +56,80 @@ const p3 = new Point(5, 5);
 console.log(p1.hashCode()); // Same hash
 console.log(p2.hashCode()); // Same hash (equal values = equal hash)
 console.log(p3.hashCode()); // Different hash
+``` ## Hash Algorithm
+ The generated hash function uses the following algorithm for different types:
+ - `number` → Integers use bitwise OR (`| 0`), floats are stringified and hashed
+ - `string` → Character-by-character hash: `(h * 31 + charCode) | 0`
+ - `boolean` → `1231` for true, `1237` for false (Java convention)
+ - `bigint` → Converted to string and hashed character-by-character
+ - `Date` → Uses `getTime() | 0` for timestamp hash
+ - `Array` → Combines element hashes with `h * 31 + elementHash`
+ - `Map/Set` → Combines all entry hashes
+ - `Object` → Calls `hashCode()` if available, otherwise JSON stringifies and hashes
+ - `null` → Returns 0
+ - `undefined` → Returns 1
+ ## Field Options
+ ### @hash(skip)
+ Use `@hash(skip)` to exclude a field from hash computation:
+ **Before:**
 ```
-
-## Hash Algorithm
-
-The generated hash function uses the following algorithm for different types:
-
-- `number` → Integers use bitwise OR (`| 0`), floats are stringified and hashed
-
-- `string` → Character-by-character hash: `(h * 31 + charCode) | 0`
-
-- `boolean` → `1231` for true, `1237` for false (Java convention)
-
-- `bigint` → Converted to string and hashed character-by-character
-
-- `Date` → Uses `getTime() | 0` for timestamp hash
-
-- `Array` → Combines element hashes with `h * 31 + elementHash`
-
-- `Map/Set` → Combines all entry hashes
-
-- `Object` → Calls `hashCode()` if available, otherwise JSON stringifies and hashes
-
-- `null` → Returns 0
-
-- `undefined` → Returns 1
-
-## Field Options
-
-### @hash(skip)
-
-Use `@hash(skip)` to exclude a field from hash computation:
-
-<MacroExample before={data.examples.skip.before} after={data.examples.skip.after} />
-
-```typescript
+/** @derive(Hash) */
+class User {
+    id: number;
+    name: string;
+
+    /** @hash(skip) */
+    lastLogin: Date;
+
+    constructor(id: number, name: string, lastLogin: Date) {
+        this.id = id;
+        this.name = name;
+        this.lastLogin = lastLogin;
+    }
+}
+```  
+**After:**
+```
+class User {
+    id: number;
+    name: string;
+
+    lastLogin: Date;
+
+    constructor(id: number, name: string, lastLogin: Date) {
+        this.id = id;
+        this.name = name;
+        this.lastLogin = lastLogin;
+    }
+
+    hashCode(): number {
+        let hash = 17;
+        hash =
+            (hash * 31 +
+                (Number.isInteger(this.id)
+                    ? this.id | 0
+                    : this.id
+                          .toString()
+                          .split('')
+                          .reduce((h, c) => (h * 31 + c.charCodeAt(0)) | 0, 0))) |
+            0;
+        hash =
+            (hash * 31 +
+                (this.name ?? '').split('').reduce((h, c) => (h * 31 + c.charCodeAt(0)) | 0, 0)) |
+            0;
+        return hash;
+    }
+}
+``` ```
 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.hashCode() === user2.hashCode()); // true (lastLogin is skipped)
+``` ## Use with PartialEq
+ Hash is often used together with PartialEq. Objects that are equal should have the same hash code:
+ **Source:**
 ```
-
-## Use with PartialEq
-
-Hash is often used together with PartialEq. Objects that are equal should have the same hash code:
-
-<InteractiveMacro code={`/** @derive(Hash, PartialEq) */
+/** @derive(Hash, PartialEq) */
 class Product {
   sku: string;
   name: string;
@@ -68,56 +138,142 @@ class Product {
     this.sku = sku;
     this.name = name;
   }
-}`} />
-
-```typescript
+}
+```  ```
 const p1 = new Product("ABC123", "Widget");
 const p2 = new Product("ABC123", "Widget");
 
 // Equal objects have equal hash codes
 console.log(p1.equals(p2));                       // true
 console.log(p1.hashCode() === p2.hashCode());     // true
+``` ## Interface Support
+ Hash also works with interfaces. For interfaces, a namespace is generated with a `hashCode` function:
+ **Before:**
 ```
-
-## Interface Support
-
-Hash also works with interfaces. For interfaces, a namespace is generated with a `hashCode` function:
-
-<MacroExample before={data.examples.interface.before} after={data.examples.interface.after} />
-
-```typescript
+/** @derive(Hash) */
+interface Point {
+    x: number;
+    y: number;
+}
+```  
+**After:**
+```
+interface Point {
+    x: number;
+    y: number;
+}
+
+export namespace Point {
+    export function hashCode(self: Point): number {
+        let hash = 17;
+        hash =
+            (hash * 31 +
+                (Number.isInteger(self.x)
+                    ? self.x | 0
+                    : self.x
+                          .toString()
+                          .split('')
+                          .reduce((h, c) => (h * 31 + c.charCodeAt(0)) | 0, 0))) |
+            0;
+        hash =
+            (hash * 31 +
+                (Number.isInteger(self.y)
+                    ? self.y | 0
+                    : self.y
+                          .toString()
+                          .split('')
+                          .reduce((h, c) => (h * 31 + c.charCodeAt(0)) | 0, 0))) |
+            0;
+        return hash;
+    }
+}
+``` ```
 const p: Point = { x: 10, y: 20 };
 console.log(Point.hashCode(p)); // numeric hash value
+``` ## Enum Support
+ Hash works with enums. For string enums, it hashes the string value; for numeric enums, it uses the numeric value directly:
+ **Before:**
 ```
-
-## Enum Support
-
-Hash works with enums. For string enums, it hashes the string value; for numeric enums, it uses the numeric value directly:
-
-<MacroExample before={data.examples.enum.before} after={data.examples.enum.after} />
-
-```typescript
+/** @derive(Hash) */
+enum Status {
+    Active = 'active',
+    Inactive = 'inactive',
+    Pending = 'pending'
+}
+```  
+**After:**
+```
+enum Status {
+    Active = 'active',
+    Inactive = 'inactive',
+    Pending = 'pending'
+}
+
+export namespace Status {
+    export function hashCode(value: Status): number {
+        if (typeof value === 'string') {
+            let hash = 0;
+            for (let i = 0; i < value.length; i++) {
+                hash = (hash * 31 + value.charCodeAt(i)) | 0;
+            }
+            return hash;
+        }
+        return value as number;
+    }
+}
+``` ```
 console.log(Status.hashCode(Status.Active));   // consistent hash
 console.log(Status.hashCode(Status.Inactive)); // different hash
+``` ## Type Alias Support
+ Hash works with type aliases. For object types, it hashes each field:
+ **Before:**
 ```
-
-## Type Alias Support
-
-Hash works with type aliases. For object types, it hashes each field:
-
-<MacroExample before={data.examples.typeAlias.before} after={data.examples.typeAlias.after} />
-
-```typescript
+/** @derive(Hash) */
+type Coordinates = {
+    lat: number;
+    lng: number;
+};
+```  
+**After:**
+```
+type Coordinates = {
+    lat: number;
+    lng: number;
+};
+
+export namespace Coordinates {
+    export function hashCode(value: Coordinates): number {
+        let hash = 17;
+        hash =
+            (hash * 31 +
+                (Number.isInteger(value.lat)
+                    ? value.lat | 0
+                    : value.lat
+                          .toString()
+                          .split('')
+                          .reduce((h, c) => (h * 31 + c.charCodeAt(0)) | 0, 0))) |
+            0;
+        hash =
+            (hash * 31 +
+                (Number.isInteger(value.lng)
+                    ? value.lng | 0
+                    : value.lng
+                          .toString()
+                          .split('')
+                          .reduce((h, c) => (h * 31 + c.charCodeAt(0)) | 0, 0))) |
+            0;
+        return hash;
+    }
+}
+``` ```
 const loc: Coordinates = { lat: 40.7128, lng: -74.0060 };
 console.log(Coordinates.hashCode(loc));
+``` For union types, it uses JSON stringification as a fallback:
+ **Source:**
 ```
-
-For union types, it uses JSON stringification as a fallback:
-
-<InteractiveMacro code={`/** @derive(Hash) */
-type Result = "success" | "error" | "pending";`} />
-
-```typescript
+/** @derive(Hash) */
+type Result = "success" | "error" | "pending";
+```  ```
 console.log(Result.hashCode("success")); // hash of "success" string
 console.log(Result.hashCode("error"));   // hash of "error" string
 ```

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

@@ -1,50 +1,20 @@
 # Built-in Macros
-
-*Macroforge comes with built-in derive macros that cover the most common code generation needs. All macros work with classes, interfaces, enums, and type aliases.*
-
-## Overview
-
-| [`Debug`]({base}/docs/builtin-macros/debug) 
-| `toString(): string` 
-| Human-readable string representation 
-
-| [`Clone`]({base}/docs/builtin-macros/clone) 
-| `clone(): T` 
-| Creates a deep copy of the object 
-
-| [`Default`]({base}/docs/builtin-macros/default) 
-| `static default(): T` 
-| Creates an instance with default values 
-
-| [`Hash`]({base}/docs/builtin-macros/hash) 
-| `hashCode(): number` 
-| Generates a hash code for the object 
-
-| [`PartialEq`]({base}/docs/builtin-macros/partial-eq) 
-| `equals(other: T): boolean` 
-| Value equality comparison 
-
-| [`Ord`]({base}/docs/builtin-macros/ord) 
-| `compare(other: T): number` 
-| Total ordering comparison (-1, 0, 1) 
-
-| [`PartialOrd`]({base}/docs/builtin-macros/partial-ord) 
-| `partialCompare(other: T): number | null` 
-| Partial ordering comparison 
-
-| [`Serialize`]({base}/docs/builtin-macros/serialize) 
-| `toJSON(): Record<string, unknown>` 
-| JSON serialization with type handling 
-
-| [`Deserialize`]({base}/docs/builtin-macros/deserialize) 
-| `static fromJSON(data: unknown): T` 
-| JSON deserialization with validation
-
-## Using Built-in Macros
-
-Built-in macros don't require imports. Just use them with `@derive`:
-
-```typescript
+ *Macroforge comes with built-in derive macros that cover the most common code generation needs. All macros work with classes, interfaces, enums, and type aliases.*
+ ## Overview
+ | Macro | Generates | Description |
+| --- | --- | --- |
+| [`Debug`](../docs/builtin-macros/debug) | `toString(): string` | Human-readable string representation |
+| [`Clone`](../docs/builtin-macros/clone) | `clone(): T` | Creates a deep copy of the object |
+| [`Default`](../docs/builtin-macros/default) | `static default(): T` | Creates an instance with default values |
+| [`Hash`](../docs/builtin-macros/hash) | `hashCode(): number` | Generates a hash code for the object |
+| [`PartialEq`](../docs/builtin-macros/partial-eq) | `equals(other: T): boolean` | Value equality comparison |
+| [`Ord`](../docs/builtin-macros/ord) | `compare(other: T): number` | Total ordering comparison (-1, 0, 1) |
+| [`PartialOrd`](../docs/builtin-macros/partial-ord) | `partialCompare(other: T): number | null` | Partial ordering comparison |
+| [`Serialize`](../docs/builtin-macros/serialize) | `toJSON(): Record<string, unknown>` | JSON serialization with type handling |
+| [`Deserialize`](../docs/builtin-macros/deserialize) | `static fromJSON(data: unknown): T` | JSON deserialization with validation |
+ ## Using Built-in Macros
+ Built-in macros don't require imports. Just use them with `@derive`:
+ ```
 /** @derive(Debug, Clone, PartialEq) */
 class User {
   name: string;
@@ -55,13 +25,9 @@ class User {
     this.age = age;
   }
 }
-```
-
-## Interface Support
-
-All built-in macros work with interfaces. For interfaces, methods are generated as functions in a namespace with the same name, using `self` as the first parameter:
-
-```typescript
+``` ## Interface Support
+ All built-in macros work with interfaces. For interfaces, methods are generated as functions in a namespace with the same name, using `self` as the first parameter:
+ ```
 /** @derive(Debug, Clone, PartialEq) */
 interface Point {
   x: number;
@@ -82,13 +48,9 @@ const point: Point = { x: 10, y: 20 };
 console.log(Point.toString(point));     // "Point { x: 10, y: 20 }"
 const copy = Point.clone(point);        // { x: 10, y: 20 }
 console.log(Point.equals(point, copy)); // true
-```
-
-## Enum Support
-
-All built-in macros work with enums. For enums, methods are generated as functions in a namespace with the same name:
-
-```typescript
+``` ## Enum Support
+ All built-in macros work with enums. For enums, methods are generated as functions in a namespace with the same name:
+ ```
 /** @derive(Debug, Clone, PartialEq, Serialize, Deserialize) */
 enum Status {
   Active = "active",
@@ -111,13 +73,9 @@ console.log(Status.toString(Status.Active));     // "Status.Active"
 console.log(Status.equals(Status.Active, Status.Active)); // true
 const json = Status.toJSON(Status.Pending);      // "pending"
 const parsed = Status.fromJSON("active");        // Status.Active
-```
-
-## Type Alias Support
-
-All built-in macros work with type aliases. For object type aliases, field-aware methods are generated in a namespace:
-
-```typescript
+``` ## Type Alias Support
+ All built-in macros work with type aliases. For object type aliases, field-aware methods are generated in a namespace:
+ ```
 /** @derive(Debug, Clone, PartialEq, Serialize, Deserialize) */
 type Point = {
   x: number;
@@ -138,24 +96,17 @@ const point: Point = { x: 10, y: 20 };
 console.log(Point.toString(point));     // "Point { x: 10, y: 20 }"
 const copy = Point.clone(point);        // { x: 10, y: 20 }
 console.log(Point.equals(point, copy)); // true
-```
-
-Union type aliases also work, using JSON-based implementations:
-
-```typescript
+``` Union type aliases also work, using JSON-based implementations:
+ ```
 /** @derive(Debug, PartialEq) */
 type ApiStatus = "loading" | "success" | "error";
 
 const status: ApiStatus = "success";
-console.log(ApiStatus.toString(status)); // "ApiStatus(\\"success\\")"
+console.log(ApiStatus.toString(status)); // "ApiStatus(\"success\")"
 console.log(ApiStatus.equals("success", "success")); // true
-```
-
-## Combining Macros
-
-All macros can be used together. They don't conflict and each generates independent methods:
-
-```typescript
+``` ## Combining Macros
+ All macros can be used together. They don't conflict and each generates independent methods:
+ ```
 const user = new User("Alice", 30);
 
 // Debug
@@ -168,26 +119,14 @@ console.log(copy.name); // "Alice"
 
 // Eq
 console.log(user.equals(copy)); // true
-```
-
-## Detailed Documentation
-
-Each macro has its own options and behaviors:
-
-- [**Debug**]({base}/docs/builtin-macros/debug) - Customizable field renaming and skipping
-
-- [**Clone**]({base}/docs/builtin-macros/clone) - Deep copying for all field types
-
-- [**Default**]({base}/docs/builtin-macros/default) - Default value generation with field attributes
-
-- [**Hash**]({base}/docs/builtin-macros/hash) - Hash code generation for use in maps and sets
-
-- [**PartialEq**]({base}/docs/builtin-macros/partial-eq) - Value-based equality comparison
-
-- [**Ord**]({base}/docs/builtin-macros/ord) - Total ordering for sorting
-
-- [**PartialOrd**]({base}/docs/builtin-macros/partial-ord) - Partial ordering comparison
-
-- [**Serialize**]({base}/docs/builtin-macros/serialize) - JSON serialization with serde-style options
-
-- [**Deserialize**]({base}/docs/builtin-macros/deserialize) - JSON deserialization with validation
+``` ## Detailed Documentation
+ Each macro has its own options and behaviors:
+ - [**Debug**](../docs/builtin-macros/debug) - Customizable field renaming and skipping
+ - [**Clone**](../docs/builtin-macros/clone) - Deep copying for all field types
+ - [**Default**](../docs/builtin-macros/default) - Default value generation with field attributes
+ - [**Hash**](../docs/builtin-macros/hash) - Hash code generation for use in maps and sets
+ - [**PartialEq**](../docs/builtin-macros/partial-eq) - Value-based equality comparison
+ - [**Ord**](../docs/builtin-macros/ord) - Total ordering for sorting
+ - [**PartialOrd**](../docs/builtin-macros/partial-ord) - Partial ordering comparison
+ - [**Serialize**](../docs/builtin-macros/serialize) - JSON serialization with serde-style options
+ - [**Deserialize**](../docs/builtin-macros/deserialize) - JSON deserialization with validation