@mtcute/dispatcher 0.1.0

package/esm/dispatcher.js

@@ -0,0 +1,761 @@
+/* eslint-disable @typescript-eslint/unified-signatures,@typescript-eslint/no-unsafe-assignment */
+/* eslint-disable @typescript-eslint/no-unsafe-argument,@typescript-eslint/no-unsafe-call,max-depth,dot-notation */
+/* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/ban-types */
+// ^^ will be looked into in MTQ-29
+import { MtArgumentError, } from '@mtcute/client';
+import { _parsedUpdateToContext } from './context/parse.js';
+import { defaultStateKeyDelegate, isCompatibleStorage, UpdateState, } from './state/index.js';
+/**
+ * Updates dispatcher
+ */
+export class Dispatcher {
+    constructor(client, params) {
+        this._groups = {};
+        this._groupsOrder = [];
+        this._children = [];
+        this.dispatchRawUpdate = this.dispatchRawUpdate.bind(this);
+        this.dispatchUpdate = this.dispatchUpdate.bind(this);
+        // eslint-disable-next-line prefer-const
+        let { storage, key, sceneName } = params ?? {};
+        if (client) {
+            this.bindToClient(client);
+            if (!storage) {
+                const _storage = client.storage;
+                if (!isCompatibleStorage(_storage)) {
+                    throw new MtArgumentError('Storage used by the client is not compatible with the dispatcher. Please provide a compatible storage manually');
+                }
+                storage = _storage;
+            }
+            if (storage) {
+                this._storage = storage;
+                this._stateKeyDelegate = (key ?? defaultStateKeyDelegate);
+            }
+        }
+        else {
+            // child dispatcher without client
+            if (storage) {
+                this._customStorage = storage;
+            }
+            if (key) {
+                this._customStateKeyDelegate = key;
+            }
+            if (sceneName) {
+                if (sceneName[0] === '$') {
+                    throw new MtArgumentError('Scene name cannot start with $');
+                }
+                this._scene = sceneName;
+            }
+        }
+    }
+    /**
+     * Create a new dispatcher and bind it to the client.
+     */
+    static for(client, params) {
+        return new Dispatcher(client, params);
+    }
+    /**
+     * Create a new child dispatcher.
+     */
+    static child(params) {
+        return new Dispatcher(undefined, params);
+    }
+    /**
+     * Create a new scene dispatcher
+     */
+    static scene(name, params) {
+        return new Dispatcher(undefined, { sceneName: name, ...params });
+    }
+    /** For scene dispatchers, name of the scene */
+    get sceneName() {
+        return this._scene;
+    }
+    /**
+     * Bind the dispatcher to the client.
+     * Called by the constructor automatically if
+     * `client` was passed.
+     *
+     * Under the hood, this replaces client's `dispatchUpdate`
+     * function, meaning you can't bind two different
+     * dispatchers to the same client at the same time.
+     * Instead, use {@link extend}, {@link addChild}
+     * or {@link addScene} on the existing, already bound dispatcher.
+     *
+     * Dispatcher also uses bound client to throw errors
+     */
+    bindToClient(client) {
+        client.on('update', this.dispatchUpdate);
+        client.on('raw_update', this.dispatchRawUpdate);
+        this._client = client;
+    }
+    /**
+     * Unbind a dispatcher from the client.
+     *
+     * This will replace client's dispatchUpdate with a no-op.
+     * If this dispatcher is not bound, nothing will happen.
+     */
+    unbind() {
+        if (this._client) {
+            this._client.off('update', this.dispatchUpdate);
+            this._client.off('raw_update', this.dispatchRawUpdate);
+            this._client = undefined;
+        }
+    }
+    /**
+     * Process a raw update with this dispatcher.
+     * Calling this method without bound client will not work.
+     *
+     * Under the hood asynchronously calls {@link dispatchRawUpdateNow}
+     * with error handler set to client's one.
+     *
+     * @param update  Update to process
+     * @param peers Peers index
+     */
+    dispatchRawUpdate(update, peers) {
+        if (!this._client)
+            return;
+        // order does not matter in the dispatcher,
+        // so we can handle each update in its own task
+        this.dispatchRawUpdateNow(update, peers).catch((err) => this._client._emitError(err));
+    }
+    /**
+     * Process a raw update right now in the current stack.
+     *
+     * Unlike {@link dispatchRawUpdate}, this does not schedule
+     * the update to be dispatched, but dispatches it immediately,
+     * and after `await`ing this method you can be certain that the update
+     * was fully processed by all the registered handlers, including children.
+     *
+     * @param update  Update to process
+     * @param peers  Peers map
+     * @returns  Whether the update was handled
+     */
+    async dispatchRawUpdateNow(update, peers) {
+        if (!this._client)
+            return false;
+        let handled = false;
+        outer: for (const grp of this._groupsOrder) {
+            const group = this._groups[grp];
+            if ('raw' in group) {
+                const handlers = group.raw;
+                for (const h of handlers) {
+                    let result;
+                    if (!h.check || (await h.check(this._client, update, peers))) {
+                        result = await h.callback(this._client, update, peers);
+                        handled = true;
+                    }
+                    else
+                        continue;
+                    switch (result) {
+                        case 'continue':
+                            continue;
+                        case 'stop':
+                            break outer;
+                        case 'stop-children':
+                            return handled;
+                    }
+                    break;
+                }
+            }
+        }
+        for (const child of this._children) {
+            const childHandled = await child.dispatchRawUpdateNow(update, peers);
+            handled || (handled = childHandled);
+        }
+        return handled;
+    }
+    /**
+     * Process an update with this dispatcher.
+     * Calling this method without bound client will not work.
+     *
+     * Under the hood asynchronously calls {@link dispatchUpdateNow}
+     * with error handler set to client's one.
+     *
+     * @param update  Update to process
+     */
+    dispatchUpdate(update) {
+        if (!this._client)
+            return;
+        // order does not matter in the dispatcher,
+        // so we can handle each update in its own task
+        this.dispatchUpdateNow(update).catch((err) => this._client._emitError(err));
+    }
+    /**
+     * Process an update right now in the current stack.
+     *
+     * Unlike {@link dispatchUpdate}, this does not schedule
+     * the update to be dispatched, but dispatches it immediately,
+     * and after `await`ing this method you can be certain that the update
+     * was fully processed by all the registered handlers, including children.
+     *
+     * @param update  Update to process
+     * @returns  Whether the update was handled
+     */
+    async dispatchUpdateNow(update) {
+        return this._dispatchUpdateNowImpl(update);
+    }
+    async _dispatchUpdateNowImpl(update, 
+    // this is getting a bit crazy lol
+    parsedState, parsedScene, forceScene, parsedContext) {
+        if (!this._client)
+            return false;
+        if (parsedScene === undefined) {
+            if (this._storage &&
+                this._scenes &&
+                (update.name === 'new_message' ||
+                    update.name === 'edit_message' ||
+                    update.name === 'callback_query' ||
+                    update.name === 'message_group')) {
+                // no need to fetch scene if there are no registered scenes
+                if (!parsedContext)
+                    parsedContext = _parsedUpdateToContext(this._client, update);
+                const key = await this._stateKeyDelegate(parsedContext);
+                if (key) {
+                    parsedScene = await this._storage.getCurrentScene(key);
+                }
+                else {
+                    parsedScene = null;
+                }
+            }
+            else {
+                parsedScene = null;
+            }
+        }
+        if (!forceScene && parsedScene !== null) {
+            if (this._scene) {
+                if (this._scene !== parsedScene) {
+                    // should not happen, but just in case
+                    return false;
+                }
+            }
+            else {
+                if (!this._scenes || !(parsedScene in this._scenes)) {
+                    // not registered scene
+                    return false;
+                }
+                return this._scenes[parsedScene]._dispatchUpdateNowImpl(update, parsedState, parsedScene, true);
+            }
+        }
+        if (parsedState === undefined) {
+            if (this._storage &&
+                (update.name === 'new_message' ||
+                    update.name === 'edit_message' ||
+                    update.name === 'callback_query' ||
+                    update.name === 'message_group')) {
+                if (!parsedContext)
+                    parsedContext = _parsedUpdateToContext(this._client, update);
+                const key = await this._stateKeyDelegate(parsedContext);
+                if (key) {
+                    let customKey;
+                    if (!this._customStateKeyDelegate ||
+                        (customKey = await this._customStateKeyDelegate(parsedContext))) {
+                        parsedState = new UpdateState(this._storage, key, this._scene ?? null, this._sceneScoped, this._customStorage, customKey);
+                    }
+                }
+                else {
+                    parsedState = null;
+                }
+            }
+            else {
+                parsedState = null;
+            }
+        }
+        let shouldDispatch = true;
+        let shouldDispatchChildren = true;
+        let handled = false;
+        switch (await this._preUpdateHandler?.(update, parsedState)) {
+            case 'stop':
+                shouldDispatch = false;
+                break;
+            case 'stop-children':
+                return false;
+        }
+        if (shouldDispatch) {
+            outer: for (const grp of this._groupsOrder) {
+                const group = this._groups[grp];
+                if (update.name in group) {
+                    // raw is not handled here, so we can safely assume this
+                    const handlers = group[update.name];
+                    try {
+                        for (const h of handlers) {
+                            let result;
+                            if (!parsedContext)
+                                parsedContext = _parsedUpdateToContext(this._client, update);
+                            if (!h.check || (await h.check(parsedContext, parsedState))) {
+                                result = await h.callback(parsedContext, parsedState);
+                                handled = true;
+                            }
+                            else
+                                continue;
+                            switch (result) {
+                                case 'continue':
+                                    continue;
+                                case 'stop':
+                                    break outer;
+                                case 'stop-children':
+                                    shouldDispatchChildren = false;
+                                    break outer;
+                                case 'scene': {
+                                    if (!parsedState) {
+                                        throw new MtArgumentError('Cannot use ToScene without state');
+                                    }
+                                    const scene = parsedState['_scene'];
+                                    if (!scene) {
+                                        throw new MtArgumentError('Cannot use ToScene without entering a scene');
+                                    }
+                                    return this._scenes[scene]._dispatchUpdateNowImpl(update, undefined, scene, true);
+                                }
+                            }
+                            break;
+                        }
+                    }
+                    catch (e) {
+                        if (this._errorHandler) {
+                            const handled = await this._errorHandler(e, update, parsedState);
+                            if (!handled)
+                                throw e;
+                        }
+                        else {
+                            throw e;
+                        }
+                    }
+                }
+            }
+        }
+        if (shouldDispatchChildren) {
+            for (const child of this._children) {
+                const childHandled = await child._dispatchUpdateNowImpl(update);
+                handled || (handled = childHandled);
+            }
+        }
+        await this._postUpdateHandler?.(handled, update, parsedState);
+        return handled;
+    }
+    /**
+     * Add an update handler to a given handlers group
+     *
+     * @param handler  Update handler
+     * @param group  Handler group index
+     */
+    addUpdateHandler(handler, group = 0) {
+        if (!(group in this._groups)) {
+            this._groups[group] = {};
+            this._groupsOrder.push(group);
+            this._groupsOrder.sort((a, b) => a - b);
+        }
+        if (!(handler.name in this._groups[group])) {
+            this._groups[group][handler.name] = [];
+        }
+        this._groups[group][handler.name].push(handler);
+    }
+    /**
+     * Remove an update handler (or handlers) from a given
+     * handler group.
+     *
+     * @param handler  Update handler to remove, its name or `'all'` to remove all
+     * @param group  Handler group index (-1 to affect all groups)
+     */
+    removeUpdateHandler(handler, group = 0) {
+        if (group !== -1 && !(group in this._groups)) {
+            return;
+        }
+        if (typeof handler === 'string') {
+            if (handler === 'all') {
+                if (group === -1) {
+                    this._groups = {};
+                }
+                else {
+                    delete this._groups[group];
+                }
+            }
+            else {
+                delete this._groups[group][handler];
+            }
+            return;
+        }
+        if (!(handler.name in this._groups[group])) {
+            return;
+        }
+        const idx = this._groups[group][handler.name].indexOf(handler);
+        if (idx > -1) {
+            this._groups[group][handler.name].splice(idx, 1);
+        }
+    }
+    /**
+     * Register an error handler.
+     *
+     * This is used locally within this dispatcher
+     * (does not affect children/parent) whenever
+     * an error is thrown inside an update handler.
+     * Not used for raw update handlers
+     *
+     * When an error is thrown, but there is no error
+     * handler, it is propagated to `TelegramClient`.
+     *
+     * There can be at most one error handler.
+     * Pass `null` to remove it.
+     *
+     * @param handler  Error handler
+     */
+    onError(handler) {
+        if (handler)
+            this._errorHandler = handler;
+        else
+            this._errorHandler = undefined;
+    }
+    /**
+     * Register pre-update middleware.
+     *
+     * This is used locally within this dispatcher
+     * (does not affect children/parent) before processing
+     * an update, and can be used to skip this update.
+     *
+     * There can be at most one pre-update middleware.
+     * Pass `null` to remove it.
+     *
+     * @param handler  Pre-update middleware
+     */
+    onPreUpdate(handler) {
+        if (handler)
+            this._preUpdateHandler = handler;
+        else
+            this._preUpdateHandler = undefined;
+    }
+    /**
+     * Register post-update middleware.
+     *
+     * This is used locally within this dispatcher
+     * (does not affect children/parent) after successfully
+     * processing an update, and can be used for stats.
+     *
+     * There can be at most one post-update middleware.
+     * Pass `null` to remove it.
+     *
+     * @param handler  Pre-update middleware
+     */
+    onPostUpdate(handler) {
+        if (handler)
+            this._postUpdateHandler = handler;
+        else
+            this._postUpdateHandler = undefined;
+    }
+    /**
+     * Set error handler that will propagate
+     * the error to the parent dispatcher
+     */
+    propagateErrorToParent(err, update, state) {
+        if (!this.parent) {
+            throw new MtArgumentError('This dispatcher is not a child');
+        }
+        if (this.parent._errorHandler) {
+            return this.parent._errorHandler(err, update, state);
+        }
+        throw err;
+    }
+    // children //
+    /**
+     * Get parent dispatcher if current dispatcher is a child.
+     * Otherwise, return `null`
+     */
+    get parent() {
+        return this._parent ?? null;
+    }
+    _prepareChild(child) {
+        if (child._client) {
+            throw new MtArgumentError('Provided dispatcher is ' +
+                (child._parent ?
+                    'already a child. Use parent.removeChild() before calling addChild()' :
+                    'already bound to a client. Use unbind() before calling addChild()'));
+        }
+        child._parent = this;
+        child._client = this._client;
+        child._storage = this._storage;
+        child._stateKeyDelegate = this._stateKeyDelegate;
+    }
+    /**
+     * Add a child dispatcher.
+     *
+     * Child dispatchers are called when dispatching updates
+     * just like normal, except they can be controlled
+     * externally. Additionally, child dispatcher have their own
+     * independent handler grouping that does not interfere with parent's,
+     * including `StopPropagation` (i.e. returning `StopPropagation` will
+     * still call children. To entirely stop, use `StopChildrenPropagation`)
+     *
+     * Note that child dispatchers share the same TelegramClient and
+     * storage binding as the parent, don't bind them manually.
+     *
+     * @param child  Other dispatcher
+     */
+    addChild(child) {
+        if (this._children.includes(child))
+            return;
+        this._prepareChild(child);
+        this._children.push(child);
+    }
+    addScene(scene, scoped = true) {
+        if (!this._scenes)
+            this._scenes = {};
+        if (!scene._scene) {
+            throw new MtArgumentError('Non-scene dispatcher passed to addScene. Use `Dispatcher.scene()` to create one.');
+        }
+        if (scene._scene in this._scenes) {
+            throw new MtArgumentError(`Scene with name ${scene._scene} is already registered!`);
+        }
+        this._prepareChild(scene);
+        scene._sceneScoped = scoped;
+        this._scenes[scene._scene] = scene;
+    }
+    /**
+     * Remove a child dispatcher.
+     *
+     * Removing child dispatcher will also remove
+     * child dispatcher's client binding.
+     *
+     * If the provided dispatcher is not a child of current,
+     * this function will silently fail.
+     *
+     * @param child  Other dispatcher
+     */
+    removeChild(child) {
+        const idx = this._children.indexOf(child);
+        if (idx > -1) {
+            child._unparent();
+            this._children.splice(idx, 1);
+        }
+    }
+    _unparent() {
+        this._parent = this._client = undefined;
+        this._stateKeyDelegate = undefined;
+        this._storage = undefined;
+    }
+    /**
+     * Extend current dispatcher by copying other dispatcher's
+     * handlers and children to the current.
+     *
+     * This might be more efficient for simple cases, but do note that the handler
+     * groups, children and scenes will get merged (unlike {@link addChild},
+     * where they are independent). Also note that unlike with children,
+     * when adding handlers to `other` *after* you extended
+     * the current dispatcher, changes will not be applied.
+     *
+     * @param other  Other dispatcher
+     */
+    extend(other) {
+        if (other._customStorage || other._customStateKeyDelegate) {
+            throw new MtArgumentError('Provided dispatcher has custom storage and cannot be extended from.');
+        }
+        other._groupsOrder.forEach((group) => {
+            if (!(group in this._groups)) {
+                this._groups[group] = other._groups[group];
+                this._groupsOrder.push(group);
+            }
+            else {
+                const otherGrp = other._groups[group];
+                const selfGrp = this._groups[group];
+                Object.keys(otherGrp).forEach((typ) => {
+                    if (!(typ in selfGrp)) {
+                        selfGrp[typ] = otherGrp[typ];
+                    }
+                    else {
+                        selfGrp[typ].push(...otherGrp[typ]);
+                    }
+                });
+            }
+        });
+        other._children.forEach((it) => {
+            it._unparent();
+            this.addChild(it);
+        });
+        if (other._scenes) {
+            const otherScenes = other._scenes;
+            if (!this._scenes)
+                this._scenes = {};
+            const myScenes = this._scenes;
+            Object.keys(otherScenes).forEach((key) => {
+                otherScenes[key]._unparent();
+                if (key in myScenes) {
+                    // will be overwritten
+                    delete myScenes[key];
+                }
+                this.addScene(myScenes[key], myScenes[key]._sceneScoped);
+            });
+        }
+        this._groupsOrder.sort((a, b) => a - b);
+    }
+    /**
+     * Create a clone of this dispatcher, that has the same handlers,
+     * but is not bound to a client or to a parent dispatcher.
+     *
+     * Custom Storage and key delegate are copied too.
+     *
+     * By default, child dispatchers (and scenes) are ignored, since
+     * that requires cloning every single one of them recursively
+     * and then binding them back.
+     *
+     * @param children  Whether to also clone children and scenes
+     */
+    clone(children = false) {
+        const dp = new Dispatcher();
+        // copy handlers.
+        Object.keys(this._groups).forEach((key) => {
+            const idx = key;
+            dp._groups[idx] = {};
+            Object.keys(this._groups[idx]).forEach((type) => {
+                dp._groups[idx][type] = [...this._groups[idx][type]];
+            });
+        });
+        dp._groupsOrder = [...this._groupsOrder];
+        dp._errorHandler = this._errorHandler;
+        dp._customStateKeyDelegate = this._customStateKeyDelegate;
+        dp._customStorage = this._customStorage;
+        if (children) {
+            this._children.forEach((it) => {
+                const child = it.clone(true);
+                dp.addChild(child);
+            });
+            if (this._scenes) {
+                Object.keys(this._scenes).forEach((key) => {
+                    const scene = this._scenes[key].clone(true);
+                    dp.addScene(scene, this._scenes[key]._sceneScoped);
+                });
+            }
+        }
+        return dp;
+    }
+    getState(object) {
+        if (!this._storage) {
+            throw new MtArgumentError('Cannot use getUpdateState() filter without state storage');
+        }
+        if (typeof object === 'string') {
+            return new UpdateState(this._storage, object, this._scene ?? null, this._sceneScoped, this._customStorage);
+        }
+        return Promise.resolve(this._stateKeyDelegate(object)).then((key) => {
+            if (!key) {
+                throw new MtArgumentError('Cannot derive key from given object');
+            }
+            if (!this._customStateKeyDelegate) {
+                return new UpdateState(this._storage, key, this._scene ?? null, this._sceneScoped, this._customStorage);
+            }
+            return Promise.resolve(this._customStateKeyDelegate(object)).then((customKey) => {
+                if (!customKey) {
+                    throw new MtArgumentError('Cannot derive custom key from given object');
+                }
+                return new UpdateState(this._storage, key, this._scene ?? null, this._sceneScoped, this._customStorage, customKey);
+            });
+        });
+    }
+    /**
+     * Get global state.
+     *
+     * This will load the state for the given object
+     * ignoring local custom storage, key delegate and scene scope.
+     */
+    getGlobalState(object) {
+        if (!this._parent) {
+            throw new MtArgumentError('This dispatcher does not have a parent');
+        }
+        return Promise.resolve(this._stateKeyDelegate(object)).then((key) => {
+            if (!key) {
+                throw new MtArgumentError('Cannot derive key from given object');
+            }
+            return new UpdateState(this._storage, key, this._scene ?? null, false);
+        });
+    }
+    // addUpdateHandler convenience wrappers //
+    _addKnownHandler(name, filter, handler, group) {
+        if (typeof handler === 'number' || typeof handler === 'undefined') {
+            this.addUpdateHandler({
+                name,
+                callback: filter,
+            }, handler);
+        }
+        else {
+            this.addUpdateHandler({
+                name,
+                callback: handler,
+                check: filter,
+            }, group);
+        }
+    }
+    /** @internal */
+    onRawUpdate(filter, handler, group) {
+        this._addKnownHandler('raw', filter, handler, group);
+    }
+    /** @internal */
+    onNewMessage(filter, handler, group) {
+        this._addKnownHandler('new_message', filter, handler, group);
+    }
+    /** @internal */
+    onEditMessage(filter, handler, group) {
+        this._addKnownHandler('edit_message', filter, handler, group);
+    }
+    /** @internal */
+    onMessageGroup(filter, handler, group) {
+        this._addKnownHandler('message_group', filter, handler, group);
+    }
+    /** @internal */
+    onDeleteMessage(filter, handler, group) {
+        this._addKnownHandler('delete_message', filter, handler, group);
+    }
+    /** @internal */
+    onChatMemberUpdate(filter, handler, group) {
+        this._addKnownHandler('chat_member', filter, handler, group);
+    }
+    /** @internal */
+    onInlineQuery(filter, handler, group) {
+        this._addKnownHandler('inline_query', filter, handler, group);
+    }
+    /** @internal */
+    onChosenInlineResult(filter, handler, group) {
+        this._addKnownHandler('chosen_inline_result', filter, handler, group);
+    }
+    /** @internal */
+    onCallbackQuery(filter, handler, group) {
+        this._addKnownHandler('callback_query', filter, handler, group);
+    }
+    /** @internal */
+    onPollUpdate(filter, handler, group) {
+        this._addKnownHandler('poll', filter, handler, group);
+    }
+    /** @internal */
+    onPollVote(filter, handler, group) {
+        this._addKnownHandler('poll_vote', filter, handler, group);
+    }
+    /** @internal */
+    onUserStatusUpdate(filter, handler, group) {
+        this._addKnownHandler('user_status', filter, handler, group);
+    }
+    /** @internal */
+    onUserTyping(filter, handler, group) {
+        this._addKnownHandler('user_typing', filter, handler, group);
+    }
+    /** @internal */
+    onHistoryRead(filter, handler, group) {
+        this._addKnownHandler('history_read', filter, handler, group);
+    }
+    /** @internal */
+    onBotStopped(filter, handler, group) {
+        this._addKnownHandler('bot_stopped', filter, handler, group);
+    }
+    /** @internal */
+    onBotChatJoinRequest(filter, handler, group) {
+        this._addKnownHandler('bot_chat_join_request', filter, handler, group);
+    }
+    /** @internal */
+    onChatJoinRequest(filter, handler, group) {
+        this._addKnownHandler('chat_join_request', filter, handler, group);
+    }
+    /** @internal */
+    onPreCheckoutQuery(filter, handler, group) {
+        this._addKnownHandler('pre_checkout_query', filter, handler, group);
+    }
+    /** @internal */
+    onStoryUpdate(filter, handler, group) {
+        this._addKnownHandler('story', filter, handler, group);
+    }
+    /** @internal */
+    onDeleteStory(filter, handler, group) {
+        this._addKnownHandler('delete_story', filter, handler, group);
+    }
+}
+//# sourceMappingURL=dispatcher.js.map