diff --git a/dev/Telegrator.RoslynGenerators/ImplicitHandlerBuilderExtensionsGenerator.cs b/dev/Telegrator.RoslynGenerators/ImplicitHandlerBuilderExtensionsGenerator.cs index 1d993ac..6ace9a5 100644 --- a/dev/Telegrator.RoslynGenerators/ImplicitHandlerBuilderExtensionsGenerator.cs +++ b/dev/Telegrator.RoslynGenerators/ImplicitHandlerBuilderExtensionsGenerator.cs @@ -100,7 +100,13 @@ public class ImplicitHandlerBuilderExtensionsGenerator : IIncrementalGenerator continue; usings.UnionAdd(classDeclaration.FindAncestor().Usings, UsingEqualityComparer); - MethodDeclarationSyntax targeter = FindTargetterMethod(targetters, classDeclaration); + MethodDeclarationSyntax? targeter = FindTargetterMethod(targetters, classDeclaration); + + if (targeter == null) + { + debugExport.AppendLine("Targetter not found"); + continue; + } if (classDeclaration.ParameterList != null && classDeclaration.BaseList != null) { @@ -227,7 +233,7 @@ public class ImplicitHandlerBuilderExtensionsGenerator : IIncrementalGenerator private static IEnumerable GetConstructors(ClassDeclarationSyntax classDeclaration) => classDeclaration.Members.OfType().Where(ctor => ctor.Modifiers.HasModifiers("public")); - private static MethodDeclarationSyntax FindTargetterMethod(Dictionary targeters, ClassDeclarationSyntax classDeclaration) + private static MethodDeclarationSyntax? FindTargetterMethod(Dictionary targeters, ClassDeclarationSyntax classDeclaration) { if (targeters.TryGetValue(classDeclaration.Identifier.ValueText, out MethodDeclarationSyntax targeter)) return targeter; @@ -235,7 +241,7 @@ public class ImplicitHandlerBuilderExtensionsGenerator : IIncrementalGenerator if (classDeclaration.BaseList != null && targeters.TryGetValue(classDeclaration.BaseList.Types.ElementAt(0).Type.ToString(), out targeter)) return targeter; - throw new TargteterNotFoundException(); + return null; } private static SyntaxTriviaList BuildExtensionXmlDocTrivia(ClassDeclarationSyntax classDeclaration, ParameterListSyntax methodParameters) diff --git a/docs/Telegartor.RedisStateStorage.xml b/docs/Telegartor.RedisStateStorage.xml new file mode 100644 index 0000000..a89e7b2 --- /dev/null +++ b/docs/Telegartor.RedisStateStorage.xml @@ -0,0 +1,29 @@ + + + + Telegartor.RedisStateStorage + + + + + Provides a Redis-based implementation of the interface. + Serializes state objects to JSON format before storing them in the Redis database. + + + + + Provides a Redis-based implementation of the interface. + Serializes state objects to JSON format before storing them in the Redis database. + + + + + + + + + + + + + diff --git a/docs/Telegrator.xml b/docs/Telegrator.xml index ce8c582..819efc1 100644 --- a/docs/Telegrator.xml +++ b/docs/Telegrator.xml @@ -769,6 +769,33 @@ + + + Attribute for filtering updates where resolved state matches target value. + + + + + + + + Attribute for filtering updates where resolved state matches target value. + + + + + + + + The targetting state value. + + + + + + + + Attribute for filtering message with command "start" in bot's private chats. @@ -2896,6 +2923,80 @@ The update to resolve the key from. The resolved key. + + + Defines a contract for a state machine that manages transitions and retrieves states for specific updates. + + The type of the state. Must implement . + + + + Gets the current state associated with the specified update key. + + The storage mechanism used to persist the state. + The unique key identifying the current update context (e.g., chat and user ID). + A cancellation token that can be used by other objects or threads to receive notice of cancellation. + A task that represents the asynchronous operation. The task result contains the current state, or the default value if no state is found. + + + + Advances the state machine to the next state in the sequence. + + The storage mechanism used to persist the state. + The unique key identifying the current update context. + A cancellation token that can be used by other objects or threads to receive notice of cancellation. + A task that represents the asynchronous transition operation. + + + + Moves the state machine backward to the previous state in the sequence. + + The storage mechanism used to persist the state. + The unique key identifying the current update context. + A cancellation token that can be used by other objects or threads to receive notice of cancellation. + A task that represents the asynchronous transition operation. + + + + Resets the state machine to its initial or default state. + + The storage mechanism used to persist the state. + The unique key identifying the current update context. + A cancellation token that can be used by other objects or threads to receive notice of cancellation. + A task that represents the asynchronous reset operation. + + + + Defines a contract for an asynchronous state storage mechanism. + + + + + Saves or updates a state value associated with the specified key. + + The type of the state object. + The unique identifier for the state. + The state object to store. + A cancellation token that can be used by other objects or threads to receive notice of cancellation. + A task that represents the asynchronous save operation. + + + + Retrieves a state value associated with the specified key. + + The type of the state object to retrieve. + The unique identifier for the state. + A cancellation token that can be used by other objects or threads to receive notice of cancellation. + A task that represents the asynchronous retrieve operation. The task result contains the state object if found; otherwise, the default value of . + + + + Deletes the state value associated with the specified key. + + The unique identifier for the state to remove. + A cancellation token that can be used by other objects or threads to receive notice of cancellation. + A task that represents the asynchronous delete operation. + Enumeration of dice types supported by Telegram. @@ -4996,6 +5097,7 @@ + @@ -6548,6 +6650,20 @@ The chat ID as a long value. Thrown when the update does not contain a valid chat ID. + + + Defines default in-memory state storage + + + + + + + + + + + State machine implementation for enum-based states. @@ -6581,6 +6697,29 @@ The sender ID as a long value. Thrown when the update does not contain a valid sender ID. + + + + + + + + + Chosen key resolver + + + + + + + + + + + + + + Implementation of that provides bot information. @@ -6872,6 +7011,73 @@ An enumerable of bot commands. + + + Provides extension methods for to easily initialize state machines. + + + + + Initializes a state machine using the default for the specified update. + + The enum type representing the state. + The storage mechanism used to persist the state. + The update context to resolve the state key from. + A new instance of . + + + + Initializes a specific custom state machine for the specified update. + + The type of the state machine logic implementation. + The type of the state. + The storage mechanism used to persist the state. + The update context to resolve the state key from. + A new instance of . + + + + Initializes a state machine and explicitly configures it to resolve keys by the chat ID. + + The type of the state machine logic implementation. + The type of the state. + The storage mechanism used to persist the state. + The update context to resolve the state key from. + A configured instance of . + + + + Initializes a state machine and explicitly configures it to resolve keys by the sender (user) ID. + + The type of the state machine logic implementation. + The type of the state. + The storage mechanism used to persist the state. + The update context to resolve the state key from. + A configured instance of . + + + + Provides fluent extension methods for configuring instances. + + + + + Configures the state machine to use a for state key resolution. + + The type of the state machine logic implementation. + The type of the state. + The state machine instance to configure. + The same state machine instance for method chaining. + + + + Configures the state machine to use a for state key resolution. + + The type of the state machine logic implementation. + The type of the state. + The state machine instance to configure. + The same state machine instance for method chaining. + Extension methods for handlers collections. @@ -7034,5 +7240,582 @@ + + + Adds a CallbackDataAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The data. + The same builder instance. + + + + Adds a CallbackInlineIdAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The inlineMessageId. + The same builder instance. + + + + Adds a CommandAlliasAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The alliases. + The same builder instance. + + + + Adds a ArgumentCountAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The count. + The same builder instance. + + + + Adds a ArgumentStartsWithAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The content. + The comparison. + The index. + The same builder instance. + + + + Adds a ArgumentEndsWithAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The content. + The comparison. + The index. + The same builder instance. + + + + Adds a ArgumentContainsAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The content. + The comparison. + The index. + The same builder instance. + + + + Adds a ArgumentEqualsAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The content. + The comparison. + The index. + The same builder instance. + + + + Adds a ArgumentRegexAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The pattern. + The options. + The index. + The same builder instance. + + + + Adds a IsDebugEnvironmentAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The same builder instance. + + + + Adds a IsReleaseEnvironmentAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The same builder instance. + + + + Adds a EnvironmentVariableAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The variable. + The value. + The comparison. + The same builder instance. + + + + Adds a EnvironmentVariableAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The variable. + The value. + The same builder instance. + + + + Adds a EnvironmentVariableAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The variable. + The same builder instance. + + + + Adds a EnvironmentVariableAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The variable. + The comparison. + The same builder instance. + + + + Adds a MentionedAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The same builder instance. + + + + Adds a MentionedAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The offset. + The same builder instance. + + + + Adds a MentionedAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The mention. + The same builder instance. + + + + Adds a MentionedAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The mention. + The offset. + The same builder instance. + + + + Adds a ChatIsForumAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The same builder instance. + + + + Adds a ChatIdAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The id. + The same builder instance. + + + + Adds a ChatTypeAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The type. + The same builder instance. + + + + Adds a ChatTypeAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The flags. + The same builder instance. + + + + Adds a ChatTitleAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The title. + The comparison. + The same builder instance. + + + + Adds a ChatTitleAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The title. + The same builder instance. + + + + Adds a ChatUsernameAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The userName. + The comparison. + The same builder instance. + + + + Adds a ChatUsernameAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The userName. + The same builder instance. + + + + Adds a ChatNameAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The firstName. + The lastName. + The comparison. + The same builder instance. + + + + Adds a ChatNameAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The firstName. + The lastName. + The same builder instance. + + + + Adds a MessageRegexAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The pattern. + The regexOptions. + The same builder instance. + + + + Adds a MessageRegexAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The regex. + The same builder instance. + + + + Adds a DiceThrowedAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The value. + The same builder instance. + + + + Adds a DiceThrowedAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The diceType. + The value. + The same builder instance. + + + + Adds a IsAutomaticFormwardMessageAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The same builder instance. + + + + Adds a IsFromOfflineMessageAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The same builder instance. + + + + Adds a IsServiceMessageMessageAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The same builder instance. + + + + Adds a IsTopicMessageMessageAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The same builder instance. + + + + Adds a MessageHasEntityAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The type. + The same builder instance. + + + + Adds a MessageHasEntityAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The type. + The offset. + The length. + The same builder instance. + + + + Adds a MessageHasEntityAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The type. + The content. + The stringComparison. + The same builder instance. + + + + Adds a MessageHasEntityAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The type. + The offset. + The length. + The content. + The stringComparison. + The same builder instance. + + + + Adds a MeRepliedAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The same builder instance. + + + + Adds a HasReplyAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The replyDepth. + The same builder instance. + + + + Adds a FromReplyChainAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The replyDepth. + The same builder instance. + + + + Adds a FromUsernameAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The username. + The same builder instance. + + + + Adds a FromUsernameAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The username. + The comparison. + The same builder instance. + + + + Adds a FromUserAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The firstName. + The lastName. + The comparison. + The same builder instance. + + + + Adds a FromUserAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The firstName. + The lastName. + The same builder instance. + + + + Adds a FromUserAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The firstName. + The same builder instance. + + + + Adds a FromUserAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The firstName. + The comparison. + The same builder instance. + + + + Adds a FromUserIdAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The userId. + The same builder instance. + + + + Adds a NotFromBotAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The same builder instance. + + + + Adds a FromBotAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The same builder instance. + + + + Adds a FromPremiumUserAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The same builder instance. + + + + Adds a TextStartsWithAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The content. + The comparison. + The same builder instance. + + + + Adds a TextEndsWithAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The content. + The comparison. + The same builder instance. + + + + Adds a TextContainsAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The content. + The comparison. + The same builder instance. + + + + Adds a TextEqualsAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The content. + The comparison. + The same builder instance. + + + + Adds a HasTextAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The same builder instance. + + + + Adds a TextContainsWordAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The word. + The comparison. + The startIndex. + The same builder instance. + + + + Adds a WelcomeAttribute target filter to the handler builder. + + The builder type. + The handler builder. + The onlyFirst. + The same builder instance. + diff --git a/src/Telegartor.RedisStateStorage/States/RedisStateStorage.cs b/src/Telegartor.RedisStateStorage/States/RedisStateStorage.cs index 01f89c2..214fd5c 100644 --- a/src/Telegartor.RedisStateStorage/States/RedisStateStorage.cs +++ b/src/Telegartor.RedisStateStorage/States/RedisStateStorage.cs @@ -4,6 +4,10 @@ using Telegrator.Core.States; namespace Telegrator.States; +/// +/// Provides a Redis-based implementation of the interface. +/// Serializes state objects to JSON format before storing them in the Redis database. +/// public class RedisStateStorage(IConnectionMultiplexer redis) : IStateStorage { private readonly IDatabase _db = redis.GetDatabase(); @@ -30,6 +34,6 @@ public class RedisStateStorage(IConnectionMultiplexer redis) : IStateStorage /// public async Task DeleteAsync(string key, CancellationToken cancellationToken = default) { - throw new NotImplementedException(); + await _db.KeyDeleteAsync(key); } } \ No newline at end of file diff --git a/src/Telegrator.Localized/Telegrator.Localized.csproj b/src/Telegrator.Localized/Telegrator.Localized.csproj index 2c1a84a..11fe976 100644 --- a/src/Telegrator.Localized/Telegrator.Localized.csproj +++ b/src/Telegrator.Localized/Telegrator.Localized.csproj @@ -1,7 +1,7 @@  - netstandard2.0 + netstandard2.1 latest diff --git a/src/Telegrator/Annotations/StateAttribute.cs b/src/Telegrator/Annotations/StateAttribute.cs index 5adfdd1..751c702 100644 --- a/src/Telegrator/Annotations/StateAttribute.cs +++ b/src/Telegrator/Annotations/StateAttribute.cs @@ -6,14 +6,25 @@ using Telegrator.Filters; namespace Telegrator.Annotations; +/// +/// Attribute for filtering updates where resolved state matches target value. +/// +/// +/// +/// public class StateAttribute(TValue? value) : UpdateFilterAttribute(new StateKeyFilter(value)) where TKey : IStateKeyResolver, new() where TValue : IEquatable { + /// + /// The targetting state value. + /// public TValue? Value => value; + /// public override UpdateType[] AllowedTypes => Update.AllTypes; + /// public override Update? GetFilterringTarget(Update update) { return update; diff --git a/src/Telegrator/Core/States/IStateMachine.cs b/src/Telegrator/Core/States/IStateMachine.cs index 5506c2b..b132f3d 100644 --- a/src/Telegrator/Core/States/IStateMachine.cs +++ b/src/Telegrator/Core/States/IStateMachine.cs @@ -1,9 +1,44 @@ namespace Telegrator.Core.States; +/// +/// Defines a contract for a state machine that manages transitions and retrieves states for specific updates. +/// +/// The type of the state. Must implement . public interface IStateMachine where TState : IEquatable { + /// + /// Gets the current state associated with the specified update key. + /// + /// The storage mechanism used to persist the state. + /// The unique key identifying the current update context (e.g., chat and user ID). + /// A cancellation token that can be used by other objects or threads to receive notice of cancellation. + /// A task that represents the asynchronous operation. The task result contains the current state, or the default value if no state is found. Task Current(IStateStorage storage, string updateKey, CancellationToken cancellationToken = default); + + /// + /// Advances the state machine to the next state in the sequence. + /// + /// The storage mechanism used to persist the state. + /// The unique key identifying the current update context. + /// A cancellation token that can be used by other objects or threads to receive notice of cancellation. + /// A task that represents the asynchronous transition operation. Task Advance(IStateStorage storage, string updateKey, CancellationToken cancellationToken = default); + + /// + /// Moves the state machine backward to the previous state in the sequence. + /// + /// The storage mechanism used to persist the state. + /// The unique key identifying the current update context. + /// A cancellation token that can be used by other objects or threads to receive notice of cancellation. + /// A task that represents the asynchronous transition operation. Task Retreat(IStateStorage storage, string updateKey, CancellationToken cancellationToken = default); + + /// + /// Resets the state machine to its initial or default state. + /// + /// The storage mechanism used to persist the state. + /// The unique key identifying the current update context. + /// A cancellation token that can be used by other objects or threads to receive notice of cancellation. + /// A task that represents the asynchronous reset operation. Task Reset(IStateStorage storage, string updateKey, CancellationToken cancellationToken = default); -} +} \ No newline at end of file diff --git a/src/Telegrator/Core/States/IStateStorage.cs b/src/Telegrator/Core/States/IStateStorage.cs index c48cb2e..17c4ccb 100644 --- a/src/Telegrator/Core/States/IStateStorage.cs +++ b/src/Telegrator/Core/States/IStateStorage.cs @@ -1,8 +1,34 @@ namespace Telegrator.Core.States; +/// +/// Defines a contract for an asynchronous state storage mechanism. +/// public interface IStateStorage { + /// + /// Saves or updates a state value associated with the specified key. + /// + /// The type of the state object. + /// The unique identifier for the state. + /// The state object to store. + /// A cancellation token that can be used by other objects or threads to receive notice of cancellation. + /// A task that represents the asynchronous save operation. Task SetAsync(string key, T state, CancellationToken cancellationToken = default); + + /// + /// Retrieves a state value associated with the specified key. + /// + /// The type of the state object to retrieve. + /// The unique identifier for the state. + /// A cancellation token that can be used by other objects or threads to receive notice of cancellation. + /// A task that represents the asynchronous retrieve operation. The task result contains the state object if found; otherwise, the default value of . Task GetAsync(string key, CancellationToken cancellationToken = default); + + /// + /// Deletes the state value associated with the specified key. + /// + /// The unique identifier for the state to remove. + /// A cancellation token that can be used by other objects or threads to receive notice of cancellation. + /// A task that represents the asynchronous delete operation. Task DeleteAsync(string key, CancellationToken cancellationToken = default); -} +} \ No newline at end of file diff --git a/src/Telegrator/Handlers/HandlerContainer.cs b/src/Telegrator/Handlers/HandlerContainer.cs index d489b58..663df37 100644 --- a/src/Telegrator/Handlers/HandlerContainer.cs +++ b/src/Telegrator/Handlers/HandlerContainer.cs @@ -61,6 +61,7 @@ namespace Telegrator.Handlers /// /// /// + /// public HandlerContainer(TUpdate actualUpdate, Update handlingUpdate, ITelegramBotClient client, Dictionary extraData, CompletedFiltersList filters, IAwaitingProvider awaitingProvider, IStateStorage stateStorage) { ActualUpdate = actualUpdate; diff --git a/src/Telegrator/States/DefaultStateStorage.cs b/src/Telegrator/States/DefaultStateStorage.cs index 1cdcd30..3133cf9 100644 --- a/src/Telegrator/States/DefaultStateStorage.cs +++ b/src/Telegrator/States/DefaultStateStorage.cs @@ -3,10 +3,14 @@ using Telegrator.Core.States; namespace Telegrator.States; +/// +/// Defines default in-memory state storage +/// public class DefaultStateStorage : IStateStorage { private readonly ConcurrentDictionary storage = []; + /// public Task DeleteAsync(string key, CancellationToken cancellationToken = default) { if (key is null) @@ -18,6 +22,7 @@ public class DefaultStateStorage : IStateStorage return Task.CompletedTask; } + /// public Task GetAsync(string key, CancellationToken ccancellationTokent = default) { if (key is null) @@ -29,6 +34,7 @@ public class DefaultStateStorage : IStateStorage return Task.FromResult(default(T)); } + /// public Task SetAsync(string key, T state, CancellationToken cancellationToken = default) { if (key is null) diff --git a/src/Telegrator/States/StateMachine.cs b/src/Telegrator/States/StateMachine.cs index aa2ef72..af913bd 100644 --- a/src/Telegrator/States/StateMachine.cs +++ b/src/Telegrator/States/StateMachine.cs @@ -3,6 +3,7 @@ using Telegrator.Core.States; namespace Telegrator.States; +/// public class StateMachine(IStateStorage stateStorage, Update handlingUpdate) where TMachine : IStateMachine, new() where TState : IEquatable @@ -11,8 +12,12 @@ public class StateMachine(IStateStorage stateStorage, Update h private readonly Update _handlingUpdate = handlingUpdate; private readonly IStateMachine _stateMachine = new TMachine(); + /// + /// Chosen key resolver + /// public IStateKeyResolver? KeyResolver; + /// public async Task Advance(CancellationToken cancellationToken = default) { if (KeyResolver is null) @@ -25,6 +30,7 @@ public class StateMachine(IStateStorage stateStorage, Update h await _stateMachine.Advance(_stateStorage, key, cancellationToken); } + /// public async Task Current(CancellationToken cancellationToken = default) { if (KeyResolver is null) @@ -37,6 +43,7 @@ public class StateMachine(IStateStorage stateStorage, Update h return await _stateMachine.Current(_stateStorage, key, cancellationToken); } + /// public async Task Reset(CancellationToken cancellationToken = default) { if (KeyResolver is null) @@ -49,6 +56,7 @@ public class StateMachine(IStateStorage stateStorage, Update h await _stateMachine.Reset(_stateStorage, key, cancellationToken); } + /// public async Task Retreat(CancellationToken cancellationToken = default) { if (KeyResolver is null) diff --git a/src/Telegrator/TypesExtensions.cs b/src/Telegrator/TypesExtensions.cs index d1f6a3a..3db5e4c 100644 --- a/src/Telegrator/TypesExtensions.cs +++ b/src/Telegrator/TypesExtensions.cs @@ -284,30 +284,74 @@ namespace Telegrator } } + /// + /// Provides extension methods for to easily initialize state machines. + /// public static class StateStorageExtensions { + /// + /// Initializes a state machine using the default for the specified update. + /// + /// The enum type representing the state. + /// The storage mechanism used to persist the state. + /// The update context to resolve the state key from. + /// A new instance of . public static StateMachine, TState> GetStateMachine(this IStateStorage stateStorage, Update handlingUpdate) where TState : struct, Enum, IEquatable => new StateMachine, TState>(stateStorage, handlingUpdate); + /// + /// Initializes a specific custom state machine for the specified update. + /// + /// The type of the state machine logic implementation. + /// The type of the state. + /// The storage mechanism used to persist the state. + /// The update context to resolve the state key from. + /// A new instance of . public static StateMachine GetStateMachine(this IStateStorage stateStorage, Update handlingUpdate) where TMachine : IStateMachine, new() where TState : IEquatable => new StateMachine(stateStorage, handlingUpdate); + /// + /// Initializes a state machine and explicitly configures it to resolve keys by the chat ID. + /// + /// The type of the state machine logic implementation. + /// The type of the state. + /// The storage mechanism used to persist the state. + /// The update context to resolve the state key from. + /// A configured instance of . public static StateMachine ByChatId(this IStateStorage stateStorage, Update handlingUpdate) where TMachine : IStateMachine, new() where TState : IEquatable => new StateMachine(stateStorage, handlingUpdate).ByChatId(); + /// + /// Initializes a state machine and explicitly configures it to resolve keys by the sender (user) ID. + /// + /// The type of the state machine logic implementation. + /// The type of the state. + /// The storage mechanism used to persist the state. + /// The update context to resolve the state key from. + /// A configured instance of . public static StateMachine BySenderId(this IStateStorage stateStorage, Update handlingUpdate) where TMachine : IStateMachine, new() where TState : IEquatable => new StateMachine(stateStorage, handlingUpdate).BySenderId(); } + /// + /// Provides fluent extension methods for configuring instances. + /// public static class StateMachineExtensions { + /// + /// Configures the state machine to use a for state key resolution. + /// + /// The type of the state machine logic implementation. + /// The type of the state. + /// The state machine instance to configure. + /// The same state machine instance for method chaining. public static StateMachine ByChatId(this StateMachine stateMachine) where TMachine : IStateMachine, new() where TState : IEquatable @@ -316,6 +360,13 @@ namespace Telegrator return stateMachine; } + /// + /// Configures the state machine to use a for state key resolution. + /// + /// The type of the state machine logic implementation. + /// The type of the state. + /// The state machine instance to configure. + /// The same state machine instance for method chaining. public static StateMachine BySenderId(this StateMachine stateMachine) where TMachine : IStateMachine, new() where TState : IEquatable