@mtcute/dispatcher 0.1.0

package/cjs/handler.d.ts

@@ -0,0 +1,31 @@
+import { BotStoppedUpdate, ChatJoinRequestUpdate, ChatMemberUpdate, DeleteMessageUpdate, DeleteStoryUpdate, HistoryReadUpdate, MaybeAsync, PeersIndex, PollUpdate, PollVoteUpdate, StoryUpdate, TelegramClient, tl, UserStatusUpdate, UserTypingUpdate } from '@mtcute/client';
+import { UpdateContext } from './context/base.js';
+import { CallbackQueryContext, ChatJoinRequestUpdateContext, ChosenInlineResultContext, InlineQueryContext, MessageContext, PreCheckoutQueryContext } from './context/index.js';
+import { PropagationAction } from './propagation.js';
+export interface BaseUpdateHandler<Name, Handler, Checker> {
+    name: Name;
+    callback: Handler;
+    check?: Checker;
+}
+export type ParsedUpdateHandler<Name, Update, State = never> = BaseUpdateHandler<Name, (update: Update, state: State) => MaybeAsync<void | PropagationAction>, (update: Update, state: State) => MaybeAsync<boolean>>;
+export type RawUpdateHandler = BaseUpdateHandler<'raw', (client: TelegramClient, update: tl.TypeUpdate | tl.TypeMessage, peers: PeersIndex) => MaybeAsync<void | PropagationAction>, (client: TelegramClient, update: tl.TypeUpdate | tl.TypeMessage, peers: PeersIndex) => MaybeAsync<boolean>>;
+export type NewMessageHandler<T = MessageContext, S = never> = ParsedUpdateHandler<'new_message', T, S>;
+export type EditMessageHandler<T = MessageContext, S = never> = ParsedUpdateHandler<'edit_message', T, S>;
+export type MessageGroupHandler<T = MessageContext, S = never> = ParsedUpdateHandler<'message_group', T, S>;
+export type DeleteMessageHandler<T = UpdateContext<DeleteMessageUpdate>> = ParsedUpdateHandler<'delete_message', T>;
+export type ChatMemberUpdateHandler<T = UpdateContext<ChatMemberUpdate>> = ParsedUpdateHandler<'chat_member', T>;
+export type InlineQueryHandler<T = InlineQueryContext> = ParsedUpdateHandler<'inline_query', T>;
+export type ChosenInlineResultHandler<T = ChosenInlineResultContext> = ParsedUpdateHandler<'chosen_inline_result', T>;
+export type CallbackQueryHandler<T = CallbackQueryContext, S = never> = ParsedUpdateHandler<'callback_query', T, S>;
+export type PollUpdateHandler<T = UpdateContext<PollUpdate>> = ParsedUpdateHandler<'poll', T>;
+export type PollVoteHandler<T = UpdateContext<PollVoteUpdate>> = ParsedUpdateHandler<'poll_vote', T>;
+export type UserStatusUpdateHandler<T = UpdateContext<UserStatusUpdate>> = ParsedUpdateHandler<'user_status', T>;
+export type UserTypingHandler<T = UpdateContext<UserTypingUpdate>> = ParsedUpdateHandler<'user_typing', T>;
+export type HistoryReadHandler<T = UpdateContext<HistoryReadUpdate>> = ParsedUpdateHandler<'history_read', T>;
+export type BotStoppedHandler<T = UpdateContext<BotStoppedUpdate>> = ParsedUpdateHandler<'bot_stopped', T>;
+export type BotChatJoinRequestHandler<T = ChatJoinRequestUpdateContext> = ParsedUpdateHandler<'bot_chat_join_request', T>;
+export type ChatJoinRequestHandler<T = UpdateContext<ChatJoinRequestUpdate>> = ParsedUpdateHandler<'chat_join_request', T>;
+export type PreCheckoutQueryHandler<T = PreCheckoutQueryContext> = ParsedUpdateHandler<'pre_checkout_query', T>;
+export type StoryUpdateHandler<T = UpdateContext<StoryUpdate>> = ParsedUpdateHandler<'story', T>;
+export type DeleteStoryHandler<T = UpdateContext<DeleteStoryUpdate>> = ParsedUpdateHandler<'delete_story', T>;
+export type UpdateHandler = RawUpdateHandler | NewMessageHandler | EditMessageHandler | MessageGroupHandler | DeleteMessageHandler | ChatMemberUpdateHandler | InlineQueryHandler | ChosenInlineResultHandler | CallbackQueryHandler | PollUpdateHandler | PollVoteHandler | UserStatusUpdateHandler | UserTypingHandler | HistoryReadHandler | BotStoppedHandler | BotChatJoinRequestHandler | ChatJoinRequestHandler | PreCheckoutQueryHandler | StoryUpdateHandler | DeleteStoryHandler;

