com.wallstop-studios.unity-helpers 2.0.0-rc81.7 → 2.0.0-rc81.9

package/Runtime/Core/DataStructure/Trie.cs.meta

@@ -1,3 +1,3 @@
-fileFormatVersion: 2
-guid: 6693302ec09144868fbf8da3c5f1c298
+fileFormatVersion: 2
+guid: 6693302ec09144868fbf8da3c5f1c298
 timeCreated: 1748539006

package/Runtime/Core/DataStructure.meta

@@ -1,8 +1,8 @@
-fileFormatVersion: 2
-guid: 9e1f0db7ec7ce4c4e9a7b0a77c370cd6
-folderAsset: yes
-DefaultImporter:
-  externalObjects: {}
-  userData: 
-  assetBundleName: 
-  assetBundleVariant: 
+fileFormatVersion: 2
+guid: 9e1f0db7ec7ce4c4e9a7b0a77c370cd6
+folderAsset: yes
+DefaultImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Runtime/Core/Extension/AnimatorExtensions.cs

@@ -1,25 +1,40 @@
-namespace WallstopStudios.UnityHelpers.Core.Extension
-{
-    using UnityEngine;
-
-    public static class AnimatorExtensions
-    {
-        public static void ResetTriggers(this Animator animator)
-        {
-            if (!animator || !animator.isActiveAndEnabled)
-            {
-                return;
-            }
-
-            foreach (AnimatorControllerParameter animatorParameter in animator.parameters)
-            {
-                if (animatorParameter.type != AnimatorControllerParameterType.Trigger)
-                {
-                    continue;
-                }
-
-                animator.ResetTrigger(animatorParameter.name);
-            }
-        }
-    }
-}
+namespace WallstopStudios.UnityHelpers.Core.Extension
+{
+    using UnityEngine;
+
+    /// <summary>
+    /// Extension methods for Unity's Animator class.
+    /// </summary>
+    public static class AnimatorExtensions
+    {
+        /// <summary>
+        /// Resets all trigger parameters on the Animator to their default state.
+        /// </summary>
+        /// <param name="animator">The Animator whose triggers will be reset.</param>
+        /// <remarks>
+        /// This method iterates through all parameters on the Animator and resets any parameters of type Trigger.
+        /// Only processes the Animator if it is not null and is active and enabled.
+        /// Non-trigger parameters are left unchanged.
+        /// This is useful for cleaning up trigger states between animation transitions or when resetting an Animator to a known state.
+        /// Thread-safe: No. Must be called from the main Unity thread.
+        /// Performance: O(n) where n is the number of parameters on the Animator.
+        /// </remarks>
+        public static void ResetTriggers(this Animator animator)
+        {
+            if (animator == null || !animator.isActiveAndEnabled)
+            {
+                return;
+            }
+
+            foreach (AnimatorControllerParameter animatorParameter in animator.parameters)
+            {
+                if (animatorParameter.type != AnimatorControllerParameterType.Trigger)
+                {
+                    continue;
+                }
+
+                animator.ResetTrigger(animatorParameter.name);
+            }
+        }
+    }
+}

package/Runtime/Core/Extension/AnimatorExtensions.cs.meta

@@ -1,11 +1,11 @@
-fileFormatVersion: 2
-guid: b854868f69ce80b488c813dae7273745
-MonoImporter:
-  externalObjects: {}
-  serializedVersion: 2
-  defaultReferences: []
-  executionOrder: 0
-  icon: {instanceID: 0}
-  userData: 
-  assetBundleName: 
-  assetBundleVariant: 
+fileFormatVersion: 2
+guid: b854868f69ce80b488c813dae7273745
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Runtime/Core/Extension/AsyncOperationExtensions.cs

@@ -1,110 +1,404 @@
-namespace WallstopStudios.UnityHelpers.Core.Extension
-{
-    using System;
-    using System.Collections.Concurrent;
-    using System.Collections.Generic;
-    using System.Runtime.CompilerServices;
-    using System.Threading.Tasks;
-    using UnityEngine;
-
-    public static class AsyncOperationExtensions
-    {
-        private static readonly ConcurrentDictionary<
-            AsyncOperation,
-            Action<AsyncOperation>
-        > Handlers = new();
-        private static readonly ConcurrentDictionary<AsyncOperation, Action> Continuations = new();
-
-        public readonly struct AsyncOperationAwaiter : INotifyCompletion
-        {
-            private readonly AsyncOperation _operation;
-
-            public AsyncOperationAwaiter(AsyncOperation operation)
-            {
-                _operation = operation ?? throw new ArgumentNullException(nameof(operation));
-            }
-
-            public bool IsCompleted => _operation.isDone;
-
-            public void OnCompleted(Action continuation)
-            {
-                Continuations[_operation] = continuation;
-
-                Action<AsyncOperation> handler = CachedHandler;
-                if (!Handlers.TryAdd(_operation, handler))
-                {
-                    return;
-                }
-
-                Handlers[_operation] = handler;
-                _operation.completed += handler;
-            }
-
-            public void GetResult() { }
-        }
-
-        private static readonly Action<AsyncOperation> CachedHandler = OnOperationCompleted;
-
-        private static void OnOperationCompleted(AsyncOperation operation)
-        {
-            Handlers.Remove(operation, out Action<AsyncOperation> _);
-            if (!Continuations.Remove(operation, out Action completionCondition))
-            {
-                return;
-            }
-
-            completionCondition?.Invoke();
-        }
-
-        public static async Task AsTask(this AsyncOperation asyncOp)
-        {
-            if (asyncOp.isDone)
-            {
-                return;
-            }
-
-            await asyncOp;
-        }
-
-        public static async ValueTask AsValueTask(this AsyncOperation asyncOp)
-        {
-            if (asyncOp.isDone)
-            {
-                return;
-            }
-
-            await asyncOp;
-        }
-
-#if !UNITY_2023_1_OR_NEWER
-        public static AsyncOperationAwaiter GetAwaiter(this AsyncOperation op)
-        {
-            return new AsyncOperationAwaiter(op);
-        }
-#endif
-
-        public static async ValueTask WithContinuation(this ValueTask task, Action continuation)
-        {
-            await task;
-            continuation?.Invoke();
-        }
-
-        public static async ValueTask<TResult> WithContinuation<TResult>(
-            this ValueTask<TResult> task,
-            Func<TResult, TResult> continuation
-        )
-        {
-            TResult result = await task;
-            return continuation(result);
-        }
-
-        public static async ValueTask WithContinuation<TResult>(
-            this ValueTask<TResult> task,
-            Action<TResult> continuation
-        )
-        {
-            TResult result = await task;
-            continuation(result);
-        }
-    }
-}
+namespace WallstopStudios.UnityHelpers.Core.Extension
+{
+    using System;
+    using System.Collections;
+    using System.Collections.Concurrent;
+    using System.Collections.Generic;
+    using System.Runtime.CompilerServices;
+    using System.Threading.Tasks;
+    using UnityEngine;
+
+    /// <summary>
+    /// Extension methods for Unity AsyncOperation and Task/ValueTask/IEnumerator interoperability.
+    /// </summary>
+    public static class AsyncOperationExtensions
+    {
+        private static readonly ConcurrentDictionary<
+            AsyncOperation,
+            Action<AsyncOperation>
+        > Handlers = new();
+        private static readonly ConcurrentDictionary<AsyncOperation, Action> Continuations = new();
+
+        /// <summary>
+        /// Provides an awaiter for Unity AsyncOperation objects, enabling async/await syntax.
+        /// </summary>
+        /// <remarks>
+        /// <para>This struct is used internally to enable async/await on AsyncOperation.</para>
+        /// <para>Thread safety: Thread-safe using concurrent dictionaries for handler storage. Must complete on Unity main thread.</para>
+        /// <para>Performance: O(1) for completion checks. Allocations occur for continuation storage in dictionaries.</para>
+        /// <para>Allocations: Allocates dictionary entries for tracking completions. Cleaned up on completion.</para>
+        /// </remarks>
+        public readonly struct AsyncOperationAwaiter : INotifyCompletion
+        {
+            private readonly AsyncOperation _operation;
+
+            /// <summary>
+            /// Initializes a new instance of the AsyncOperationAwaiter struct.
+            /// </summary>
+            /// <param name="operation">The AsyncOperation to await.</param>
+            /// <exception cref="ArgumentNullException">Thrown when operation is null.</exception>
+            public AsyncOperationAwaiter(AsyncOperation operation)
+            {
+                _operation = operation ?? throw new ArgumentNullException(nameof(operation));
+            }
+
+            /// <summary>
+            /// Gets a value indicating whether the async operation has completed.
+            /// </summary>
+            public bool IsCompleted => _operation.isDone;
+
+            /// <summary>
+            /// Schedules the continuation action to be invoked when the operation completes.
+            /// </summary>
+            /// <param name="continuation">The action to invoke when the operation completes.</param>
+            public void OnCompleted(Action continuation)
+            {
+                Continuations[_operation] = continuation;
+
+                Action<AsyncOperation> handler = CachedHandler;
+                if (!Handlers.TryAdd(_operation, handler))
+                {
+                    return;
+                }
+
+                Handlers[_operation] = handler;
+                _operation.completed += handler;
+            }
+
+            /// <summary>
+            /// Gets the result of the async operation. Since AsyncOperation has no return value, this is a no-op.
+            /// </summary>
+            public void GetResult() { }
+        }
+
+        private static readonly Action<AsyncOperation> CachedHandler = OnOperationCompleted;
+
+        private static void OnOperationCompleted(AsyncOperation operation)
+        {
+            Handlers.Remove(operation, out Action<AsyncOperation> _);
+            if (!Continuations.Remove(operation, out Action completionCondition))
+            {
+                return;
+            }
+
+            completionCondition?.Invoke();
+        }
+
+        /// <summary>
+        /// Converts a Unity AsyncOperation to a Task.
+        /// </summary>
+        /// <param name="asyncOp">The AsyncOperation to convert.</param>
+        /// <returns>A Task that completes when the AsyncOperation completes.</returns>
+        /// <remarks>
+        /// <para>Null handling: Throws NullReferenceException if asyncOp is null when awaiting.</para>
+        /// <para>Thread safety: Must complete on Unity main thread. No Unity main thread requirement for initial call.</para>
+        /// <para>Performance: O(1). Returns immediately if already complete.</para>
+        /// <para>Allocations: Allocates Task state machine if operation not complete.</para>
+        /// <para>Edge cases: Returns immediately if operation is already done.</para>
+        /// </remarks>
+        public static async Task AsTask(this AsyncOperation asyncOp)
+        {
+            if (asyncOp.isDone)
+            {
+                return;
+            }
+
+            await asyncOp;
+        }
+
+        /// <summary>
+        /// Converts a Unity AsyncOperation to a ValueTask.
+        /// </summary>
+        /// <param name="asyncOp">The AsyncOperation to convert.</param>
+        /// <returns>A ValueTask that completes when the AsyncOperation completes.</returns>
+        /// <remarks>
+        /// <para>Null handling: Throws NullReferenceException if asyncOp is null when awaiting.</para>
+        /// <para>Thread safety: Must complete on Unity main thread. No Unity main thread requirement for initial call.</para>
+        /// <para>Performance: O(1). Returns immediately if already complete.</para>
+        /// <para>Allocations: No allocations if operation is already done, otherwise allocates ValueTask state machine.</para>
+        /// <para>Edge cases: Returns immediately if operation is already done. Prefer over AsTask for completed operations.</para>
+        /// </remarks>
+        public static async ValueTask AsValueTask(this AsyncOperation asyncOp)
+        {
+            if (asyncOp.isDone)
+            {
+                return;
+            }
+
+            await asyncOp;
+        }
+
+#if !UNITY_2023_1_OR_NEWER
+        /// <summary>
+        /// Gets an awaiter for the AsyncOperation, enabling async/await syntax.
+        /// Only available in Unity versions before 2023.1 (Unity 2023.1+ provides this natively).
+        /// </summary>
+        /// <param name="op">The AsyncOperation to get an awaiter for.</param>
+        /// <returns>An AsyncOperationAwaiter for the operation.</returns>
+        /// <remarks>
+        /// <para>Null handling: Throws ArgumentNullException if op is null (thrown by AsyncOperationAwaiter constructor).</para>
+        /// <para>Thread safety: Thread-safe. Must complete on Unity main thread.</para>
+        /// <para>Performance: O(1).</para>
+        /// <para>Allocations: Allocates AsyncOperationAwaiter struct (stack allocation).</para>
+        /// <para>Edge cases: Not available in Unity 2023.1+, where AsyncOperation implements INotifyCompletion natively.</para>
+        /// </remarks>
+        /// <exception cref="ArgumentNullException">Thrown when op is null.</exception>
+        public static AsyncOperationAwaiter GetAwaiter(this AsyncOperation op)
+        {
+            return new AsyncOperationAwaiter(op);
+        }
+#endif
+
+        /// <summary>
+        /// Executes a continuation action after a ValueTask completes.
+        /// </summary>
+        /// <param name="task">The task to await.</param>
+        /// <param name="continuation">The action to execute after the task completes. Can be null.</param>
+        /// <returns>A ValueTask that completes after the continuation executes.</returns>
+        /// <remarks>
+        /// <para>Null handling: If continuation is null, no action is taken after the task completes.</para>
+        /// <para>Thread safety: Continuation executes on the same context as the task completion. No Unity main thread requirement unless task requires it.</para>
+        /// <para>Performance: O(1) overhead for continuation invocation.</para>
+        /// <para>Allocations: Allocates async state machine.</para>
+        /// <para>Edge cases: Null continuation is allowed and does nothing.</para>
+        /// </remarks>
+        public static async ValueTask WithContinuation(this ValueTask task, Action continuation)
+        {
+            await task;
+            continuation?.Invoke();
+        }
+
+        /// <summary>
+        /// Executes a continuation function that transforms the result after a ValueTask completes.
+        /// </summary>
+        /// <typeparam name="TResult">The type of the task result.</typeparam>
+        /// <param name="task">The task to await.</param>
+        /// <param name="continuation">The function to execute on the result. Can be null, in which case the original result is returned.</param>
+        /// <returns>A ValueTask containing the transformed result, or the original result if continuation is null.</returns>
+        /// <remarks>
+        /// <para>Null handling: If continuation is null, returns the original task result unchanged.</para>
+        /// <para>Thread safety: Continuation executes on the same context as the task completion. No Unity main thread requirement unless task requires it.</para>
+        /// <para>Performance: O(1) overhead for continuation invocation.</para>
+        /// <para>Allocations: Allocates async state machine.</para>
+        /// <para>Edge cases: Null continuation is allowed and returns original result.</para>
+        /// </remarks>
+        public static async ValueTask<TResult> WithContinuation<TResult>(
+            this ValueTask<TResult> task,
+            Func<TResult, TResult> continuation
+        )
+        {
+            TResult result = await task;
+            return continuation != null ? continuation(result) : result;
+        }
+
+        /// <summary>
+        /// Executes a continuation action with the result after a ValueTask completes.
+        /// </summary>
+        /// <typeparam name="TResult">The type of the task result.</typeparam>
+        /// <param name="task">The task to await.</param>
+        /// <param name="continuation">The action to execute with the result. Can be null.</param>
+        /// <returns>A ValueTask that completes after the continuation executes.</returns>
+        /// <remarks>
+        /// <para>Null handling: If continuation is null, no action is taken after the task completes.</para>
+        /// <para>Thread safety: Continuation executes on the same context as the task completion. No Unity main thread requirement unless task requires it.</para>
+        /// <para>Performance: O(1) overhead for continuation invocation.</para>
+        /// <para>Allocations: Allocates async state machine.</para>
+        /// <para>Edge cases: Null continuation is allowed and does nothing.</para>
+        /// </remarks>
+        public static async ValueTask WithContinuation<TResult>(
+            this ValueTask<TResult> task,
+            Action<TResult> continuation
+        )
+        {
+            TResult result = await task;
+            continuation?.Invoke(result);
+        }
+
+        // Task/ValueTask to IEnumerator conversions
+        /// <summary>
+        /// Converts a Task to a Unity coroutine (IEnumerator).
+        /// </summary>
+        /// <param name="task">The task to convert.</param>
+        /// <returns>An IEnumerator that can be used with StartCoroutine.</returns>
+        /// <remarks>
+        /// <para>Null handling: Throws NullReferenceException if task is null when checking IsCompleted.</para>
+        /// <para>Thread safety: Must be iterated on Unity main thread. No Unity main thread requirement for task execution.</para>
+        /// <para>Performance: Yields every frame until task completes. O(1) per iteration.</para>
+        /// <para>Allocations: Allocates iterator state machine.</para>
+        /// <para>Edge cases: Throws task.Exception if task is faulted. Blocks coroutine execution until task completes.</para>
+        /// </remarks>
+        /// <exception cref="Exception">Throws the task's exception if the task is faulted.</exception>
+        public static IEnumerator AsCoroutine(this Task task)
+        {
+            while (!task.IsCompleted)
+            {
+                yield return null;
+            }
+
+            if (task.IsFaulted)
+            {
+                throw task.Exception;
+            }
+        }
+
+        /// <summary>
+        /// Converts a Task with a result to a Unity coroutine (IEnumerator), optionally invoking a callback with the result.
+        /// </summary>
+        /// <typeparam name="T">The type of the task result.</typeparam>
+        /// <param name="task">The task to convert.</param>
+        /// <param name="onResult">Optional callback to receive the task result. Can be null.</param>
+        /// <returns>An IEnumerator that can be used with StartCoroutine.</returns>
+        /// <remarks>
+        /// <para>Null handling: Throws NullReferenceException if task is null. onResult can be null.</para>
+        /// <para>Thread safety: Must be iterated on Unity main thread. No Unity main thread requirement for task execution.</para>
+        /// <para>Performance: Yields every frame until task completes. O(1) per iteration.</para>
+        /// <para>Allocations: Allocates iterator state machine.</para>
+        /// <para>Edge cases: Throws task.Exception if task is faulted. onResult is invoked with result after successful completion.</para>
+        /// </remarks>
+        /// <exception cref="Exception">Throws the task's exception if the task is faulted.</exception>
+        public static IEnumerator AsCoroutine<T>(this Task<T> task, Action<T> onResult = null)
+        {
+            while (!task.IsCompleted)
+            {
+                yield return null;
+            }
+
+            if (task.IsFaulted)
+            {
+                throw task.Exception;
+            }
+
+            onResult?.Invoke(task.Result);
+        }
+
+        /// <summary>
+        /// Converts a ValueTask to a Unity coroutine (IEnumerator).
+        /// </summary>
+        /// <param name="task">The ValueTask to convert.</param>
+        /// <returns>An IEnumerator that can be used with StartCoroutine.</returns>
+        /// <remarks>
+        /// <para>Null handling: ValueTask is a value type and cannot be null.</para>
+        /// <para>Thread safety: Must be iterated on Unity main thread. No Unity main thread requirement for task execution.</para>
+        /// <para>Performance: No yielding if already complete. Otherwise yields every frame. O(1) per iteration.</para>
+        /// <para>Allocations: No allocations if already complete. Otherwise allocates iterator and converts to Task internally.</para>
+        /// <para>Edge cases: Returns immediately if task is already completed. Throws task exception if faulted.</para>
+        /// </remarks>
+        /// <exception cref="Exception">Throws the task's exception if the task is faulted.</exception>
+        public static IEnumerator AsCoroutine(this ValueTask task)
+        {
+            if (task.IsCompleted)
+            {
+                if (task.IsFaulted)
+                {
+                    throw task.AsTask().Exception;
+                }
+                yield break;
+            }
+
+            Task innerTask = task.AsTask();
+            while (!innerTask.IsCompleted)
+            {
+                yield return null;
+            }
+
+            if (innerTask.IsFaulted)
+            {
+                throw innerTask.Exception;
+            }
+        }
+
+        /// <summary>
+        /// Converts a ValueTask with a result to a Unity coroutine (IEnumerator), optionally invoking a callback with the result.
+        /// </summary>
+        /// <typeparam name="T">The type of the task result.</typeparam>
+        /// <param name="task">The ValueTask to convert.</param>
+        /// <param name="onResult">Optional callback to receive the task result. Can be null.</param>
+        /// <returns>An IEnumerator that can be used with StartCoroutine.</returns>
+        /// <remarks>
+        /// <para>Null handling: ValueTask is a value type and cannot be null. onResult can be null.</para>
+        /// <para>Thread safety: Must be iterated on Unity main thread. No Unity main thread requirement for task execution.</para>
+        /// <para>Performance: No yielding if already complete. Otherwise yields every frame. O(1) per iteration.</para>
+        /// <para>Allocations: No allocations if already complete. Otherwise allocates iterator and converts to Task internally.</para>
+        /// <para>Edge cases: Returns immediately if task is already completed. onResult invoked with result after successful completion.</para>
+        /// </remarks>
+        /// <exception cref="Exception">Throws the task's exception if the task is faulted.</exception>
+        public static IEnumerator AsCoroutine<T>(this ValueTask<T> task, Action<T> onResult = null)
+        {
+            if (task.IsCompleted)
+            {
+                if (task.IsFaulted)
+                {
+                    throw task.AsTask().Exception;
+                }
+                onResult?.Invoke(task.Result);
+                yield break;
+            }
+
+            Task<T> innerTask = task.AsTask();
+            while (!innerTask.IsCompleted)
+            {
+                yield return null;
+            }
+
+            if (innerTask.IsFaulted)
+            {
+                throw innerTask.Exception;
+            }
+
+            onResult?.Invoke(innerTask.Result);
+        }
+
+        // IEnumerator to Task/ValueTask conversions
+        /// <summary>
+        /// Converts a Unity coroutine (IEnumerator) to a Task.
+        /// </summary>
+        /// <param name="coroutine">The coroutine to convert.</param>
+        /// <returns>A Task that completes when the coroutine finishes.</returns>
+        /// <remarks>
+        /// <para>Null handling: Throws ArgumentNullException if coroutine is null.</para>
+        /// <para>Thread safety: Coroutine must be iterated on the thread where it's executed. Typically requires Unity main thread.</para>
+        /// <para>Performance: O(n) where n is the number of iterations. Yields control between iterations.</para>
+        /// <para>Allocations: Allocates async state machine.</para>
+        /// <para>Edge cases: Does not use Unity's StartCoroutine - manually iterates the enumerator. Task.Yield() returns control to caller between iterations.</para>
+        /// </remarks>
+        /// <exception cref="ArgumentNullException">Thrown when coroutine is null.</exception>
+        public static async Task AsTask(this IEnumerator coroutine)
+        {
+            if (coroutine == null)
+            {
+                throw new ArgumentNullException(nameof(coroutine));
+            }
+
+            while (coroutine.MoveNext())
+            {
+                await Task.Yield();
+            }
+        }
+
+        /// <summary>
+        /// Converts a Unity coroutine (IEnumerator) to a ValueTask.
+        /// </summary>
+        /// <param name="coroutine">The coroutine to convert.</param>
+        /// <returns>A ValueTask that completes when the coroutine finishes.</returns>
+        /// <remarks>
+        /// <para>Null handling: Throws ArgumentNullException if coroutine is null.</para>
+        /// <para>Thread safety: Coroutine must be iterated on the thread where it's executed. Typically requires Unity main thread.</para>
+        /// <para>Performance: O(n) where n is the number of iterations. Yields control between iterations.</para>
+        /// <para>Allocations: Allocates async state machine.</para>
+        /// <para>Edge cases: Does not use Unity's StartCoroutine - manually iterates the enumerator. Task.Yield() returns control to caller between iterations.</para>
+        /// </remarks>
+        /// <exception cref="ArgumentNullException">Thrown when coroutine is null.</exception>
+        public static async ValueTask AsValueTask(this IEnumerator coroutine)
+        {
+            if (coroutine == null)
+            {
+                throw new ArgumentNullException(nameof(coroutine));
+            }
+
+            while (coroutine.MoveNext())
+            {
+                await Task.Yield();
+            }
+        }
+    }
+}

package/Runtime/Core/Extension/AsyncOperationExtensions.cs.meta

@@ -1,3 +1,3 @@
-fileFormatVersion: 2
-guid: 198fd29beff34b32b0d4c19eb0ce843b
+fileFormatVersion: 2
+guid: 198fd29beff34b32b0d4c19eb0ce843b
 timeCreated: 1743991510