com.wallstop-studios.dxmessaging 2.1.4 → 2.1.5

package/.llm/skills/solid/fluent-builder-pattern.md

@@ -0,0 +1,322 @@
+---
+title: "Fluent Builder Pattern with Struct Builders"
+id: "fluent-builder-pattern"
+category: "solid"
+version: "1.0.0"
+created: "2026-01-21"
+updated: "2026-01-21"
+
+source:
+  repository: "wallstop/unity-helpers"
+  files:
+    - path: "Runtime/Core/Cache/CacheBuilder.cs"
+  url: "https://github.com/wallstop/unity-helpers"
+
+tags:
+  - "solid"
+  - "patterns"
+  - "builder"
+  - "fluent-api"
+  - "zero-alloc"
+
+complexity:
+  level: "intermediate"
+  reasoning: "Requires understanding of builder pattern and struct semantics"
+
+impact:
+  performance:
+    rating: "medium"
+    details: "Struct builder eliminates allocation for configuration object"
+  maintainability:
+    rating: "high"
+    details: "Self-documenting API with method chaining"
+  testability:
+    rating: "high"
+    details: "Easy to test different configurations"
+
+prerequisites:
+  - "Understanding of builder pattern"
+  - "Knowledge of struct vs class tradeoffs"
+
+dependencies:
+  packages: []
+  skills: []
+
+applies_to:
+  languages:
+    - "C#"
+  frameworks:
+    - "Unity"
+    - ".NET"
+  versions:
+    unity: ">=2021.3"
+
+aliases:
+  - "Method chaining"
+  - "Configuration builder"
+  - "Fluent interface"
+
+related:
+  - "collection-extensions"
+  - "try-pattern-apis"
+  - "fluent-builder-pattern-templates"
+  - "fluent-builder-pattern-usage-examples"
+
+status: "stable"
+---
+
+# Fluent Builder Pattern with Struct Builders
+
+> **One-line summary**: Implement the builder pattern using structs to provide a zero-allocation fluent API for complex object construction.
+
+## Overview
+
+The builder pattern separates object construction from its representation. Using a struct builder:
+
+1. **Zero allocation** for the builder itself
+1. **Fluent API** with method chaining
+1. **Immutable result** - builder returns configured object
+1. **Validation** in Build() method
+
+## Problem Statement
+
+```csharp
+// BAD: Constructor with many parameters
+var cache = new Cache<string, int>(
+    1000,           // What is this?
+    EvictionPolicy.Lru,
+    TimeSpan.FromMinutes(5),
+    TimeSpan.FromMinutes(1),
+    true,           // What does true mean?
+    null);
+
+// BAD: Class-based builder allocates
+var builder = new CacheBuilder<string, int>(); // Heap allocation!
+builder.WithMaxSize(1000);
+var cache = builder.Build();
+```
+
+## Solution
+
+### Struct-Based Fluent Builder
+
+```csharp
+namespace WallstopStudios.UnityHelpers.Core.Cache
+{
+    using System;
+    using System.Collections.Generic;
+
+    /// <summary>
+    /// Zero-allocation fluent builder for Cache configuration.
+    /// </summary>
+    /// <remarks>
+    /// This is a struct to avoid heap allocation. Each With* method returns
+    /// a new struct by value, enabling method chaining.
+    /// </remarks>
+    public struct CacheBuilder<TKey, TValue>
+    {
+        private int maximumSize;
+        private EvictionPolicy policy;
+        private TimeSpan? expireAfterWrite;
+        private TimeSpan? expireAfterAccess;
+        private bool recordStats;
+        private IEqualityComparer<TKey> keyComparer;
+        private float? jitterFactor;
+        private bool initialized;
+
+        /// <summary>
+        /// Sets the maximum number of entries in the cache.
+        /// </summary>
+        /// <param name="size">Maximum entry count. Must be positive.</param>
+        public CacheBuilder<TKey, TValue> WithMaximumSize(int size)
+        {
+            if (size <= 0)
+            {
+                throw new ArgumentOutOfRangeException(nameof(size), "Size must be positive");
+            }
+
+            var copy = this;
+            copy.maximumSize = size;
+            copy.initialized = true;
+            return copy;
+        }
+
+        /// <summary>
+        /// Sets the eviction policy when cache is full.
+        /// </summary>
+        /// <param name="evictionPolicy">Policy to use (LRU, LFU, etc.).</param>
+        public CacheBuilder<TKey, TValue> WithPolicy(EvictionPolicy evictionPolicy)
+        {
+            var copy = this;
+            copy.policy = evictionPolicy;
+            copy.initialized = true;
+            return copy;
+        }
+
+        /// <summary>
+        /// Sets expiration time after an entry is written.
+        /// </summary>
+        public CacheBuilder<TKey, TValue> WithExpireAfterWrite(TimeSpan duration)
+        {
+            if (duration <= TimeSpan.Zero)
+            {
+                throw new ArgumentOutOfRangeException(nameof(duration), "Duration must be positive");
+            }
+
+            var copy = this;
+            copy.expireAfterWrite = duration;
+            copy.initialized = true;
+            return copy;
+        }
+
+        /// <summary>
+        /// Sets expiration time after an entry is accessed.
+        /// </summary>
+        public CacheBuilder<TKey, TValue> WithExpireAfterAccess(TimeSpan duration)
+        {
+            if (duration <= TimeSpan.Zero)
+            {
+                throw new ArgumentOutOfRangeException(nameof(duration), "Duration must be positive");
+            }
+
+            var copy = this;
+            copy.expireAfterAccess = duration;
+            copy.initialized = true;
+            return copy;
+        }
+
+        /// <summary>
+        /// Enables hit/miss statistics recording.
+        /// </summary>
+        public CacheBuilder<TKey, TValue> WithRecordStats()
+        {
+            var copy = this;
+            copy.recordStats = true;
+            copy.initialized = true;
+            return copy;
+        }
+
+        /// <summary>
+        /// Sets a custom key comparer for lookups.
+        /// </summary>
+        public CacheBuilder<TKey, TValue> WithKeyComparer(IEqualityComparer<TKey> comparer)
+        {
+            var copy = this;
+            copy.keyComparer = comparer ?? throw new ArgumentNullException(nameof(comparer));
+            copy.initialized = true;
+            return copy;
+        }
+
+        /// <summary>
+        /// Adds random jitter to expiration times to prevent thundering herd.
+        /// </summary>
+        /// <param name="factor">Jitter factor (0.0-1.0). E.g., 0.1 = ±10% variation.</param>
+        public CacheBuilder<TKey, TValue> WithExpirationJitter(float factor)
+        {
+            if (factor < 0f || factor > 1f)
+            {
+                throw new ArgumentOutOfRangeException(nameof(factor), "Factor must be between 0 and 1");
+            }
+
+            var copy = this;
+            copy.jitterFactor = factor;
+            copy.initialized = true;
+            return copy;
+        }
+
+        /// <summary>
+        /// Builds the cache with the configured options.
+        /// </summary>
+        /// <returns>A new Cache instance.</returns>
+        /// <exception cref="InvalidOperationException">If configuration is invalid.</exception>
+        public Cache<TKey, TValue> Build()
+        {
+            // Apply defaults
+            int size = maximumSize > 0 ? maximumSize : 1000;
+            EvictionPolicy pol = initialized ? policy : EvictionPolicy.Lru;
+
+            // Validate combinations
+            if (jitterFactor.HasValue && !expireAfterWrite.HasValue && !expireAfterAccess.HasValue)
+            {
+                throw new InvalidOperationException(
+                    "Jitter requires expiration to be set. Call WithExpireAfterWrite or WithExpireAfterAccess first.");
+            }
+
+            var options = new CacheOptions<TKey, TValue>
+            {
+                MaximumSize = size,
+                Policy = pol,
+                ExpireAfterWriteSeconds = (float?)expireAfterWrite?.TotalSeconds,
+                ExpireAfterAccessSeconds = (float?)expireAfterAccess?.TotalSeconds,
+                RecordStats = recordStats,
+                KeyComparer = keyComparer,
+                JitterFactor = jitterFactor
+            };
+
+            return new Cache<TKey, TValue>(options);
+        }
+    }
+}
+```
+
+## Performance Notes
+
+### Struct vs Class Builder
+
+| Aspect        | Struct Builder | Class Builder     |
+| ------------- | -------------- | ----------------- |
+| Allocation    | 0 bytes        | ~24 bytes minimum |
+| GC pressure   | None           | Creates garbage   |
+| Copy behavior | Value copy     | Reference copy    |
+
+### Method Chaining Cost
+
+Each `With*` method copies the struct (~50-100 bytes typically). This is stack-allocated and very fast (~1ns).
+
+## Best Practices
+
+### Do
+
+- Use struct for builders with few fields (<10)
+- Return `this` by value (`var copy = this; ... return copy;`)
+- Validate early in With\* methods where possible
+- Validate configuration combinations in Build()
+- Provide sensible defaults
+
+### Don't
+
+- Don't use struct for large builders (>200 bytes)
+- Don't store reference types that might be mutated after Build()
+- Don't make builders mutable (always return new copy)
+- Don't forget the `initialized` flag pattern for distinguishing "not set" from "set to default"
+
+### Initialization Pattern
+
+```csharp
+public struct Builder
+{
+    private int value;
+    private bool valueSet; // Distinguishes "0" from "not set"
+
+    public Builder WithValue(int v)
+    {
+        var copy = this;
+        copy.value = v;
+        copy.valueSet = true;
+        return copy;
+    }
+
+    public Result Build()
+    {
+        int finalValue = valueSet ? value : 100; // Default is 100
+        return new Result(finalValue);
+    }
+}
+```
+
+## Related Patterns
+
+- [Collection Extensions](./collection-extensions.md) - Fluent collection API
+- [Try-Pattern APIs](./try-pattern-apis.md) - Safe configuration validation
+- [Fluent Builder Templates and Factories](./fluent-builder-pattern-templates.md) - Reusable patterns
+- [Fluent Builder Usage Examples](./fluent-builder-pattern-usage-examples.md) - Common flows

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