package/cjs/handler.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// end-codegen
+//# sourceMappingURL=handler.js.map

package/cjs/handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.js","sourceRoot":"","sources":["../../src/handler.ts"],"names":[],"mappings":";;AAqGA,cAAc","sourcesContent":["import {\n    BotStoppedUpdate,\n    ChatJoinRequestUpdate,\n    ChatMemberUpdate,\n    DeleteMessageUpdate,\n    DeleteStoryUpdate,\n    HistoryReadUpdate,\n    MaybeAsync,\n    PeersIndex,\n    PollUpdate,\n    PollVoteUpdate,\n    StoryUpdate,\n    TelegramClient,\n    tl,\n    UserStatusUpdate,\n    UserTypingUpdate,\n} from '@mtcute/client'\n\nimport { UpdateContext } from './context/base.js'\nimport {\n    CallbackQueryContext,\n    ChatJoinRequestUpdateContext,\n    ChosenInlineResultContext,\n    InlineQueryContext,\n    MessageContext,\n    PreCheckoutQueryContext,\n} from './context/index.js'\nimport { PropagationAction } from './propagation.js'\n\nexport interface BaseUpdateHandler<Name, Handler, Checker> {\n    name: Name\n    callback: Handler\n\n    check?: Checker\n}\n\nexport type ParsedUpdateHandler<Name, Update, State = never> = BaseUpdateHandler<\n    Name,\n    (update: Update, state: State) => MaybeAsync<void | PropagationAction>,\n    (update: Update, state: State) => MaybeAsync<boolean>\n>\n\nexport type RawUpdateHandler = BaseUpdateHandler<\n    'raw',\n    (\n        client: TelegramClient,\n        update: tl.TypeUpdate | tl.TypeMessage,\n        peers: PeersIndex,\n    ) => MaybeAsync<void | PropagationAction>,\n    (client: TelegramClient, update: tl.TypeUpdate | tl.TypeMessage, peers: PeersIndex) => MaybeAsync<boolean>\n>\n\n// begin-codegen\nexport type NewMessageHandler<T = MessageContext, S = never> = ParsedUpdateHandler<'new_message', T, S>\nexport type EditMessageHandler<T = MessageContext, S = never> = ParsedUpdateHandler<'edit_message', T, S>\nexport type MessageGroupHandler<T = MessageContext, S = never> = ParsedUpdateHandler<'message_group', T, S>\nexport type DeleteMessageHandler<T = UpdateContext<DeleteMessageUpdate>> = ParsedUpdateHandler<'delete_message', T>\nexport type ChatMemberUpdateHandler<T = UpdateContext<ChatMemberUpdate>> = ParsedUpdateHandler<'chat_member', T>\nexport type InlineQueryHandler<T = InlineQueryContext> = ParsedUpdateHandler<'inline_query', T>\nexport type ChosenInlineResultHandler<T = ChosenInlineResultContext> = ParsedUpdateHandler<'chosen_inline_result', T>\nexport type CallbackQueryHandler<T = CallbackQueryContext, S = never> = ParsedUpdateHandler<'callback_query', T, S>\nexport type PollUpdateHandler<T = UpdateContext<PollUpdate>> = ParsedUpdateHandler<'poll', T>\nexport type PollVoteHandler<T = UpdateContext<PollVoteUpdate>> = ParsedUpdateHandler<'poll_vote', T>\nexport type UserStatusUpdateHandler<T = UpdateContext<UserStatusUpdate>> = ParsedUpdateHandler<'user_status', T>\nexport type UserTypingHandler<T = UpdateContext<UserTypingUpdate>> = ParsedUpdateHandler<'user_typing', T>\nexport type HistoryReadHandler<T = UpdateContext<HistoryReadUpdate>> = ParsedUpdateHandler<'history_read', T>\nexport type BotStoppedHandler<T = UpdateContext<BotStoppedUpdate>> = ParsedUpdateHandler<'bot_stopped', T>\nexport type BotChatJoinRequestHandler<T = ChatJoinRequestUpdateContext> = ParsedUpdateHandler<\n    'bot_chat_join_request',\n    T\n>\nexport type ChatJoinRequestHandler<T = UpdateContext<ChatJoinRequestUpdate>> = ParsedUpdateHandler<\n    'chat_join_request',\n    T\n>\nexport type PreCheckoutQueryHandler<T = PreCheckoutQueryContext> = ParsedUpdateHandler<'pre_checkout_query', T>\nexport type StoryUpdateHandler<T = UpdateContext<StoryUpdate>> = ParsedUpdateHandler<'story', T>\nexport type DeleteStoryHandler<T = UpdateContext<DeleteStoryUpdate>> = ParsedUpdateHandler<'delete_story', T>\n\nexport type UpdateHandler =\n    | RawUpdateHandler\n    | NewMessageHandler\n    | EditMessageHandler\n    | MessageGroupHandler\n    | DeleteMessageHandler\n    | ChatMemberUpdateHandler\n    | InlineQueryHandler\n    | ChosenInlineResultHandler\n    | CallbackQueryHandler\n    | PollUpdateHandler\n    | PollVoteHandler\n    | UserStatusUpdateHandler\n    | UserTypingHandler\n    | HistoryReadHandler\n    | BotStoppedHandler\n    | BotChatJoinRequestHandler\n    | ChatJoinRequestHandler\n    | PreCheckoutQueryHandler\n    | StoryUpdateHandler\n    | DeleteStoryHandler\n\n// end-codegen\n"]}

