node-telegram-operation-manager v1.2.0

Node Telegram Operation Manager

This package purpose is to help managing the operations in Telegram bots in Node.js.

Installation

$ npm install --save node-telegram-operation-manager

Architecture

The package exports 3 classes to achive different purposes:

• Queue Manager
• Reply Manager
• Operation Manager

The purposes are described below.

The second and the third extends Queue Manager to access to queue manipulation methods.

This is not a typical implementation of Queue. In fact this is a set of Queues, all identified by a custom identifier, which might be e.g. the user id the telegram bot interacts with. The package makes available also operation to remove elements from the queue from the bottom (pop) or inside the queue (cherrypickRemove).

Queue Manager is exported to let developers to implement their own queues. This class is recommended to be exported only for this purpose, nothing else.

Reply Manager

Reply Manager is specifically studied to register common set of actions to be executed or repeated in a flow which can be, for example, a sequence of message from a user.

Actually, if not native, Telegram bot api wrappers make it difficult to manage this aspect.

Operation Manager

Operation Manager is designed to manage the amount of operations can be active at the same time for a specific user.

Operation Manager is not that useful to be used alone. In fact, it should be using to wrap the registration of replies.

Queue Manager

Queue Manager is the responsible class for queue managing. Although exported, it shouldn't be used except for implementing other queues.

Examples

Two working examples are provided in example folder.

They are structured to be a step-by-step examples in a chat with a bot you will choose by passing the token to the respective commands as below.

# ==================================#
# Execute these two commands before #
# ==================================#

# Go to project folder - assuming you installed it as module.
$ cd node_modules/node-telegram-operation-manager

# Development packages
$ npm install -D;

# =========================

$ npm run reply -- 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
# or
$ npm run operations -- 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11

Tests

Tests are also included. This package uses Jasmine as test suite.

$ npm install -D;
$ npm test

API Reference

• Reply Manager - .register() - .cancelAll() - .pop() - .expects() - .execute() - .skip() - .pending()
• Operation Manager - .register() - .end() - .onGoing() - .hasActive() - .hasReachedMaximum() - .empty() - .maxConcurrent
• Queue Manager - .push() - .remove() - .removeAll() - .cherryPickRemove() - .has() - .all() - .get() - .pop() - .emptyQueue()

Reply Manager

Reply Manager extends QueueManager with a type Reply, which will be used below to represent to express one pushed or pulled element.

Please keep this as always valid:

// for Typescript
import { ReplyManager } from "node-telegram-operation-manager";

// for Node.js
const { ReplyManager } = require("node-telegram-operation-manager");

const reply = new ReplyManager();

.register();

It adds a new action to be executed at the next user reply.

reply.register(id, action) : this;

Description:

action parameter has the following signature:

action: (someData?: ReplyData) => RegisteredResponse

You can pass through the method execute, some arbitrary data to be used in the current response. They will appear in someData.

It will also include a key, called previousData, which will be the data returned from the previous registered replies. If no data is returned from the previous responses, it won't have this key.

To pass datas to the next reply, just return an object with your data.

The default behavior is to remove from the queue the current reply. If current user reply does not satisfy your conditions, you can make them repeat, by returning:

{
	repeat: true,
	someOtherDatas: ...
}

Omitting repeat key or setting it to false, will determine the default behavior to be executed.

Returns:

The object itself for chaining multiple replies listeners.

Arguments:

.cancelAll()

It removes all the actions for a specific identifier.

reply.cancelAll(id) : this;

Returns:

The object itself for chaining.

Arguments:

.pop()

It removes the last element from a specific queue.

reply.pop(id) : Reply;

Returns:

The expelled element.

Arguments:

.expects()

It checks if there are any element in queue for the specified identifier. Useful on telegram message listener.

reply.expects(id) : boolean;

Returns: The result of the check.

Arguments:

.execute()

It execute the next registered action in the queue and removes it from the queue.

reply.execute(id, data);

Arguments:

.skip()

Skips the execution of the current reply and pass to the next one. Before skipping, it checks if there are other replies in the queue. It will succeed only if the current reply is not the last.

reply.skip(id) : boolean;

Returns:

Whether current reply got skipped or not.

Arguments:

.pending()

It fetches all the pending replies object. Even this might be the most useless method in the class.

reply.pending(id) : Reply[];

Returns:

Whether current reply got skipped or not.

Arguments:

Operation Manager

Operation Manager extends QueueManager with a type Operation, which will be used below to represent to express one element.

Please keep this as always valid:

// for Typescript
import { OperationManager } from "node-telegram-operation-manager";

// for Node.js
const { OperationManager } = require("node-telegram-operation-manager");

const opm = new OperationManager();

.register();

It adds a new operation in execution list.

opm.register(id, command, action) : any | undefined;

Returns:

The result of action.

Arguments:

.end()

It removes a specific action or all the actions for a specific identifier, based on the presence or absence of parameter commandName.

opm.end(id, commandName?) : Operation;

Returns:

The object itself for chaining.

Arguments:

.onGoing()

Fetches all the active operation. Warning: might be useless.

opm.onGoing(id) : Operation[];

Returns:

All on going operations for a specific identifier.

Arguments:

.hasActive()

It checks if there are any active operations in queue for the specified identifier.

opm.hasActive(id) : boolean;

Returns: The result of the check.

Arguments:

.hasReachedMaximum()

Checks whether the limit of concurrent operations has been reached.

opm.hasReachedMaximum(id): boolean;

Arguments:

.empty()

It wipes out a specific operation queue.

opm.empty(id) : boolean;

Returns: the operation result.

Arguments:

.maxConcurrent

It determines the maximum of concurrent operation that may happen. The value must be a number.

opm.maxConcurrent = N;

Queue Manager

Queue Manager is the basic class for all the classes above. QueueManager class has type T, that will be used to represent objects.

Please note that this class should be used only as extension for other classes.

Please keep this as always valid:

// for Typescript
import { QueueManager } from "node-telegram-operation-manager";

// for Node.js
const { QueueManager } = require("node-telegram-operation-manager");

class newQueueOperator extends QueueManager<QueueOperatorStruct> {
	// Here T is QueueOperatorStruct
}

.push();

It adds a new operation to the queue.

reply.push(id, object: T) : number;

Returns:

The amount of elements

Arguments:

.remove()

It removes the first element from a specific queue identified.

.remove(id) : T;

Returns:

The removed object.

Arguments:

.removeAll()

Removes all the elements from a specific queue.

.removeAll(id) : void;

Arguments:

.cherryPickRemove()

Removes a specific element from a specific queue.

.cherryPickRemove(id, criteria) : T;

Returns: The removed element if found, empty object otherwise.

Arguments:

.has()

Checks if a specific identifier has some elements inside its queue.

.has(id) : boolean;

Returns:

The result of operation.

Arguments:

.all()

Fetches all the elements in a specific queue.

.all(id) : T[];

Returns: the operation result.

Arguments:

.get()

Fetches the first element in a specific queue.

.get(id) : T;

Returns: the first element in the queue.

Arguments:

.get()

Removes the last element from the queue.

.pop(id) : T;

Returns: the removed element.

Arguments:

.emptyQueue()

Wipes out a specific queue or the whole set of queues, based on presence of id parameter.

.emptyQueue(id?) : number;

Returns: the amount of removed element or removed sets.

Arguments: