Merge pull request #48 from I-RzR-I/feature/LazyAndImprovements

Feature/lazy and improvements

Author: I-RzR-I

README.md

@@ -5,9 +5,9 @@
 
 This library/ repository was created as a way to simplify the development process. Here were written the usually used methods (extension methods) for some data types like `int, string, DateTime, Enum, bool, byte, Guid`, also there was added extensions for `List, Dictionary, DynamicList` and other collections(`ICollection, IEnumerable, IList, HashSet, IQueryable`).
 
-In the repository was added an extension for `cryptography`, encrypting and decrypting string by key with `RSA`, `AES`, `TEA``
+In the repository was added an extension for `cryptography`, encrypting and decrypting string by key with `RSA`, `AES`, `TEA`.
 
-In case you need some get some documentation/comments from `Assembly`, here too are some extensions.
+In case you need some get some documentation/comments from `Assembly`, here too are some extensions. Also you can find a async lazy load `AsyncLazy<T>` and `AsyncExpiringLazy<T>`.
 
 Also here you may find extensions for `SystemData (DbDataReader, DataRecord, DataTable)` lib, `FileStream, MemoryStream, Type`, and a lot other of methods and not the last some `Linq` and `Expression` extensions that can help to make code mode clean.
 

docs/CHANGELOG.md

@@ -1,3 +1,11 @@
+### **v4.6.0.8232** [[RzR](mailto:108324929+I-RzR-I@users.noreply.github.com)] 20-03-2026
+* [5503224] (RzR) -> Auto commit uncommited files
+* [e9aa417] (RzR) -> Add small improvements
+* [3982b59] (RzR) -> Add async lazy load `AsyncLazy<T>` and `AsyncExpiringLazy<T>`.
+* [ded7012] (RzR) -> Add improvements to the documentation of `TupleResult`
+* [879e778] (RzR) -> Add new string extension methods: `IsMissingOrAny`, `IfIsMissingOrAny`.
+* [b1a924b] (RzR) -> Add `TupleResult` deconstruct data.
+
 ### **v4.5.0.7408** [[RzR](mailto:108324929+I-RzR-I@users.noreply.github.com)] 11-02-2026
 * [a4fd120] (RzR) -> Auto commit uncommited files
 * [bae196d] (RzR) -> Add enumerable method `SelectWithIsLast` and `WithObservable`

docs/usage.md

@@ -3,3 +3,99 @@
 I think using these methods is no need for any explanations. Here you may find a lot of extensions that help in projects development.
 
 The source code is open, so you can check what are available and what you can find useful and can use in your project.
+
+---
+
+## Async lazy load `AsyncLazy<T>` and `AsyncExpiringLazy<T>`
+
+## **`AsyncLazy<T>`**
+
+A thread-safe asynchronous lazy initializer. Factory runs exactly once; faults and cancellations auto-reset so the next caller retries.
+
+### Constructor
+
+| Signature | Description | Throws |
+|---|---|---|
+| `AsyncLazy(Func<CancellationToken, Task<T>> factory)` | Registers the factory delegate. The factory is called on first demand, and again after any fault or cancellation. The `CancellationToken` it receives is cancelled by `Reset()` if called while the factory is running. | `ArgumentNullException` — `factory` is `null` |
+
+### Properties
+
+| Property | Type | Description |
+|---|---|---|
+| `IsValueCreated` | `bool` | `true` only when the factory completed successfully and the result has not been cleared by `Reset()`. `false` while in-progress, faulted, cancelled, or after reset. |
+| `IsInitializationStarted` | `bool` | `true` once `GetValueAsync()` has been called at least once and the state has not been cleared. Stays `true` while the factory is still running or has faulted, until `Reset()` is called. |
+
+### Methods
+
+| Signature | Returns | Description | Notes |
+|---|---|---|---|
+| `GetValueAsync(CancellationToken ct = default)` | `Task<T>` | Returns the cached task on subsequent calls. Starts the factory on the first call. All concurrent callers share the same in-progress task. | If the factory faults or is cancelled, state is auto-cleared so the next call retries from scratch. The token only affects the current in-flight factory; other concurrent waiters are not independently cancelled. |
+| `TryGetValue(out T value)` | `bool` | Synchronously returns the cached value without triggering initialization. | Returns `false` if not yet computed, still in-progress, faulted, or reset. Zero allocations — safe to call on hot paths. |
+| `Reset()` | `void` | Atomically clears state and cancels any in-progress factory invocation. After this call both `IsValueCreated` and `IsInitializationStarted` return `false`. | Safe to call concurrently or multiple times. |
+| `GetAwaiter()` | `TaskAwaiter<T>` | Enables `await myLazy` shorthand syntax equivalent to `await myLazy.GetValueAsync()`. | — |
+
+### Behavior summary
+
+| Scenario | Outcome |
+|---|---|
+| First call | Factory invoked; all concurrent callers share the same `Task<T>` |
+| Subsequent calls (success) | Cached `Task<T>` returned immediately — factory not called again |
+| Factory faults | State auto-cleared; next `GetValueAsync()` call retries |
+| Factory cancelled | State auto-cleared; next `GetValueAsync()` call retries |
+| `Reset()` while in-progress | Linked `CancellationToken` is cancelled; factory receives cancellation |
+| Concurrent `Reset()` + `GetValueAsync()` | Safe — both operate on a single atomically-swapped `LazyState` reference |
+
+---
+
+## `AsyncExpiringLazy<T>`
+
+A thread-safe asynchronous lazy initializer with a configurable TTL. After expiry the next caller transparently triggers a fresh factory invocation.
+
+### Constructor
+
+| Signature | Description | Throws |
+|---|---|---|
+| `AsyncExpiringLazy(Func<CancellationToken, Task<T>> factory, TimeSpan ttl)` | Registers the factory and TTL window. The factory is called on first access, after expiry, after a fault/cancellation, or after `Reset()`. | `ArgumentNullException` — `factory` is `null` |
+| | | `ArgumentOutOfRangeException` — `ttl` is negative |
+
+### Properties
+
+| Property | Type | Description |
+|---|---|---|
+| `IsValueCreated` | `bool` | `true` only when the factory completed successfully **and** the cached result is still within its TTL window. `false` if not computed, faulted, expired, or reset. |
+| `IsInitializationStarted` | `bool` | `true` once the first `GetValueAsync()` call has been made and `Reset()` has not cleared the entry. **Important:** remains `true` even after the TTL expires, because the entry object still exists until it is replaced or cleared. |
+
+### Methods
+
+| Signature | Returns | Description | Notes |
+|---|---|---|---|
+| `GetValueAsync(CancellationToken ct = default)` | `Task<T>` | Returns the cached value if within TTL and healthy. Otherwise starts a fresh factory invocation. Concurrent callers during a single factory run share the same in-progress task (thundering-herd guard). | Faulted or cancelled entries are treated as immediately expired regardless of TTL, allowing instant retry. |
+| `TryGetValue(out T value)` | `bool` | Synchronously returns the cached value without triggering a factory invocation or refreshing an expired entry. | Returns `false` if the entry is missing, expired, or faulted. Zero allocations — safe on hot paths. |
+| `Reset()` | `void` | Immediately evicts the cached entry regardless of the remaining TTL. After this call both `IsValueCreated` and `IsInitializationStarted` return `false`. | Any in-progress factory run is **not** cancelled — it will complete its `TaskCompletionSource`, but the result is invisible to new callers. Safe to call concurrently or multiple times. |
+| `GetAwaiter()` | `TaskAwaiter<T>` | Enables `await myExpiringLazy` shorthand syntax equivalent to `await myExpiringLazy.GetValueAsync()`. | — |
+
+### Behavior summary
+
+| Scenario | Outcome |
+|---|---|
+| First call | Factory invoked; entry stored with expiration = `UtcNow + ttl` |
+| Subsequent calls within TTL (healthy) | Cached `Task<T>` returned immediately |
+| TTL elapsed | Next `GetValueAsync()` triggers a fresh factory invocation |
+| `ttl = TimeSpan.Zero` | Entry expires immediately after creation; factory called on every request |
+| Factory faults (async) | Entry treated as expired; next call retries without waiting for TTL |
+| Factory throws synchronously | No CAS is performed; factory re-invoked on every request until it succeeds |
+| Concurrent callers during refresh | Only the CAS winner invokes the factory; losers await the winner's task |
+| `Reset()` while in-progress | Entry cleared; next caller gets a fresh factory run (old run still completes but its result is discarded) |
+
+---
+
+## Side-by-side comparison
+
+| Feature | `AsyncLazy<T>` | `AsyncExpiringLazy<T>` |
+|---|---|---|
+| **Expiry** | Never — cached forever until `Reset()` | After configured TTL |
+| **Reset behaviour** | Cancels the in-progress factory via linked `CancellationToken` | Clears the entry; in-progress factory is **not** cancelled |
+| **Fault recovery** | Auto-reset on fault/cancel; next caller retries | Auto-reset on fault/cancel; instant retry regardless of TTL |
+| **Constructor params** | `factory` | `factory` + `ttl` |
+| **`IsInitializationStarted` after TTL** | N/A | Still `true` until replaced or `Reset()` |
+| **Use when** | Value must be computed once and reused indefinitely | Value needs periodic refresh (tokens, configs, rates, etc) |

src/DomainCommonExtensions/Collections/DisposableStackCollection.cs

@@ -38,6 +38,11 @@ public class DisposableStackCollection : IDisposable
         /// </summary>
         private Stack<IDisposable> _disposable = new Stack<IDisposable>();
 
+        /// <summary>
+        ///     Tracks whether this instance has already been disposed.
+        /// </summary>
+        private bool _disposed;
+
         /// <summary>
         ///     Gets the stack length.
         /// </summary>
@@ -49,11 +54,18 @@ public class DisposableStackCollection : IDisposable
         /// <inheritdoc />
         public void Dispose()
         {
+            if (_disposed)
+                return;
+
+            _disposed = true;
+
             if (_disposable.IsNotNull())
             {
                 while (_disposable.Count.IsGreaterThanZero())
                     _disposable.Pop().Dispose();
             }
+
+            GC.SuppressFinalize(this);
         }
 
         /// <summary>

src/DomainCommonExtensions/DataTypeExtensions/ObjectExtensions.cs

@@ -178,7 +178,7 @@ public static IDictionary<string, object> ToDictionary(this object obj)
         /// <param name="source">Input source object</param>
         /// <returns></returns>
         /// <remarks></remarks>
-        public static string ToString(this object source)
+        public static string ToSafeString(this object source)
         {
             if (source.IsDbNull() || source.IsNull())
                 return null;

src/DomainCommonExtensions/DataTypeExtensions/StringExtensions.cs

@@ -1931,9 +1931,9 @@ public static string RemovePeriodValue(this string source, string periodDelimite
             if (source.EndsWith(periodDelimiter + period).IsTrue())
             {
                 var idx = source.IndexOf(periodDelimiter + period, StringComparison.Ordinal);
-                
-                return idx == -1 
-                    ? source 
+
+                return idx == -1
+                    ? source
                     : source.Remove(idx, (periodDelimiter + period).Length);
             }
             else return source;
@@ -2064,5 +2064,35 @@ public static string RemoveEndChars(this string source, int length)
 
             return source.Substring(0, source.Length - length);
         }
+
+        /// -------------------------------------------------------------------------------------------------
+        /// <summary>
+        ///     A string extension method that query if 'source' is missing or contains any values form params.
+        /// </summary>
+        /// <param name="source">Source string.</param>
+        /// <param name="checkValues">A variable-length parameters list containing check values.</param>
+        /// <returns>
+        ///     True if missing or any, false if not.
+        /// </returns>
+        /// =================================================================================================
+        public static bool IsMissingOrAny(this string source, params string[] checkValues)
+        {
+            return source.IsMissing() || checkValues.NotNull().Contains(source);
+        }
+
+        /// -------------------------------------------------------------------------------------------------
+        /// <summary>
+        ///     A string extension method that if 'source' is missing or contains any values form params.
+        ///     If is true, then execute action.
+        /// </summary>
+        /// <param name="source">Source string.</param>
+        /// <param name="execAction">The execute action.</param>
+        /// <param name="checkValues">A variable-length parameters list containing check values.</param>
+        /// =================================================================================================
+        public static void IfIsMissingOrAny(this string source, Action execAction, params string[] checkValues)
+        {
+            if (source.IsMissingOrAny(checkValues))
+                execAction();
+        }
     }
 }

src/DomainCommonExtensions/Helpers/IniFileHelper.cs

@@ -112,7 +112,7 @@ public class IniFileHelper
         ///     The class instance.
         /// </summary>
         /// =================================================================================================
-        public static IniFileHelper Instance = new IniFileHelper();
+        public static readonly IniFileHelper Instance = new IniFileHelper();
 
         /// -------------------------------------------------------------------------------------------------
         /// <summary>

src/DomainCommonExtensions/Helpers/RandomHelper.cs

@@ -31,7 +31,7 @@ namespace DomainCommonExtensions.Helpers
     ///     A random helper.
     /// </summary>
     /// =================================================================================================
-    public class RandomHelper
+    public sealed class RandomHelper
     {
         /// -------------------------------------------------------------------------------------------------
         /// <summary>