package/cjs/index.d.ts

@@ -0,0 +1,8 @@
+export * from './callback-data-builder.js';
+export * from './context/index.js';
+export * from './dispatcher.js';
+export * from './filters/index.js';
+export * from './handler.js';
+export * from './propagation.js';
+export * from './state/index.js';
+export * from './wizard.js';

package/cjs/index.js

@@ -0,0 +1,25 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./callback-data-builder.js"), exports);
+__exportStar(require("./context/index.js"), exports);
+__exportStar(require("./dispatcher.js"), exports);
+__exportStar(require("./filters/index.js"), exports);
+__exportStar(require("./handler.js"), exports);
+__exportStar(require("./propagation.js"), exports);
+__exportStar(require("./state/index.js"), exports);
+__exportStar(require("./wizard.js"), exports);
+//# sourceMappingURL=index.js.map

package/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,6DAA0C;AAC1C,qDAAkC;AAClC,kDAA+B;AAC/B,qDAAkC;AAClC,+CAA4B;AAC5B,mDAAgC;AAChC,mDAAgC;AAChC,8CAA2B","sourcesContent":["export * from './callback-data-builder.js'\nexport * from './context/index.js'\nexport * from './dispatcher.js'\nexport * from './filters/index.js'\nexport * from './handler.js'\nexport * from './propagation.js'\nexport * from './state/index.js'\nexport * from './wizard.js'\n"]}

package/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/cjs/propagation.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Propagation action.
+ *
+ * `Stop`: Stop the propagation of the event through any handler groups
+ * in the current dispatcher. Does not prevent child dispatchers from
+ * being executed.
+ *
+ * `StopChildren`: Stop the propagation of the event through any handler groups
+ * in the current dispatcher, and any of its children. If current dispatcher
+ * is a child, does not prevent from propagating to its siblings.
+ *
+ * `Continue`: Continue propagating the event inside the same handler group.
+ *
+ * `ToScene`: Used after using `state.enter()` to dispatch the update to the scene
+ */
+export declare enum PropagationAction {
+    Stop = "stop",
+    StopChildren = "stop-children",
+    Continue = "continue",
+    ToScene = "scene"
+}

