com.wallstop-studios.dxmessaging 2.1.4 → 2.1.5

package/.llm/skills/solid/iequatable-implementation.md

@@ -0,0 +1,239 @@
+---
+title: "IEquatable Implementation for Value Types"
+id: "iequatable-implementation"
+category: "solid"
+version: "1.0.0"
+created: "2026-01-21"
+updated: "2026-01-21"
+
+source:
+  repository: "wallstop/unity-helpers"
+  files:
+    - path: "Runtime/Core/DataStructure/FastVector2Int.cs"
+    - path: "Runtime/Core/DataStructure/FastVector3Int.cs"
+  url: "https://github.com/wallstop/unity-helpers"
+
+tags:
+  - "solid"
+  - "performance"
+  - "struct"
+  - "equality"
+  - "boxing"
+  - "iequatable"
+
+complexity:
+  level: "intermediate"
+  reasoning: "Requires understanding of boxing and equality contracts"
+
+impact:
+  performance:
+    rating: "high"
+    details: "Eliminates boxing in collection operations"
+  maintainability:
+    rating: "high"
+    details: "Standard pattern with clear implementation"
+  testability:
+    rating: "high"
+    details: "Equality easily unit tested"
+
+prerequisites:
+  - "Understanding of boxing"
+  - "Knowledge of equality contract"
+
+dependencies:
+  packages: []
+  skills: []
+
+applies_to:
+  languages:
+    - "C#"
+  frameworks:
+    - "Unity"
+    - ".NET"
+  versions:
+    unity: ">=2021.3"
+
+aliases:
+  - "Struct equality"
+  - "Value type equality"
+  - "Boxing avoidance"
+
+related:
+  - "readonly-struct-cached-hash"
+  - "collection-extensions"
+  - "iequatable-implementation-variants"
+  - "iequatable-implementation-usage"
+
+status: "stable"
+---
+
+# IEquatable<T> Implementation for Value Types
+
+> **One-line summary**: Implement `IEquatable<T>` on structs to avoid boxing allocations when used in collections, providing 10-100x faster equality comparisons.
+
+## Overview
+
+When structs are compared via `object.Equals()`, they are boxed (heap-allocated). Implementing `IEquatable<T>`:
+
+1. **Avoids boxing** - direct typed comparison
+1. **Enables optimization** - collections use generic `Equals(T)`
+1. **Clear contract** - explicit equality semantics
+
+## Problem Statement
+
+```csharp
+// BAD: Default struct equality uses reflection and boxes
+public struct BadPoint
+{
+    public int X, Y;
+}
+
+var dict = new Dictionary<BadPoint, string>();
+var point = new BadPoint { X = 1, Y = 2 };
+
+// Each operation boxes the struct!
+dict.Add(point, "A");     // Box for GetHashCode
+dict.ContainsKey(point);  // Box for Equals
+
+// Default Equals uses reflection - SLOW
+bool equal = point.Equals(otherPoint); // Reflection-based comparison
+```
+
+### Boxing Cost
+
+For 128,000 `HashSet.Contains` calls:
+
+- Without IEquatable: 4MB allocations (boxing)
+- With IEquatable: 0 allocations
+
+## Solution
+
+### Complete IEquatable Implementation
+
+```csharp
+namespace WallstopStudios.UnityHelpers.Core.DataStructure
+{
+    using System;
+    using System.Runtime.CompilerServices;
+
+    /// <summary>
+    /// Properly implemented struct with IEquatable for optimal collection performance.
+    /// </summary>
+    public readonly struct Point : IEquatable<Point>
+    {
+        public readonly int X;
+        public readonly int Y;
+
+        public Point(int x, int y)
+        {
+            X = x;
+            Y = y;
+        }
+
+        /// <summary>
+        /// Typed equality comparison - no boxing.
+        /// </summary>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public bool Equals(Point other)
+        {
+            return X == other.X && Y == other.Y;
+        }
+
+        /// <summary>
+        /// Object equality - boxes if other is Point, but necessary for interface.
+        /// </summary>
+        public override bool Equals(object obj)
+        {
+            return obj is Point other && Equals(other);
+        }
+
+        /// <summary>
+        /// Hash code for dictionary/hashset operations.
+        /// </summary>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public override int GetHashCode()
+        {
+            unchecked
+            {
+                int hash = 17;
+                hash = hash * 31 + X;
+                hash = hash * 31 + Y;
+                return hash;
+            }
+        }
+
+        /// <summary>
+        /// Equality operator for natural syntax.
+        /// </summary>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static bool operator ==(Point left, Point right)
+        {
+            return left.Equals(right);
+        }
+
+        /// <summary>
+        /// Inequality operator.
+        /// </summary>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static bool operator !=(Point left, Point right)
+        {
+            return !left.Equals(right);
+        }
+
+        public override string ToString() => $"({X}, {Y})";
+    }
+}
+```
+
+## Performance Notes
+
+### Boxing Cost
+
+| Operation         | Without IEquatable | With IEquatable |
+| ----------------- | ------------------ | --------------- |
+| Dictionary lookup | ~50ns + 24B alloc  | ~10ns, 0 alloc  |
+| HashSet.Contains  | ~30ns + 24B alloc  | ~5ns, 0 alloc   |
+| List.Contains     | ~20ns + 24B alloc  | ~5ns, 0 alloc   |
+
+### Memory Impact (128K operations)
+
+| Without IEquatable | With IEquatable |
+| ------------------ | --------------- |
+| 4MB allocations    | 0 allocations   |
+| GC pauses          | No GC pressure  |
+
+## Best Practices
+
+### Do
+
+- Always implement `IEquatable<T>` for structs used in collections
+- Override `Equals(object)` for compatibility
+- Override `GetHashCode()` with consistent hash
+- Implement `==` and `!=` operators
+- Use `readonly struct` to prevent mutation
+- Use `[MethodImpl(AggressiveInlining)]` for hot paths
+
+### Don't
+
+- Don't rely on default struct equality (uses reflection)
+- Don't forget any of the four members (Equals, GetHashCode, ==, !=)
+- Don't mutate fields used in hash calculation
+- Don't ignore nullable fields in equality/hash
+
+### Equality Contract
+
+```text
+1. Reflexive: a.Equals(a) == true
+2. Symmetric: a.Equals(b) == b.Equals(a)
+3. Transitive: if a.Equals(b) && b.Equals(c) then a.Equals(c)
+4. Consistent: multiple calls return same result
+5. Null: a.Equals(null) == false (for reference types)
+6. Hash: if a.Equals(b) then a.GetHashCode() == b.GetHashCode()
+```
+
+## Related Patterns
+
+- [Readonly Struct with Cached Hash](../performance/readonly-struct-cached-hash.md) - Advanced hashing
+- [Collection Extensions](./collection-extensions.md) - Collection utilities
+- [IEquatable Implementation Variants](./iequatable-implementation-variants.md) - Cached hash and nullable patterns
+- [IEquatable Usage Examples](./iequatable-implementation-usage.md) - Collections and comparisons

