@mtcute/dispatcher 0.17.2 → 0.18.0

package/state/update-state.js

@@ -0,0 +1,201 @@
+import { sleep } from "@fuman/utils";
+import { MtArgumentError, MtcuteError } from "@mtcute/core";
+class RateLimitError extends 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 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 MtArgumentError("Cannot enter a non-scene Dispatcher");
+    }
+    if (!scene["_parent"]) {
+      throw new 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 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 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}`);
+  }
+}
+export {
+  RateLimitError,
+  UpdateState
+};

package/wizard.cjs

@@ -0,0 +1,90 @@
+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 dispatcher = require("./dispatcher.cjs");
+const logic = require("./filters/logic.cjs");
+const state = require("./filters/state.cjs");
+var WizardSceneAction = /* @__PURE__ */ ((WizardSceneAction2) => {
+  WizardSceneAction2["Next"] = "next";
+  WizardSceneAction2["Stay"] = "stay";
+  WizardSceneAction2["Exit"] = "exit";
+  return WizardSceneAction2;
+})(WizardSceneAction || {});
+class WizardScene extends dispatcher.Dispatcher {
+  _steps = 0;
+  _defaultState = {};
+  constructor(name, params) {
+    super(void 0, { sceneName: name, ...params });
+  }
+  setDefaultState(defaultState) {
+    this._defaultState = defaultState;
+  }
+  /**
+   * Get the total number of registered steps
+   */
+  get totalSteps() {
+    return this._steps;
+  }
+  /**
+   * Go to the Nth step
+   */
+  async goToStep(state2, step) {
+    if (step >= this._steps) {
+      await state2.exit();
+    } else {
+      await state2.merge({ $step: step }, { fallback: this._defaultState });
+    }
+  }
+  /**
+   * Skip N steps
+   */
+  async skip(state2, count = 1) {
+    const { $step } = await state2.get() || {};
+    if ($step === void 0) throw new Error("Wizard state is not initialized");
+    return this.goToStep(state2, $step + count);
+  }
+  /**
+   * Filter that will only pass if the current step is `step`
+   */
+  // eslint-disable-next-line ts/no-empty-object-type
+  static onNthStep(step) {
+    const filter = state.state((it) => it.$step === step);
+    if (step === 0) return logic.or(state.stateEmpty, filter);
+    return filter;
+  }
+  /**
+   * Filter that will only pass if the current step is the one after last one added
+   */
+  // eslint-disable-next-line ts/no-empty-object-type
+  onCurrentStep() {
+    return WizardScene.onNthStep(this._steps);
+  }
+  /**
+   * Add a step to the wizard
+   */
+  addStep(handler) {
+    const step = this._steps++;
+    this.onNewMessage(WizardScene.onNthStep(step), async (msg, state2) => {
+      const result = await handler(msg, state2);
+      if (typeof result === "number") {
+        await this.goToStep(state2, result);
+        return;
+      }
+      switch (result) {
+        case "next": {
+          await this.goToStep(state2, step + 1);
+          break;
+        }
+        case "exit":
+          await state2.exit();
+          break;
+      }
+    });
+  }
+}
+exports.WizardScene = WizardScene;
+exports.WizardSceneAction = WizardSceneAction;

package/wizard.d.cts

@@ -0,0 +1,64 @@
+import { MaybePromise } from '@mtcute/core';
+import { MessageContext } from './context/message.js';
+import { DispatcherParams, Dispatcher } from './dispatcher.js';
+import { UpdateFilter } from './filters/index.js';
+import { UpdateState } from './state/update-state.js';
+/**
+ * Action for the wizard scene.
+ *
+ * `Next`: Continue to the next registered step
+ * (or exit, if this is the last step)
+ *
+ * `Stay`: Stay on the same step
+ *
+ * `Exit`: Exit from the wizard scene
+ *
+ * You can also return a `number` to jump to that step
+ */
+export declare enum WizardSceneAction {
+    Next = "next",
+    Stay = "stay",
+    Exit = "exit"
+}
+interface WizardInternalState {
+    $step?: number;
+}
+/**
+ * Wizard is a special type of Dispatcher
+ * that can be used to simplify implementing
+ * step-by-step scenes.
+ */
+export declare class WizardScene<State extends object> extends Dispatcher<State & WizardInternalState> {
+    private _steps;
+    private _defaultState;
+    constructor(name: string, params?: Omit<DispatcherParams, 'sceneName'>);
+    static for: never;
+    static child: never;
+    static scene: never;
+    setDefaultState(defaultState: State): void;
+    /**
+     * Get the total number of registered steps
+     */
+    get totalSteps(): number;
+    /**
+     * Go to the Nth step
+     */
+    goToStep(state: UpdateState<WizardInternalState>, step: number): Promise<void>;
+    /**
+     * Skip N steps
+     */
+    skip(state: UpdateState<WizardInternalState>, count?: number): Promise<void>;
+    /**
+     * Filter that will only pass if the current step is `step`
+     */
+    static onNthStep(step: number): UpdateFilter<any, {}, WizardInternalState>;
+    /**
+     * Filter that will only pass if the current step is the one after last one added
+     */
+    onCurrentStep(): UpdateFilter<any, {}, WizardInternalState>;
+    /**
+     * Add a step to the wizard
+     */
+    addStep(handler: (msg: MessageContext, state: UpdateState<State & WizardInternalState>) => MaybePromise<WizardSceneAction | number>): void;
+}
+export {};

package/wizard.js

@@ -0,0 +1,85 @@
+import { Dispatcher } from "./dispatcher.js";
+import { or } from "./filters/logic.js";
+import { state, stateEmpty } from "./filters/state.js";
+var WizardSceneAction = /* @__PURE__ */ ((WizardSceneAction2) => {
+  WizardSceneAction2["Next"] = "next";
+  WizardSceneAction2["Stay"] = "stay";
+  WizardSceneAction2["Exit"] = "exit";
+  return WizardSceneAction2;
+})(WizardSceneAction || {});
+class WizardScene extends Dispatcher {
+  _steps = 0;
+  _defaultState = {};
+  constructor(name, params) {
+    super(void 0, { sceneName: name, ...params });
+  }
+  setDefaultState(defaultState) {
+    this._defaultState = defaultState;
+  }
+  /**
+   * Get the total number of registered steps
+   */
+  get totalSteps() {
+    return this._steps;
+  }
+  /**
+   * Go to the Nth step
+   */
+  async goToStep(state2, step) {
+    if (step >= this._steps) {
+      await state2.exit();
+    } else {
+      await state2.merge({ $step: step }, { fallback: this._defaultState });
+    }
+  }
+  /**
+   * Skip N steps
+   */
+  async skip(state2, count = 1) {
+    const { $step } = await state2.get() || {};
+    if ($step === void 0) throw new Error("Wizard state is not initialized");
+    return this.goToStep(state2, $step + count);
+  }
+  /**
+   * Filter that will only pass if the current step is `step`
+   */
+  // eslint-disable-next-line ts/no-empty-object-type
+  static onNthStep(step) {
+    const filter = state((it) => it.$step === step);
+    if (step === 0) return or(stateEmpty, filter);
+    return filter;
+  }
+  /**
+   * Filter that will only pass if the current step is the one after last one added
+   */
+  // eslint-disable-next-line ts/no-empty-object-type
+  onCurrentStep() {
+    return WizardScene.onNthStep(this._steps);
+  }
+  /**
+   * Add a step to the wizard
+   */
+  addStep(handler) {
+    const step = this._steps++;
+    this.onNewMessage(WizardScene.onNthStep(step), async (msg, state2) => {
+      const result = await handler(msg, state2);
+      if (typeof result === "number") {
+        await this.goToStep(state2, result);
+        return;
+      }
+      switch (result) {
+        case "next": {
+          await this.goToStep(state2, step + 1);
+          break;
+        }
+        case "exit":
+          await state2.exit();
+          break;
+      }
+    });
+  }
+}
+export {
+  WizardScene,
+  WizardSceneAction
+};