package/cjs/propagation.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PropagationAction = void 0;
+/**
+ * Propagation action.
+ *
+ * `Stop`: Stop the propagation of the event through any handler groups
+ * in the current dispatcher. Does not prevent child dispatchers from
+ * being executed.
+ *
+ * `StopChildren`: Stop the propagation of the event through any handler groups
+ * in the current dispatcher, and any of its children. If current dispatcher
+ * is a child, does not prevent from propagating to its siblings.
+ *
+ * `Continue`: Continue propagating the event inside the same handler group.
+ *
+ * `ToScene`: Used after using `state.enter()` to dispatch the update to the scene
+ */
+var PropagationAction;
+(function (PropagationAction) {
+    PropagationAction["Stop"] = "stop";
+    PropagationAction["StopChildren"] = "stop-children";
+    PropagationAction["Continue"] = "continue";
+    PropagationAction["ToScene"] = "scene";
+})(PropagationAction = exports.PropagationAction || (exports.PropagationAction = {}));
+//# sourceMappingURL=propagation.js.map

package/cjs/propagation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"propagation.js","sourceRoot":"","sources":["../../src/propagation.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;GAcG;AACH,IAAY,iBAKX;AALD,WAAY,iBAAiB;IACzB,kCAAa,CAAA;IACb,mDAA8B,CAAA;IAC9B,0CAAqB,CAAA;IACrB,sCAAiB,CAAA;AACrB,CAAC,EALW,iBAAiB,GAAjB,yBAAiB,KAAjB,yBAAiB,QAK5B","sourcesContent":["/**\n * Propagation action.\n *\n * `Stop`: Stop the propagation of the event through any handler groups\n * in the current dispatcher. Does not prevent child dispatchers from\n * being executed.\n *\n * `StopChildren`: Stop the propagation of the event through any handler groups\n * in the current dispatcher, and any of its children. If current dispatcher\n * is a child, does not prevent from propagating to its siblings.\n *\n * `Continue`: Continue propagating the event inside the same handler group.\n *\n * `ToScene`: Used after using `state.enter()` to dispatch the update to the scene\n */\nexport enum PropagationAction {\n    Stop = 'stop',\n    StopChildren = 'stop-children',\n    Continue = 'continue',\n    ToScene = 'scene',\n}\n"]}

package/cjs/state/index.d.ts

@@ -0,0 +1,3 @@
+export * from './key.js';
+export * from './storage.js';
+export * from './update-state.js';

package/cjs/state/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./key.js"), exports);
+__exportStar(require("./storage.js"), exports);
+__exportStar(require("./update-state.js"), exports);
+//# sourceMappingURL=index.js.map

package/cjs/state/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/state/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2CAAwB;AACxB,+CAA4B;AAC5B,oDAAiC","sourcesContent":["export * from './key.js'\nexport * from './storage.js'\nexport * from './update-state.js'\n"]}

package/cjs/state/key.d.ts

@@ -0,0 +1,23 @@
+import { Chat, MaybeAsync, User } from '@mtcute/client';
+import { CallbackQueryContext, MessageContext } from '../context/index.js';
+/**
+ * Function that determines how the state key is derived.
+ *
+ * The key is additionally prefixed with current scene, if any.
+ *
+ * @param msg  Message or callback from which to derive the key
+ * @param scene  Current scene UID, or `null` if none
+ */
+export type StateKeyDelegate = (upd: MessageContext | CallbackQueryContext | User | Chat) => MaybeAsync<string | null>;
+/**
+ * Default state key delegate.
+ *
+ * Derives key as follows:
+ *  - If private chat, `msg.chat.id`
+ *  - If group chat, `msg.chat.id + '_' + msg.sender.id`
+ *  - If channel, `msg.chat.id`
+ *  - If non-inline callback query:
+ *    - If in private chat (i.e. `upd.chatType === 'user'`), `upd.user.id`
+ *    - If in group/channel/supergroup (i.e. `upd.chatType !== 'user'`), `upd.chatId + '_' + upd.user.id`
+ */
+export declare const defaultStateKeyDelegate: StateKeyDelegate;

