com.wallstop-studios.dxmessaging 2.1.7 → 2.1.9

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

@@ -1,239 +0,0 @@
----
-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

@@ -1,136 +0,0 @@
----
-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

@@ -1,233 +0,0 @@
----
-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>();
-    }
-}
-```