@@ -0,0 +1,111 @@
+---
+title: "IEquatable Usage Examples"
+id: "iequatable-implementation-usage"
+category: "solid"
+version: "1.0.0"
+created: "2026-01-21"
+updated: "2026-01-21"
+
+source:
+  repository: "wallstop/unity-helpers"
+  files:
+    - path: "Runtime/Core/DataStructure/"
+  url: "https://github.com/wallstop/unity-helpers"
+
+tags:
+  - "solid"
+  - "performance"
+  - "struct"
+  - "equality"
+
+complexity:
+  level: "intermediate"
+  reasoning: "Builds on core IEquatable implementation details"
+
+impact:
+  performance:
+    rating: "medium"
+    details: "Variants reduce boxing and hash recomputation"
+  maintainability:
+    rating: "medium"
+    details: "More code, but consistent patterns"
+  testability:
+    rating: "high"
+    details: "Equality logic can be unit tested"
+
+prerequisites:
+  - "Understanding of IEquatable"
+
+dependencies:
+  packages: []
+  skills:
+    - "iequatable-implementation"
+
+applies_to:
+  languages:
+    - "C#"
+  frameworks:
+    - "Unity"
+    - ".NET"
+
+aliases:
+  - "Equality variants"
+
+related:
+  - "iequatable-implementation"
+
+status: "stable"
+---
+
+# IEquatable Usage Examples
+
+> **One-line summary**: Using IEquatable in dictionaries, hash sets, and comparisons.
+
+## Overview
+
+This skill shows how to apply IEquatable in common collection scenarios.
+
+## Solution
+
+Use the examples below to integrate equality in dictionaries and sets.
+
+## Usage
+
+### In Dictionary
+
+```csharp
+var positions = new Dictionary<Point, GameObject>(256);
+
+// All operations use typed Equals and GetHashCode - no boxing
+positions[new Point(1, 2)] = playerObject;
+
+if (positions.TryGetValue(new Point(1, 2), out GameObject go))
+{
+    // Found!
+}
+```
+
+### In HashSet
+
+```csharp
+var visited = new HashSet<Point>(512);
+
+// Zero allocations for these operations
+visited.Add(new Point(x, y));
+if (visited.Contains(currentPosition))
+{
+    return; // Already visited
+}
+```
+
+### Equality Comparisons
+
+```csharp
+Point a = new Point(1, 2);
+Point b = new Point(1, 2);
+Point c = new Point(3, 4);
+
+bool equal = a == b;     // true, uses operator ==
+bool notEqual = a != c;  // true, uses operator !=
+bool alsoEqual = a.Equals(b); // true, direct typed call
+```

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

