@mtcute/dispatcher 0.17.2 → 0.18.0

package/package.json

@@ -1,11 +1,15 @@
 {
     "name": "@mtcute/dispatcher",
     "type": "module",
-    "version": "0.17.2",
+    "version": "0.18.0",
     "description": "Updates dispatcher and bot framework for @mtcute/client",
-    "author": "alina sireneva <alina@tei.su>",
     "license": "MIT",
-    "sideEffects": false,
+    "scripts": {},
+    "dependencies": {
+        "@mtcute/core": "^0.18.0",
+        "@fuman/utils": "0.0.4",
+        "events": "3.2.0"
+    },
     "exports": {
         ".": {
             "import": {
@@ -18,14 +22,11 @@
             }
         }
     },
-    "scripts": {},
-    "dependencies": {
-        "@mtcute/core": "^0.17.1",
-        "events": "3.2.0"
-    },
+    "author": "alina sireneva <alina@tei.su>",
+    "sideEffects": false,
     "homepage": "https://mtcute.dev",
     "repository": {
         "type": "git",
-        "url": "https://github.com/mtcute/mtcute"
+        "url": "git+https://github.com/mtcute/mtcute.git"
     }
 }

package/propagation.cjs

@@ -0,0 +1,15 @@
+if (typeof globalThis !== "undefined" && !globalThis._MTCUTE_CJS_DEPRECATION_WARNED) {
+  globalThis._MTCUTE_CJS_DEPRECATION_WARNED = true;
+  console.warn("[mtcute-workspace] CommonJS support is deprecated and will be removed in 0.20.0. Please consider switching to ESM, it's " + (/* @__PURE__ */ new Date()).getFullYear() + " already.");
+  console.warn("[mtcute-workspace] Learn more about switching to ESM: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c");
+}
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+var PropagationAction = /* @__PURE__ */ ((PropagationAction2) => {
+  PropagationAction2["Stop"] = "stop";
+  PropagationAction2["StopChildren"] = "stop-children";
+  PropagationAction2["Continue"] = "continue";
+  PropagationAction2["ToScene"] = "scene";
+  return PropagationAction2;
+})(PropagationAction || {});
+exports.PropagationAction = PropagationAction;

package/propagation.d.cts

@@ -0,0 +1,22 @@
+/**
+ * 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,
+ * or after `state.exit()` to dispatch the update to the root dispatcher.
+ */
+export declare enum PropagationAction {
+    Stop = "stop",
+    StopChildren = "stop-children",
+    Continue = "continue",
+    ToScene = "scene"
+}

package/propagation.js

@@ -0,0 +1,10 @@
+var PropagationAction = /* @__PURE__ */ ((PropagationAction2) => {
+  PropagationAction2["Stop"] = "stop";
+  PropagationAction2["StopChildren"] = "stop-children";
+  PropagationAction2["Continue"] = "continue";
+  PropagationAction2["ToScene"] = "scene";
+  return PropagationAction2;
+})(PropagationAction || {});
+export {
+  PropagationAction
+};

package/state/index.d.cts

@@ -0,0 +1,5 @@
+export * from './key.js';
+export * from './provider.js';
+export * from './providers/index.js';
+export * from './repository.js';
+export * from './update-state.js';

package/state/key.cjs

@@ -0,0 +1,32 @@
+if (typeof globalThis !== "undefined" && !globalThis._MTCUTE_CJS_DEPRECATION_WARNED) {
+  globalThis._MTCUTE_CJS_DEPRECATION_WARNED = true;
+  console.warn("[mtcute-workspace] CommonJS support is deprecated and will be removed in 0.20.0. Please consider switching to ESM, it's " + (/* @__PURE__ */ new Date()).getFullYear() + " already.");
+  console.warn("[mtcute-workspace] Learn more about switching to ESM: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c");
+}
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const core = require("@mtcute/core");
+const defaultStateKeyDelegate = (upd) => {
+  if ("type" in upd) {
+    return String(upd.id);
+  }
+  if (upd._name === "new_message" || upd._name === "new_business_message") {
+    if (upd.chat.type === "user") return String(upd.chat.id);
+    switch (upd.chat.chatType) {
+      case "channel":
+        return String(upd.chat.id);
+      case "group":
+      case "supergroup":
+      case "gigagroup":
+        return `${upd.chat.id}_${upd.sender.id}`;
+      default:
+        core.assertNever(upd.chat.chatType);
+    }
+  }
+  if (upd._name === "callback_query") {
+    if (upd.chat.type === "user") return `${upd.user.id}`;
+    return `${upd.chat.id}_${upd.user.id}`;
+  }
+  return null;
+};
+exports.defaultStateKeyDelegate = defaultStateKeyDelegate;

package/state/key.d.cts

@@ -0,0 +1,24 @@
+import { MaybePromise, Peer } from '@mtcute/core';
+import { BusinessMessageContext } from '../context/business-message.js';
+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 | BusinessMessageContext | CallbackQueryContext | Peer) => MaybePromise<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/state/key.js

@@ -0,0 +1,27 @@
+import { assertNever } from "@mtcute/core";
+const defaultStateKeyDelegate = (upd) => {
+  if ("type" in upd) {
+    return String(upd.id);
+  }
+  if (upd._name === "new_message" || upd._name === "new_business_message") {
+    if (upd.chat.type === "user") return String(upd.chat.id);
+    switch (upd.chat.chatType) {
+      case "channel":
+        return String(upd.chat.id);
+      case "group":
+      case "supergroup":
+      case "gigagroup":
+        return `${upd.chat.id}_${upd.sender.id}`;
+      default:
+        assertNever(upd.chat.chatType);
+    }
+  }
+  if (upd._name === "callback_query") {
+    if (upd.chat.type === "user") return `${upd.user.id}`;
+    return `${upd.chat.id}_${upd.user.id}`;
+  }
+  return null;
+};
+export {
+  defaultStateKeyDelegate
+};

package/state/provider.d.cts

@@ -0,0 +1,5 @@
+import { IStorageProvider } from '@mtcute/core';
+import { IStateRepository } from './repository.js';
+export type IStateStorageProvider = IStorageProvider<{
+    state: IStateRepository;
+}>;

package/state/providers/index.d.cts

@@ -0,0 +1,2 @@
+export * from './memory.js';
+export * from './sqlite.js';

package/state/providers/memory.cjs

@@ -0,0 +1,79 @@
+if (typeof globalThis !== "undefined" && !globalThis._MTCUTE_CJS_DEPRECATION_WARNED) {
+  globalThis._MTCUTE_CJS_DEPRECATION_WARNED = true;
+  console.warn("[mtcute-workspace] CommonJS support is deprecated and will be removed in 0.20.0. Please consider switching to ESM, it's " + (/* @__PURE__ */ new Date()).getFullYear() + " already.");
+  console.warn("[mtcute-workspace] Learn more about switching to ESM: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c");
+}
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const core = require("@mtcute/core");
+class MemoryStateRepository {
+  constructor(_driver) {
+    this._driver = _driver;
+    this.state = this._driver.getState("dispatcher_fsm", () => /* @__PURE__ */ new Map());
+    this.rl = this._driver.getState("rl", () => /* @__PURE__ */ new Map());
+  }
+  state;
+  rl;
+  setState(key, state, ttl) {
+    this.state.set(key, {
+      value: state,
+      expiresAt: ttl ? Date.now() + ttl * 1e3 : void 0
+    });
+  }
+  getState(key, now) {
+    const state = this.state.get(key);
+    if (!state) return null;
+    if (state.expiresAt && state.expiresAt < now) {
+      this.state.delete(key);
+      return null;
+    }
+    return state.value;
+  }
+  deleteState(key) {
+    this.state.delete(key);
+  }
+  vacuum(now) {
+    for (const [key, state] of this.state.entries()) {
+      if (state.expiresAt && state.expiresAt < now) {
+        this.state.delete(key);
+      }
+    }
+    for (const [key, state] of this.rl.entries()) {
+      if (state.reset < now) {
+        this.rl.delete(key);
+      }
+    }
+  }
+  getRateLimit(key, now, limit, window) {
+    const item = this.rl.get(key);
+    if (!item) {
+      const state = {
+        reset: now + window * 1e3,
+        remaining: limit
+      };
+      this.rl.set(key, state);
+      return [state.remaining, state.reset];
+    }
+    if (item.reset < now) {
+      const state = {
+        reset: now + window * 1e3,
+        remaining: limit
+      };
+      this.rl.set(key, state);
+      return [state.remaining, state.reset];
+    }
+    item.remaining = item.remaining > 0 ? item.remaining - 1 : 0;
+    return [item.remaining, item.reset];
+  }
+  resetRateLimit(key) {
+    this.rl.delete(key);
+  }
+}
+class MemoryStateStorage {
+  constructor(driver = new core.MemoryStorageDriver()) {
+    this.driver = driver;
+    this.state = new MemoryStateRepository(this.driver);
+  }
+  state;
+}
+exports.MemoryStateStorage = MemoryStateStorage;

package/state/providers/memory.d.cts

@@ -0,0 +1,29 @@
+import { MaybePromise, MemoryStorageDriver } from '@mtcute/core';
+import { IStateStorageProvider } from '../provider.js';
+import { IStateRepository } from '../repository.js';
+interface StateDto {
+    value: string;
+    expiresAt?: number;
+}
+interface RateLimitDto {
+    reset: number;
+    remaining: number;
+}
+declare class MemoryStateRepository implements IStateRepository {
+    readonly _driver: MemoryStorageDriver;
+    readonly state: Map<string, StateDto>;
+    readonly rl: Map<string, RateLimitDto>;
+    constructor(_driver: MemoryStorageDriver);
+    setState(key: string, state: string, ttl?: number | undefined): void;
+    getState(key: string, now: number): string | null;
+    deleteState(key: string): void;
+    vacuum(now: number): void;
+    getRateLimit(key: string, now: number, limit: number, window: number): [number, number];
+    resetRateLimit(key: string): MaybePromise<void>;
+}
+export declare class MemoryStateStorage implements IStateStorageProvider {
+    readonly driver: MemoryStorageDriver;
+    readonly state: MemoryStateRepository;
+    constructor(driver?: MemoryStorageDriver);
+}
+export {};

package/state/providers/memory.js

@@ -0,0 +1,74 @@
+import { MemoryStorageDriver } from "@mtcute/core";
+class MemoryStateRepository {
+  constructor(_driver) {
+    this._driver = _driver;
+    this.state = this._driver.getState("dispatcher_fsm", () => /* @__PURE__ */ new Map());
+    this.rl = this._driver.getState("rl", () => /* @__PURE__ */ new Map());
+  }
+  state;
+  rl;
+  setState(key, state, ttl) {
+    this.state.set(key, {
+      value: state,
+      expiresAt: ttl ? Date.now() + ttl * 1e3 : void 0
+    });
+  }
+  getState(key, now) {
+    const state = this.state.get(key);
+    if (!state) return null;
+    if (state.expiresAt && state.expiresAt < now) {
+      this.state.delete(key);
+      return null;
+    }
+    return state.value;
+  }
+  deleteState(key) {
+    this.state.delete(key);
+  }
+  vacuum(now) {
+    for (const [key, state] of this.state.entries()) {
+      if (state.expiresAt && state.expiresAt < now) {
+        this.state.delete(key);
+      }
+    }
+    for (const [key, state] of this.rl.entries()) {
+      if (state.reset < now) {
+        this.rl.delete(key);
+      }
+    }
+  }
+  getRateLimit(key, now, limit, window) {
+    const item = this.rl.get(key);
+    if (!item) {
+      const state = {
+        reset: now + window * 1e3,
+        remaining: limit
+      };
+      this.rl.set(key, state);
+      return [state.remaining, state.reset];
+    }
+    if (item.reset < now) {
+      const state = {
+        reset: now + window * 1e3,
+        remaining: limit
+      };
+      this.rl.set(key, state);
+      return [state.remaining, state.reset];
+    }
+    item.remaining = item.remaining > 0 ? item.remaining - 1 : 0;
+    return [item.remaining, item.reset];
+  }
+  resetRateLimit(key) {
+    this.rl.delete(key);
+  }
+}
+class MemoryStateStorage {
+  constructor(driver = new MemoryStorageDriver()) {
+    this.driver = driver;
+    this.state = new MemoryStateRepository(this.driver);
+  }
+  state;
+}
+export {
+  MemoryStateStorage
+};

package/state/providers/sqlite.cjs