package/.llm/skills/solid/try-pattern-apis-usage.md

@@ -0,0 +1,136 @@
+---
+title: "Try-Pattern API Usage Examples"
+id: "try-pattern-apis-usage"
+category: "solid"
+version: "1.0.0"
+created: "2026-01-21"
+updated: "2026-01-21"
+
+source:
+  repository: "wallstop/unity-helpers"
+  files:
+    - path: "Runtime/Core/Utilities/"
+  url: "https://github.com/wallstop/unity-helpers"
+
+tags:
+  - "solid"
+  - "defensive"
+  - "api-design"
+  - "try-pattern"
+
+complexity:
+  level: "basic"
+  reasoning: "Extends core try-pattern usage with variants"
+
+impact:
+  performance:
+    rating: "medium"
+    details: "Avoids exception allocations in expected failure cases"
+  maintainability:
+    rating: "high"
+    details: "Encourages explicit error handling"
+  testability:
+    rating: "high"
+    details: "Try-patterns are easy to test"
+
+prerequisites:
+  - "Understanding of out parameters"
+
+dependencies:
+  packages: []
+  skills:
+    - "try-pattern-apis"
+
+applies_to:
+  languages:
+    - "C#"
+  frameworks:
+    - "Unity"
+    - ".NET"
+
+aliases:
+  - "TryGet patterns"
+
+related:
+  - "try-pattern-apis"
+
+status: "stable"
+---
+
+# Try-Pattern API Usage Examples
+
+> **One-line summary**: Usage patterns for chaining, callbacks, and error handling.
+
+## Overview
+
+This skill focuses on Try-pattern usage in real flows.
+
+## Solution
+
+Apply the examples below to chain and compose Try-pattern calls.
+
+## Usage
+
+### Basic Try-Pattern Usage
+
+```csharp
+// Collection access
+if (items.TryGet(index, out Item item))
+{
+    ProcessItem(item);
+}
+else
+{
+    HandleMissingItem(index);
+}
+
+// With default fallback
+Item item = items.GetOrDefault(index, Item.Empty);
+
+// Cache lookup
+if (cache.TryGet(playerId, out PlayerData data))
+{
+    UpdateUI(data);
+}
+else
+{
+    StartDataLoad(playerId);
+}
+```
+
+### Chained Try Operations
+
+```csharp
+public bool TryLoadPlayerWeapon(string playerId, out Weapon weapon)
+{
+    weapon = null;
+
+    if (!playerCache.TryGet(playerId, out PlayerData player))
+    {
+        return false;
+    }
+
+    if (!weaponCache.TryGet(player.WeaponId, out weapon))
+    {
+        return false;
+    }
+
+    return true;
+}
+```
+
+### Try with Action on Success
+
+```csharp
+// Extension for common pattern
+public static void IfPresent<T>(this bool found, T value, Action<T> action)
+{
+    if (found)
+    {
+        action(value);
+    }
+}
+
+// Usage
+cache.TryGet(key, out var value).IfPresent(value, v => Process(v));
+```