@@ -0,0 +1,201 @@
+---
+title: "IEquatable Implementation Variants"
+id: "iequatable-implementation-variants"
+category: "solid"
+version: "1.0.0"
+created: "2026-01-21"
+updated: "2026-01-21"
+
+source:
+  repository: "wallstop/unity-helpers"
+  files:
+    - path: "Runtime/Core/DataStructure/"
+  url: "https://github.com/wallstop/unity-helpers"
+
+tags:
+  - "solid"
+  - "performance"
+  - "struct"
+  - "equality"
+
+complexity:
+  level: "intermediate"
+  reasoning: "Builds on core IEquatable implementation details"
+
+impact:
+  performance:
+    rating: "medium"
+    details: "Variants reduce boxing and hash recomputation"
+  maintainability:
+    rating: "medium"
+    details: "More code, but consistent patterns"
+  testability:
+    rating: "high"
+    details: "Equality logic can be unit tested"
+
+prerequisites:
+  - "Understanding of IEquatable"
+
+dependencies:
+  packages: []
+  skills:
+    - "iequatable-implementation"
+
+applies_to:
+  languages:
+    - "C#"
+  frameworks:
+    - "Unity"
+    - ".NET"
+
+aliases:
+  - "Equality variants"
+
+related:
+  - "iequatable-implementation"
+
+status: "stable"
+---
+
+# IEquatable Implementation Variants
+
+> **One-line summary**: Extensions for cached hashes, nullable fields, and reference comparisons.
+
+## Overview
+
+This skill documents IEquatable variants for specialized needs.
+
+## Solution
+
+Select the variant that matches hashing or null-handling requirements.
+
+### With Cached Hash (for heavy dictionary usage)
+
+```csharp
+public readonly struct FastPoint : IEquatable<FastPoint>
+{
+    public readonly int X;
+    public readonly int Y;
+    private readonly int _hash;
+
+    public FastPoint(int x, int y)
+    {
+        X = x;
+        Y = y;
+        unchecked
+        {
+            _hash = 17;
+            _hash = _hash * 31 + x;
+            _hash = _hash * 31 + y;
+        }
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public bool Equals(FastPoint other)
+    {
+        // Early-out on hash mismatch
+        return _hash == other._hash && X == other.X && Y == other.Y;
+    }
+
+    public override bool Equals(object obj)
+    {
+        return obj is FastPoint other && Equals(other);
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public override int GetHashCode() => _hash;
+
+    public static bool operator ==(FastPoint left, FastPoint right) => left.Equals(right);
+    public static bool operator !=(FastPoint left, FastPoint right) => !left.Equals(right);
+}
+```
+
+### With Nullable Fields
+
+```csharp
+public readonly struct OptionalPoint : IEquatable<OptionalPoint>
+{
+    public readonly int? X;
+    public readonly int? Y;
+    public readonly string Label; // Reference type
+
+    public OptionalPoint(int? x, int? y, string label)
+    {
+        X = x;
+        Y = y;
+        Label = label;
+    }
+
+    public bool Equals(OptionalPoint other)
+    {
+        return X == other.X
+            && Y == other.Y
+            && string.Equals(Label, other.Label, StringComparison.Ordinal);
+    }
+
+    public override bool Equals(object obj)
+    {
+        return obj is OptionalPoint other && Equals(other);
+    }
+
+    public override int GetHashCode()
+    {
+        unchecked
+        {
+            int hash = 17;
+            hash = hash * 31 + (X?.GetHashCode() ?? 0);
+            hash = hash * 31 + (Y?.GetHashCode() ?? 0);
+            hash = hash * 31 + (Label?.GetHashCode() ?? 0);
+            return hash;
+        }
+    }
+
+    public static bool operator ==(OptionalPoint left, OptionalPoint right) => left.Equals(right);
+    public static bool operator !=(OptionalPoint left, OptionalPoint right) => !left.Equals(right);
+}
+```
+
+### With Reference Type Comparisons
+
+```csharp
+public readonly struct Entity : IEquatable<Entity>
+{
+    public readonly int Id;
+    public readonly string Name;
+    public readonly Type ComponentType;
+
+    public Entity(int id, string name, Type componentType)
+    {
+        Id = id;
+        Name = name;
+        ComponentType = componentType;
+    }
+
+    public bool Equals(Entity other)
+    {
+        return Id == other.Id
+            && string.Equals(Name, other.Name, StringComparison.Ordinal)
+            && ComponentType == other.ComponentType;
+    }
+
+    public override bool Equals(object obj)
+    {
+        return obj is Entity other && Equals(other);
+    }
+
+    public override int GetHashCode()
+    {
+        unchecked
+        {
+            int hash = 17;
+            hash = hash * 31 + Id;
+            hash = hash * 31 + (Name?.GetHashCode() ?? 0);
+            hash = hash * 31 + (ComponentType?.GetHashCode() ?? 0);
+            return hash;
+        }
+    }
+
+    public static bool operator ==(Entity left, Entity right) => left.Equals(right);
+    public static bool operator !=(Entity left, Entity right) => !left.Equals(right);
+}
+```