@mtcute/dispatcher 0.17.2 → 0.18.0

package/state/service.cjs

@@ -0,0 +1,69 @@
+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 utils = require("@fuman/utils");
+const utils_js = require("@mtcute/core/utils.js");
+const makeCurrentSceneKey = (key) => `$current_scene_${key}`;
+class StateService {
+  constructor(provider) {
+    this.provider = provider;
+  }
+  _cache = new utils.LruMap(100);
+  _vacuumTimer;
+  _loaded = false;
+  _load = utils_js.asyncResettable(async () => {
+    await this.provider.driver.load?.();
+    this._loaded = true;
+  });
+  async load() {
+    await this._load.run();
+    this._vacuumTimer = utils.timers.setInterval(() => {
+      Promise.resolve(this.provider.state.vacuum(Date.now())).catch(() => {
+      });
+    }, 3e5);
+  }
+  async destroy() {
+    await this.provider.driver.save?.();
+    await this.provider.driver.destroy?.();
+    utils.timers.clearInterval(this._vacuumTimer);
+    this._loaded = false;
+  }
+  async getState(key) {
+    if (!this._loaded) await this.load();
+    const cached = this._cache.get(key);
+    if (cached) return cached;
+    const state = await this.provider.state.getState(key, Date.now());
+    if (!state) return null;
+    return JSON.parse(state);
+  }
+  async setState(key, state, ttl) {
+    if (!this._loaded) await this.load();
+    this._cache.set(key, state);
+    await this.provider.state.setState(key, JSON.stringify(state), ttl);
+  }
+  async deleteState(key) {
+    if (!this._loaded) await this.load();
+    this._cache.delete(key);
+    await this.provider.state.deleteState(key);
+  }
+  getCurrentScene(key) {
+    return this.getState(makeCurrentSceneKey(key));
+  }
+  setCurrentScene(key, scene, ttl) {
+    return this.setState(makeCurrentSceneKey(key), scene, ttl);
+  }
+  deleteCurrentScene(key) {
+    return this.deleteState(makeCurrentSceneKey(key));
+  }
+  getRateLimit(key, limit, window) {
+    return this.provider.state.getRateLimit(key, Date.now(), limit, window);
+  }
+  resetRateLimit(key) {
+    return this.provider.state.resetRateLimit(key);
+  }
+}
+exports.StateService = StateService;

package/state/service.d.cts

@@ -0,0 +1,20 @@
+import { MaybePromise } from '@mtcute/core';
+import { IStateStorageProvider } from './provider.js';
+export declare class StateService {
+    readonly provider: IStateStorageProvider;
+    constructor(provider: IStateStorageProvider);
+    private _cache;
+    private _vacuumTimer?;
+    private _loaded;
+    private _load;
+    load(): Promise<void>;
+    destroy(): Promise<void>;
+    getState<T>(key: string): Promise<T | null>;
+    setState<T>(key: string, state: T, ttl?: number): Promise<void>;
+    deleteState(key: string): Promise<void>;
+    getCurrentScene(key: string): Promise<string | null>;
+    setCurrentScene(key: string, scene: string, ttl?: number): Promise<void>;
+    deleteCurrentScene(key: string): Promise<void>;
+    getRateLimit(key: string, limit: number, window: number): MaybePromise<[number, number]>;
+    resetRateLimit(key: string): MaybePromise<void>;
+}

package/state/service.js

@@ -0,0 +1,64 @@
+import { LruMap, timers } from "@fuman/utils";
+import { asyncResettable } from "@mtcute/core/utils.js";
+const makeCurrentSceneKey = (key) => `$current_scene_${key}`;
+class StateService {
+  constructor(provider) {
+    this.provider = provider;
+  }
+  _cache = new LruMap(100);
+  _vacuumTimer;
+  _loaded = false;
+  _load = asyncResettable(async () => {
+    await this.provider.driver.load?.();
+    this._loaded = true;
+  });
+  async load() {
+    await this._load.run();
+    this._vacuumTimer = timers.setInterval(() => {
+      Promise.resolve(this.provider.state.vacuum(Date.now())).catch(() => {
+      });
+    }, 3e5);
+  }
+  async destroy() {
+    await this.provider.driver.save?.();
+    await this.provider.driver.destroy?.();
+    timers.clearInterval(this._vacuumTimer);
+    this._loaded = false;
+  }
+  async getState(key) {
+    if (!this._loaded) await this.load();
+    const cached = this._cache.get(key);
+    if (cached) return cached;
+    const state = await this.provider.state.getState(key, Date.now());
+    if (!state) return null;
+    return JSON.parse(state);
+  }
+  async setState(key, state, ttl) {
+    if (!this._loaded) await this.load();
+    this._cache.set(key, state);
+    await this.provider.state.setState(key, JSON.stringify(state), ttl);
+  }
+  async deleteState(key) {
+    if (!this._loaded) await this.load();
+    this._cache.delete(key);
+    await this.provider.state.deleteState(key);
+  }
+  getCurrentScene(key) {
+    return this.getState(makeCurrentSceneKey(key));
+  }
+  setCurrentScene(key, scene, ttl) {
+    return this.setState(makeCurrentSceneKey(key), scene, ttl);
+  }
+  deleteCurrentScene(key) {
+    return this.deleteState(makeCurrentSceneKey(key));
+  }
+  getRateLimit(key, limit, window) {
+    return this.provider.state.getRateLimit(key, Date.now(), limit, window);
+  }
+  resetRateLimit(key) {
+    return this.provider.state.resetRateLimit(key);
+  }
+}
+export {
+  StateService
+};

package/state/update-state.cjs