package/cjs/state/key.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultStateKeyDelegate = void 0;
+const client_1 = require("@mtcute/client");
+/**
+ * Default state key delegate.
+ *
+ * Derives key as follows:
+ *  - If private chat, `msg.chat.id`
+ *  - If group chat, `msg.chat.id + '_' + msg.sender.id`
+ *  - If channel, `msg.chat.id`
+ *  - If non-inline callback query:
+ *    - If in private chat (i.e. `upd.chatType === 'user'`), `upd.user.id`
+ *    - If in group/channel/supergroup (i.e. `upd.chatType !== 'user'`), `upd.chatId + '_' + upd.user.id`
+ */
+const defaultStateKeyDelegate = (upd) => {
+    if ('type' in upd) {
+        // User | Chat
+        return String(upd.id);
+    }
+    if (upd._name === 'new_message') {
+        switch (upd.chat.chatType) {
+            case 'private':
+            case 'bot':
+            case 'channel':
+                return String(upd.chat.id);
+            case 'group':
+            case 'supergroup':
+            case 'gigagroup':
+                return `${upd.chat.id}_${upd.sender.id}`;
+            default:
+                (0, client_1.assertNever)(upd.chat.chatType);
+        }
+    }
+    if (upd._name === 'callback_query') {
+        if (upd.isInline)
+            return null;
+        if (upd.chatType === 'user')
+            return `${upd.user.id}`;
+        return `${upd.chatId}_${upd.user.id}`;
+    }
+    return null;
+};
+exports.defaultStateKeyDelegate = defaultStateKeyDelegate;
+//# sourceMappingURL=key.js.map

package/cjs/state/key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"key.js","sourceRoot":"","sources":["../../../src/state/key.ts"],"names":[],"mappings":";;;AAAA,2CAAoE;AAcpE;;;;;;;;;;GAUG;AACI,MAAM,uBAAuB,GAAqB,CAAC,GAAG,EAAiB,EAAE;IAC5E,IAAI,MAAM,IAAI,GAAG,EAAE;QACf,cAAc;QACd,OAAO,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;KACxB;IAED,IAAI,GAAG,CAAC,KAAK,KAAK,aAAa,EAAE;QAC7B,QAAQ,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE;YACvB,KAAK,SAAS,CAAC;YACf,KAAK,KAAK,CAAC;YACX,KAAK,SAAS;gBACV,OAAO,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;YAC9B,KAAK,OAAO,CAAC;YACb,KAAK,YAAY,CAAC;YAClB,KAAK,WAAW;gBACZ,OAAO,GAAG,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,CAAA;YAC5C;gBACI,IAAA,oBAAW,EAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;SACrC;KACJ;IAED,IAAI,GAAG,CAAC,KAAK,KAAK,gBAAgB,EAAE;QAChC,IAAI,GAAG,CAAC,QAAQ;YAAE,OAAO,IAAI,CAAA;QAC7B,IAAI,GAAG,CAAC,QAAQ,KAAK,MAAM;YAAE,OAAO,GAAG,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,CAAA;QAEpD,OAAO,GAAG,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,CAAA;KACxC;IAED,OAAO,IAAI,CAAA;AACf,CAAC,CAAA;AA7BY,QAAA,uBAAuB,2BA6BnC","sourcesContent":["import { assertNever, Chat, MaybeAsync, User } from '@mtcute/client'\n\nimport { CallbackQueryContext, MessageContext } from '../context/index.js'\n\n/**\n * Function that determines how the state key is derived.\n *\n * The key is additionally prefixed with current scene, if any.\n *\n * @param msg  Message or callback from which to derive the key\n * @param scene  Current scene UID, or `null` if none\n */\nexport type StateKeyDelegate = (upd: MessageContext | CallbackQueryContext | User | Chat) => MaybeAsync<string | null>\n\n/**\n * Default state key delegate.\n *\n * Derives key as follows:\n *  - If private chat, `msg.chat.id`\n *  - If group chat, `msg.chat.id + '_' + msg.sender.id`\n *  - If channel, `msg.chat.id`\n *  - If non-inline callback query:\n *    - If in private chat (i.e. `upd.chatType === 'user'`), `upd.user.id`\n *    - If in group/channel/supergroup (i.e. `upd.chatType !== 'user'`), `upd.chatId + '_' + upd.user.id`\n */\nexport const defaultStateKeyDelegate: StateKeyDelegate = (upd): string | null => {\n    if ('type' in upd) {\n        // User | Chat\n        return String(upd.id)\n    }\n\n    if (upd._name === 'new_message') {\n        switch (upd.chat.chatType) {\n            case 'private':\n            case 'bot':\n            case 'channel':\n                return String(upd.chat.id)\n            case 'group':\n            case 'supergroup':\n            case 'gigagroup':\n                return `${upd.chat.id}_${upd.sender.id}`\n            default:\n                assertNever(upd.chat.chatType)\n        }\n    }\n\n    if (upd._name === 'callback_query') {\n        if (upd.isInline) return null\n        if (upd.chatType === 'user') return `${upd.user.id}`\n\n        return `${upd.chatId}_${upd.user.id}`\n    }\n\n    return null\n}\n"]}