package/.llm/skills/solid/try-pattern-apis-variants.md

@@ -0,0 +1,233 @@
+---
+title: "Try-Pattern API Variants"
+id: "try-pattern-apis-variants"
+category: "solid"
+version: "1.0.0"
+created: "2026-01-21"
+updated: "2026-01-21"
+
+source:
+  repository: "wallstop/unity-helpers"
+  files:
+    - path: "Runtime/Core/Utilities/"
+  url: "https://github.com/wallstop/unity-helpers"
+
+tags:
+  - "solid"
+  - "defensive"
+  - "api-design"
+  - "try-pattern"
+
+complexity:
+  level: "basic"
+  reasoning: "Extends core try-pattern usage with variants"
+
+impact:
+  performance:
+    rating: "medium"
+    details: "Avoids exception allocations in expected failure cases"
+  maintainability:
+    rating: "high"
+    details: "Encourages explicit error handling"
+  testability:
+    rating: "high"
+    details: "Try-patterns are easy to test"
+
+prerequisites:
+  - "Understanding of out parameters"
+
+dependencies:
+  packages: []
+  skills:
+    - "try-pattern-apis"
+
+applies_to:
+  languages:
+    - "C#"
+  frameworks:
+    - "Unity"
+    - ".NET"
+
+aliases:
+  - "TryGet patterns"
+
+related:
+  - "try-pattern-apis"
+
+status: "stable"
+---
+
+# Try-Pattern API Variants
+
+> **One-line summary**: Dictionary, TryParse, and component-style variants.
+
+## Overview
+
+This skill compares common Try-pattern API shapes.
+
+## Solution
+
+Pick the variant that matches your call site and error semantics.
+
+### Dictionary-Style TryGet
+
+```csharp
+public sealed class Cache<TKey, TValue>
+{
+    private readonly Dictionary<TKey, CacheEntry> entries;
+
+    /// <summary>
+    /// Attempts to retrieve a value from the cache.
+    /// </summary>
+    /// <param name="key">The key to look up.</param>
+    /// <param name="value">The value if found, default otherwise.</param>
+    /// <returns>True if the key exists and the value was retrieved.</returns>
+    public bool TryGet(TKey key, out TValue value)
+    {
+        if (key == null)
+        {
+            throw new ArgumentNullException(nameof(key));
+        }
+
+        if (entries.TryGetValue(key, out CacheEntry entry))
+        {
+            if (!IsExpired(entry))
+            {
+                UpdateAccessTime(entry);
+                value = entry.Value;
+                return true;
+            }
+
+            // Expired - remove and return false
+            entries.Remove(key);
+        }
+
+        value = default;
+        return false;
+    }
+
+    /// <summary>
+    /// Gets a value from the cache, or computes and caches it.
+    /// </summary>
+    public TValue GetOrAdd(TKey key, Func<TKey, TValue> valueFactory)
+    {
+        if (TryGet(key, out TValue existing))
+        {
+            return existing;
+        }
+
+        TValue newValue = valueFactory(key);
+        Put(key, newValue);
+        return newValue;
+    }
+}
+```
+
+### Parse-Style TryParse
+
+```csharp
+public static class ColorParser
+{
+    /// <summary>
+    /// Attempts to parse a hex color string.
+    /// </summary>
+    /// <param name="hex">Hex string like "#FF0000" or "FF0000".</param>
+    /// <param name="color">Parsed color if successful.</param>
+    /// <returns>True if parsing succeeded.</returns>
+    public static bool TryParseHex(string hex, out Color color)
+    {
+        color = default;
+
+        if (string.IsNullOrEmpty(hex))
+        {
+            return false;
+        }
+
+        // Strip leading #
+        if (hex[0] == '#')
+        {
+            hex = hex.Substring(1);
+        }
+
+        if (hex.Length != 6 && hex.Length != 8)
+        {
+            return false;
+        }
+
+        if (!TryParseHexByte(hex, 0, out byte r)) return false;
+        if (!TryParseHexByte(hex, 2, out byte g)) return false;
+        if (!TryParseHexByte(hex, 4, out byte b)) return false;
+
+        byte a = 255;
+        if (hex.Length == 8)
+        {
+            if (!TryParseHexByte(hex, 6, out a)) return false;
+        }
+
+        color = new Color(r / 255f, g / 255f, b / 255f, a / 255f);
+        return true;
+    }
+
+    private static bool TryParseHexByte(string hex, int offset, out byte value)
+    {
+        if (byte.TryParse(
+            hex.Substring(offset, 2),
+            System.Globalization.NumberStyles.HexNumber,
+            null,
+            out value))
+        {
+            return true;
+        }
+
+        value = 0;
+        return false;
+    }
+
+    /// <summary>
+    /// Parses a hex color or returns a default.
+    /// </summary>
+    public static Color ParseHexOrDefault(string hex, Color defaultColor = default)
+    {
+        return TryParseHex(hex, out Color color) ? color : defaultColor;
+    }
+}
+```
+
+### Component-Style TryGet
+
+```csharp
+public static class GameObjectExtensions
+{
+    /// <summary>
+    /// Attempts to get a component of the specified type.
+    /// </summary>
+    /// <remarks>
+    /// <para>Performance: O(n) where n is number of components.</para>
+    /// <para>Allocations: No allocations in Unity 2019.3+.</para>
+    /// </remarks>
+    public static bool TryGetComponentSafe<T>(this GameObject go, out T component)
+        where T : class
+    {
+        if (go == null)
+        {
+            component = null;
+            return false;
+        }
+
+        return go.TryGetComponent(out component);
+    }
+
+    /// <summary>
+    /// Gets a component or adds it if missing.
+    /// </summary>
+    public static T GetOrAddComponent<T>(this GameObject go) where T : Component
+    {
+        if (go.TryGetComponent(out T component))
+        {
+            return component;
+        }
+
+        return go.AddComponent<T>();
+    }
+}
+```