@@ -0,0 +1,99 @@
+if (typeof globalThis !== "undefined" && !globalThis._MTCUTE_CJS_DEPRECATION_WARNED) {
+  globalThis._MTCUTE_CJS_DEPRECATION_WARNED = true;
+  console.warn("[mtcute-workspace] CommonJS support is deprecated and will be removed in 0.20.0. Please consider switching to ESM, it's " + (/* @__PURE__ */ new Date()).getFullYear() + " already.");
+  console.warn("[mtcute-workspace] Learn more about switching to ESM: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c");
+}
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+class SqliteStateRepository {
+  constructor(_driver) {
+    this._driver = _driver;
+    _driver.registerMigration("state", 1, (db) => {
+      db.exec(`
+                create table fsm_state (
+                    key text primary key,
+                    value text not null,
+                    expires_at integer
+                );
+                create table rl_state (
+                    key text primary key,
+                    reset integer not null,
+                    remaining integer not null
+                );
+            `);
+    });
+    _driver.onLoad(() => {
+      this._setState = _driver.db.prepare(
+        "insert or replace into fsm_state (key, value, expires_at) values (?, ?, ?)"
+      );
+      this._getState = _driver.db.prepare("select value, expires_at from fsm_state where key = ?");
+      this._deleteState = _driver.db.prepare("delete from fsm_state where key = ?");
+      this._deleteOldState = _driver.db.prepare("delete from fsm_state where expires_at < ?");
+      this._setRl = _driver.db.prepare("insert or replace into rl_state (key, reset, remaining) values (?, ?, ?)");
+      this._getRl = _driver.db.prepare("select reset, remaining from rl_state where key = ?");
+      this._deleteRl = _driver.db.prepare("delete from rl_state where key = ?");
+      this._deleteOldRl = _driver.db.prepare("delete from rl_state where reset < ?");
+    });
+    _driver.registerLegacyMigration("state", (db) => {
+      db.exec("drop table state");
+    });
+  }
+  _setState;
+  setState(key, state, ttl) {
+    this._setState.run(key, state, ttl ? Date.now() + ttl * 1e3 : void 0);
+  }
+  _getState;
+  getState(key, now) {
+    const res_ = this._getState.get(key);
+    if (!res_) return null;
+    const res = res_;
+    if (res.expires_at && res.expires_at < now) {
+      this._deleteState.run(key);
+      return null;
+    }
+    return res.value;
+  }
+  _deleteState;
+  deleteState(key) {
+    this._deleteState.run(key);
+  }
+  _deleteOldState;
+  _deleteOldRl;
+  vacuum(now) {
+    this._deleteOldState.run(now);
+    this._deleteOldRl.run(now);
+  }
+  _setRl;
+  _getRl;
+  _deleteRl;
+  getRateLimit(key, now, limit, window) {
+    const val = this._getRl.get(key);
+    if (!val || val.reset < now) {
+      const item = {
+        reset: now + window * 1e3,
+        remaining: limit
+      };
+      this._setRl.run(key, item.reset, item.remaining);
+      return [item.remaining, item.reset];
+    }
+    if (val.remaining > 0) {
+      val.remaining -= 1;
+      this._setRl.run(key, val.reset, val.remaining);
+    }
+    return [val.remaining, val.reset];
+  }
+  resetRateLimit(key) {
+    this._deleteRl.run(key);
+  }
+}
+class SqliteStateStorage {
+  constructor(driver) {
+    this.driver = driver;
+    this.state = new SqliteStateRepository(driver);
+  }
+  state;
+  static from(provider) {
+    return new SqliteStateStorage(provider.driver);
+  }
+}
+exports.SqliteStateStorage = SqliteStateStorage;

package/state/providers/sqlite.d.cts

@@ -0,0 +1,28 @@
+import { BaseSqliteStorage, BaseSqliteStorageDriver, MaybePromise } from '@mtcute/core';
+import { IStateStorageProvider } from '../provider.js';
+import { IStateRepository } from '../repository.js';
+declare class SqliteStateRepository implements IStateRepository {
+    readonly _driver: BaseSqliteStorageDriver;
+    constructor(_driver: BaseSqliteStorageDriver);
+    private _setState;
+    setState(key: string, state: string, ttl?: number | undefined): MaybePromise<void>;
+    private _getState;
+    getState(key: string, now: number): MaybePromise<string | null>;
+    private _deleteState;
+    deleteState(key: string): MaybePromise<void>;
+    private _deleteOldState;
+    private _deleteOldRl;
+    vacuum(now: number): MaybePromise<void>;
+    private _setRl;
+    private _getRl;
+    private _deleteRl;
+    getRateLimit(key: string, now: number, limit: number, window: number): [number, number];
+    resetRateLimit(key: string): MaybePromise<void>;
+}
+export declare class SqliteStateStorage implements IStateStorageProvider {
+    readonly driver: BaseSqliteStorageDriver;
+    readonly state: SqliteStateRepository;
+    constructor(driver: BaseSqliteStorageDriver);
+    static from(provider: BaseSqliteStorage): SqliteStateStorage;
+}
+export {};

package/state/providers/sqlite.js