package/cjs/state/storage.d.ts

@@ -0,0 +1,75 @@
+import { MaybeAsync } from '@mtcute/client';
+/**
+ * Interface for FSM storage for the dispatcher.
+ *
+ * All of the officially supported storages already implement
+ * this interface, so you can just re-use it.
+ *
+ * Current scene is a special case of a `string` state,
+ * Most of the time you can just store it the same way
+ * as normal state, prefixing with something like `$current_state_`
+ * (scene name can't start with `$`).
+ * Alternatively, you can store them as simple strings
+ */
+export interface IStateStorage {
+    /**
+     * Retrieve state from the storage
+     *
+     * @param key  Key of the state, as defined by {@link StateKeyDelegate}
+     */
+    getState(key: string): MaybeAsync<unknown>;
+    /**
+     * Save state to the storage
+     *
+     * @param key  Key of the state, as defined by {@link StateKeyDelegate}
+     * @param state  Object representing the state
+     * @param ttl  TTL for the state, in seconds
+     */
+    setState(key: string, state: unknown, ttl?: number): MaybeAsync<void>;
+    /**
+     * Delete state from the storage
+     *
+     * @param key  Key of the state, as defined by {@link StateKeyDelegate}
+     */
+    deleteState(key: string): MaybeAsync<void>;
+    /**
+     * Retrieve the current scene UID from the storage
+     *
+     * @param key  Key of the state, as defined by {@link StateKeyDelegate}
+     */
+    getCurrentScene(key: string): MaybeAsync<string | null>;
+    /**
+     * Change current scene's UID from the storage
+     *
+     * @param key  Key of the state, as defined by {@link StateKeyDelegate}
+     * @param scene  New scene
+     * @param ttl  TTL for the scene, in seconds
+     */
+    setCurrentScene(key: string, scene: string, ttl?: number): MaybeAsync<void>;
+    /**
+     * Delete current scene from the storage, effectively "exiting" to root.
+     *
+     * @param key  Key of the state, as defined by {@link StateKeyDelegate}
+     */
+    deleteCurrentScene(key: string): MaybeAsync<void>;
+    /**
+     * Get information about a rate limit.
+     *
+     * It is recommended that you use sliding window or leaky bucket
+     * to implement rate limiting ([learn more](https://konghq.com/blog/how-to-design-a-scalable-rate-limiting-algorithm/)),
+     *
+     * @param key  Key of the rate limit
+     * @param limit  Maximum number of requests in `window`
+     * @param window  Window size in seconds
+     * @returns  Tuple containing the number of remaining and
+     *   unix time in ms when the user can try again
+     */
+    getRateLimit(key: string, limit: number, window: number): MaybeAsync<[number, number]>;
+    /**
+     * Reset a rate limit.
+     *
+     * @param key  Key of the rate limit
+     */
+    resetRateLimit(key: string): MaybeAsync<void>;
+}
+export declare function isCompatibleStorage(storage: unknown): storage is IStateStorage;

package/cjs/state/storage.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isCompatibleStorage = void 0;
+function isCompatibleStorage(storage) {
+    return (typeof storage === 'object' &&
+        storage !== null &&
+        'getState' in storage &&
+        'setState' in storage &&
+        'deleteState' in storage &&
+        'getCurrentScene' in storage &&
+        'setCurrentScene' in storage &&
+        'deleteCurrentScene' in storage &&
+        'getRateLimit' in storage &&
+        'resetRateLimit' in storage);
+}
+exports.isCompatibleStorage = isCompatibleStorage;
+//# sourceMappingURL=storage.js.map