@@ -0,0 +1,206 @@
+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 utils = require("@fuman/utils");
+const core = require("@mtcute/core");
+class RateLimitError extends core.MtcuteError {
+  constructor(reset) {
+    super("You are being rate limited.");
+    this.reset = reset;
+  }
+}
+class UpdateState {
+  _key;
+  _localKey;
+  _storage;
+  _scene;
+  _scoped;
+  _cached;
+  _localStorage;
+  _localKeyBase;
+  constructor(storage, key, scene, scoped, customStorage, customKey) {
+    this._storage = storage;
+    this._key = key;
+    this._scene = scene;
+    this._scoped = scoped;
+    this._localStorage = customStorage ?? storage;
+    this._localKeyBase = customKey ?? key;
+    this._updateLocalKey();
+  }
+  /** Name of the current scene */
+  get scene() {
+    return this._scene;
+  }
+  _updateLocalKey() {
+    if (!this._scoped) {
+      this._localKey = this._localKeyBase;
+    } else {
+      this._localKey = this._scene ? `${this._scene}_${this._localKeyBase}` : this._localKeyBase;
+    }
+  }
+  async get(fallback, force) {
+    if (typeof fallback === "boolean") {
+      force = fallback;
+      fallback = void 0;
+    }
+    if (!force && this._cached !== void 0) {
+      if (!this._cached && fallback) {
+        return typeof fallback === "function" ? fallback() : fallback;
+      }
+      return this._cached;
+    }
+    let res = await this._localStorage.getState(this._localKey);
+    if (!res && fallback) {
+      res = typeof fallback === "function" ? fallback() : fallback;
+    }
+    this._cached = res;
+    return res;
+  }
+  /**
+   * Set new state to the storage
+   *
+   * @param state  New state
+   * @param ttl  TTL for the new state (in seconds)
+   */
+  async set(state, ttl) {
+    this._cached = state;
+    await this._localStorage.setState(this._localKey, state, ttl);
+  }
+  /**
+   * 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
+   */
+  async merge(state, params = {}) {
+    const { fallback, ttl, forceLoad } = params;
+    const old = await this.get(forceLoad);
+    if (!old) {
+      if (!fallback) {
+        throw new core.MtArgumentError("Cannot use merge on empty state without fallback.");
+      }
+      const fallback_ = typeof fallback === "function" ? fallback() : fallback;
+      await this.set({ ...fallback_, ...state }, ttl);
+    } else {
+      await this.set({ ...old, ...state }, ttl);
+    }
+    return this._cached;
+  }
+  /**
+   * Delete the state from the storage
+   */
+  async delete() {
+    this._cached = null;
+    await this._localStorage.deleteState(this._localKey);
+  }
+  /**
+   * Enter some scene
+   */
+  async enter(scene, params) {
+    const { with: with_, ttl, reset = true } = params ?? {};
+    if (reset && this._scoped) await this.delete();
+    if (!scene["_scene"]) {
+      throw new core.MtArgumentError("Cannot enter a non-scene Dispatcher");
+    }
+    if (!scene["_parent"]) {
+      throw new core.MtArgumentError("This scene has not been registered");
+    }
+    this._scene = scene["_scene"];
+    this._scoped = scene["_sceneScoped"];
+    this._updateLocalKey();
+    await this._storage.setCurrentScene(this._key, this._scene, ttl);
+    if (with_) {
+      if (scene["_customStateKeyDelegate"]) {
+        throw new core.MtArgumentError("Cannot use `with` parameter when the scene uses a custom state key delegate");
+      }
+      await scene.getState(this._key).set(with_, ttl);
+    }
+  }
+  /**
+   * Exit from current scene to the root
+   *
+   * @param reset
+   *     Whether to reset scene state (only applicable in case this is a scoped scene)
+   */
+  async exit(reset = true) {
+    if (reset && this._scoped) await this.delete();
+    this._scene = null;
+    this._updateLocalKey();
+    await this._storage.deleteCurrentScene(this._key);
+  }
+  /**
+   * 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
+   */
+  async rateLimit(key, limit, window) {
+    const [remaining, reset] = await this._localStorage.getRateLimit(`${key}:${this._localKey}`, limit, window);
+    if (!remaining) {
+      throw new RateLimitError(reset);
+    }
+    return [remaining - 1, reset];
+  }
+  /**
+   * 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
+   */
+  async throttle(key, limit, window) {
+    try {
+      return await this.rateLimit(key, limit, window);
+    } catch (e) {
+      if (e instanceof RateLimitError) {
+        await utils.sleep(e.reset - Date.now());
+        return this.throttle(key, limit, window);
+      }
+      throw e;
+    }
+  }
+  /**
+   * Reset the rate limit
+   *
+   * @param key  Key of the rate limit
+   */
+  async resetRateLimit(key) {
+    await this._localStorage.resetRateLimit(`${key}:${this._localKey}`);
+  }
+}
+exports.RateLimitError = RateLimitError;
+exports.UpdateState = UpdateState;

package/state/update-state.d.cts

@@ -0,0 +1,151 @@
+import { Dispatcher } from '../dispatcher.js';
+import { StateService } from './service.js';
+import { MtcuteError } from '@mtcute/core';
+/**
+ * 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: StateService, key: string, scene: string | null, scoped?: boolean, customStorage?: StateService, 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>;
+}

package/state/update-state.d.ts

@@ -1,6 +1,6 @@
-import { MtcuteError } from '@mtcute/core';
 import { Dispatcher } from '../dispatcher.js';
 import { StateService } from './service.js';
+import { MtcuteError } from '@mtcute/core';
 /**
  * Error thrown by `.rateLimit()`
  */