@@ -0,0 +1,94 @@
+class SqliteStateRepository {
+  constructor(_driver) {
+    this._driver = _driver;
+    _driver.registerMigration("state", 1, (db) => {
+      db.exec(`
+                create table fsm_state (
+                    key text primary key,
+                    value text not null,
+                    expires_at integer
+                );
+                create table rl_state (
+                    key text primary key,
+                    reset integer not null,
+                    remaining integer not null
+                );
+            `);
+    });
+    _driver.onLoad(() => {
+      this._setState = _driver.db.prepare(
+        "insert or replace into fsm_state (key, value, expires_at) values (?, ?, ?)"
+      );
+      this._getState = _driver.db.prepare("select value, expires_at from fsm_state where key = ?");
+      this._deleteState = _driver.db.prepare("delete from fsm_state where key = ?");
+      this._deleteOldState = _driver.db.prepare("delete from fsm_state where expires_at < ?");
+      this._setRl = _driver.db.prepare("insert or replace into rl_state (key, reset, remaining) values (?, ?, ?)");
+      this._getRl = _driver.db.prepare("select reset, remaining from rl_state where key = ?");
+      this._deleteRl = _driver.db.prepare("delete from rl_state where key = ?");
+      this._deleteOldRl = _driver.db.prepare("delete from rl_state where reset < ?");
+    });
+    _driver.registerLegacyMigration("state", (db) => {
+      db.exec("drop table state");
+    });
+  }
+  _setState;
+  setState(key, state, ttl) {
+    this._setState.run(key, state, ttl ? Date.now() + ttl * 1e3 : void 0);
+  }
+  _getState;
+  getState(key, now) {
+    const res_ = this._getState.get(key);
+    if (!res_) return null;
+    const res = res_;
+    if (res.expires_at && res.expires_at < now) {
+      this._deleteState.run(key);
+      return null;
+    }
+    return res.value;
+  }
+  _deleteState;
+  deleteState(key) {
+    this._deleteState.run(key);
+  }
+  _deleteOldState;
+  _deleteOldRl;
+  vacuum(now) {
+    this._deleteOldState.run(now);
+    this._deleteOldRl.run(now);
+  }
+  _setRl;
+  _getRl;
+  _deleteRl;
+  getRateLimit(key, now, limit, window) {
+    const val = this._getRl.get(key);
+    if (!val || val.reset < now) {
+      const item = {
+        reset: now + window * 1e3,
+        remaining: limit
+      };
+      this._setRl.run(key, item.reset, item.remaining);
+      return [item.remaining, item.reset];
+    }
+    if (val.remaining > 0) {
+      val.remaining -= 1;
+      this._setRl.run(key, val.reset, val.remaining);
+    }
+    return [val.remaining, val.reset];
+  }
+  resetRateLimit(key) {
+    this._deleteRl.run(key);
+  }
+}
+class SqliteStateStorage {
+  constructor(driver) {
+    this.driver = driver;
+    this.state = new SqliteStateRepository(driver);
+  }
+  state;
+  static from(provider) {
+    return new SqliteStateStorage(provider.driver);
+  }
+}
+export {
+  SqliteStateStorage
+};

package/state/repository.d.cts

@@ -0,0 +1,62 @@
+import { MaybePromise } from '@mtcute/core';
+/**
+ * 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 IStateRepository {
+    /**
+     * Retrieve state from the storage
+     * If state is not found or has expired, return `null`
+     *
+     * @param key  Key of the state, as defined by {@link StateKeyDelegate}
+     */
+    getState: (key: string, now: number) => MaybePromise<string | null>;
+    /**
+     * Save state to the storage
+     *
+     * @param key  Key of the state, as defined by {@link StateKeyDelegate}
+     * @param state  String representing the state
+     * @param ttl  TTL for the state, in seconds
+     */
+    setState: (key: string, state: string, ttl?: number) => MaybePromise<void>;
+    /**
+     * Delete state from the storage
+     *
+     * @param key  Key of the state, as defined by {@link StateKeyDelegate}
+     */
+    deleteState: (key: string) => MaybePromise<void>;
+    /**
+     * Clean up expired states and rate limits.
+     *
+     * @param now  Current unix time in ms
+     */
+    vacuum: (now: number) => MaybePromise<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 now  Current unix time in ms
+     * @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, now: number, limit: number, window: number) => MaybePromise<[number, number]>;
+    /**
+     * Reset a rate limit.
+     *
+     * @param key  Key of the rate limit
+     */
+    resetRateLimit: (key: string) => MaybePromise<void>;
+}