package/cjs/state/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../../../src/state/storage.ts"],"names":[],"mappings":";;;AAmFA,SAAgB,mBAAmB,CAAC,OAAgB;IAChD,OAAO,CACH,OAAO,OAAO,KAAK,QAAQ;QAC3B,OAAO,KAAK,IAAI;QAChB,UAAU,IAAI,OAAO;QACrB,UAAU,IAAI,OAAO;QACrB,aAAa,IAAI,OAAO;QACxB,iBAAiB,IAAI,OAAO;QAC5B,iBAAiB,IAAI,OAAO;QAC5B,oBAAoB,IAAI,OAAO;QAC/B,cAAc,IAAI,OAAO;QACzB,gBAAgB,IAAI,OAAO,CAC9B,CAAA;AACL,CAAC;AAbD,kDAaC","sourcesContent":["import { MaybeAsync } from '@mtcute/client'\n\n/**\n * Interface for FSM storage for the dispatcher.\n *\n * All of the officially supported storages already implement\n * this interface, so you can just re-use it.\n *\n * Current scene is a special case of a `string` state,\n * Most of the time you can just store it the same way\n * as normal state, prefixing with something like `$current_state_`\n * (scene name can't start with `$`).\n * Alternatively, you can store them as simple strings\n */\nexport interface IStateStorage {\n    /**\n     * Retrieve state from the storage\n     *\n     * @param key  Key of the state, as defined by {@link StateKeyDelegate}\n     */\n    getState(key: string): MaybeAsync<unknown>\n\n    /**\n     * Save state to the storage\n     *\n     * @param key  Key of the state, as defined by {@link StateKeyDelegate}\n     * @param state  Object representing the state\n     * @param ttl  TTL for the state, in seconds\n     */\n    setState(key: string, state: unknown, ttl?: number): MaybeAsync<void>\n\n    /**\n     * Delete state from the storage\n     *\n     * @param key  Key of the state, as defined by {@link StateKeyDelegate}\n     */\n    deleteState(key: string): MaybeAsync<void>\n\n    /**\n     * Retrieve the current scene UID from the storage\n     *\n     * @param key  Key of the state, as defined by {@link StateKeyDelegate}\n     */\n    getCurrentScene(key: string): MaybeAsync<string | null>\n\n    /**\n     * Change current scene's UID from the storage\n     *\n     * @param key  Key of the state, as defined by {@link StateKeyDelegate}\n     * @param scene  New scene\n     * @param ttl  TTL for the scene, in seconds\n     */\n    setCurrentScene(key: string, scene: string, ttl?: number): MaybeAsync<void>\n\n    /**\n     * Delete current scene from the storage, effectively \"exiting\" to root.\n     *\n     * @param key  Key of the state, as defined by {@link StateKeyDelegate}\n     */\n    deleteCurrentScene(key: string): MaybeAsync<void>\n\n    /**\n     * Get information about a rate limit.\n     *\n     * It is recommended that you use sliding window or leaky bucket\n     * to implement rate limiting ([learn more](https://konghq.com/blog/how-to-design-a-scalable-rate-limiting-algorithm/)),\n     *\n     * @param key  Key of the rate limit\n     * @param limit  Maximum number of requests in `window`\n     * @param window  Window size in seconds\n     * @returns  Tuple containing the number of remaining and\n     *   unix time in ms when the user can try again\n     */\n    getRateLimit(key: string, limit: number, window: number): MaybeAsync<[number, number]>\n\n    /**\n     * Reset a rate limit.\n     *\n     * @param key  Key of the rate limit\n     */\n    resetRateLimit(key: string): MaybeAsync<void>\n}\n\nexport function isCompatibleStorage(storage: unknown): storage is IStateStorage {\n    return (\n        typeof storage === 'object' &&\n        storage !== null &&\n        'getState' in storage &&\n        'setState' in storage &&\n        'deleteState' in storage &&\n        'getCurrentScene' in storage &&\n        'setCurrentScene' in storage &&\n        'deleteCurrentScene' in storage &&\n        'getRateLimit' in storage &&\n        'resetRateLimit' in storage\n    )\n}\n"]}

package/cjs/state/update-state.d.ts

@@ -0,0 +1,151 @@
+import { MtcuteError } from '@mtcute/client';
+import type { Dispatcher } from '../dispatcher.js';
+import { IStateStorage } from './storage.js';
+/**
+ * Error thrown by `.rateLimit()`
+ */
+export declare class RateLimitError extends MtcuteError {
+    readonly reset: number;
+    constructor(reset: number);
+}
+/**
+ * State of the current update.
+ *
+ * @template State  Type that represents the state
+ * @template SceneName  Possible scene names
+ */
+export declare class UpdateState<State extends object> {
+    private _key;
+    private _localKey;
+    private _storage;
+    private _scene;
+    private _scoped?;
+    private _cached?;
+    private _localStorage;
+    private _localKeyBase;
+    constructor(storage: IStateStorage, key: string, scene: string | null, scoped?: boolean, customStorage?: IStateStorage, customKey?: string);
+    /** Name of the current scene */
+    get scene(): string | null;
+    private _updateLocalKey;
+    /**
+     * Retrieve the state from the storage, falling back to default
+     * if not found
+     *
+     * @param fallback  Default state value
+     * @param force  Whether to ignore cached state (def. `false`)
+     */
+    get(fallback: State | (() => State), force?: boolean): Promise<State>;
+    /**
+     * Retrieve the state from the storage, falling back to default
+     * if not found
+     *
+     * @param fallback  Default state value
+     * @param force  Whether to ignore cached state (def. `false`)
+     */
+    get(fallback?: State | (() => State), force?: boolean): Promise<State | null>;
+    /**
+     * Retrieve the state from the storage
+     *
+     * @param force  Whether to ignore cached state (def. `false`)
+     */
+    get(force?: boolean): Promise<State | null>;
+    /**
+     * Set new state to the storage
+     *
+     * @param state  New state
+     * @param ttl  TTL for the new state (in seconds)
+     */
+    set(state: State, ttl?: number): Promise<void>;
+    /**
+     * Merge the given object to the current state.
+     *
+     * > **Note**: If the storage currently has no state,
+     * > then `fallback` must be provided.
+     *
+     * Basically a shorthand to calling `.get()`,
+     * modifying and then calling `.set()`
+     *
+     * @param state  State to be merged
+     * @param fallback  Default state
+     * @param ttl  TTL for the new state (in seconds)
+     * @param forceLoad  Whether to force load the old state from storage
+     */
+    merge(state: Partial<State>, params?: {
+        fallback?: State | (() => State);
+        ttl?: number;
+        forceLoad?: boolean;
+    }): Promise<State>;
+    /**
+     * Delete the state from the storage
+     */
+    delete(): Promise<void>;
+    /**
+     * Enter some scene
+     */
+    enter<SceneState extends object, Scene extends Dispatcher<SceneState>>(scene: Scene, params?: {
+        /**
+         * Initial state for the scene
+         *
+         * Note that this will only work if the scene uses the same key delegate as this state.
+         */
+        with?: SceneState;
+        /** TTL for the scene (in seconds) */
+        ttl?: number;
+        /**
+         * If currently in a scoped scene, whether to reset the state
+         *
+         * @default  true
+         */
+        reset?: boolean;
+    }): Promise<void>;
+    /**
+     * Exit from current scene to the root
+     *
+     * @param reset
+     *     Whether to reset scene state (only applicable in case this is a scoped scene)
+     */
+    exit(reset?: boolean): Promise<void>;
+    /**
+     * Rate limit some handler.
+     *
+     * When the rate limit exceeds, {@link RateLimitError} is thrown.
+     *
+     * This is a simple rate-limiting solution that uses
+     * the same key as the state. If you need something more
+     * sophisticated and/or customizable, you'll have to implement
+     * your own rate-limiter.
+     *
+     * > **Note**: `key` is used to prefix the local key
+     * > derived using the given key delegate.
+     *
+     * @param key  Key of the rate limit
+     * @param limit  Maximum number of requests in `window`
+     * @param window  Window size in seconds
+     * @returns  Tuple containing the number of remaining and
+     *   unix time in ms when the user can try again
+     */
+    rateLimit(key: string, limit: number, window: number): Promise<[number, number]>;
+    /**
+     * Throttle some handler.
+     *
+     * When the rate limit exceeds, this function waits for it to reset.
+     *
+     * This is a simple wrapper over {@link rateLimit}, and follows the same logic.
+     *
+     * > **Note**: `key` is used to prefix the local key
+     * > derived using the given key delegate.
+     *
+     * @param key  Key of the rate limit
+     * @param limit  Maximum number of requests in `window`
+     * @param window  Window size in seconds
+     * @returns  Tuple containing the number of remaining and
+     *   unix time in ms when the user can try again
+     */
+    throttle(key: string, limit: number, window: number): Promise<[number, number]>;
+    /**
+     * Reset the rate limit
+     *
+     * @param key  Key of the rate limit
+     */
+    resetRateLimit(key: string): Promise<void>;
+}