@alpha-manager/core

Alpha Manager [core]

Introduction

Alpha Manager is a superpowered utility for creating and scheduling tasks.

Key features

• Friendly, chainable API
• Only 1 dependency
• Support for interacting with social medias
• Compatible with @alpha-manager/web-interface, a web interface that allows you to manage your tasks from any device, using a visual interface

Getting started

Installation

$ npm i --s @alpha-manager/core

Quick Start

const alpha = require ('@alpha-manager/core');

const simpleTask = new alpha.Task ()
	.do (() => {
        console.log ('this code will be executed every 5 minutes');
    })
	.every (5).minute ()
	.start ();

You don't necessarily have to chain the methods, but this is how Alpha was intended to be used.

For example, you could

const simpleTask = new alpha.Task ();
simpleTask.do (() => {
    //...
});
simpleTask.every (5).minute ();
simpleTask.start ();

Scheduling

Alpha uses later.js for scheduling, so I recommend reading their docs for more info about it.

What Alpha does is harness the power of later.js while making it more flexible, modular, and friendly.

You can also use a Cron expression, instead of the chainable functions. For example:

const simpleTask = new alpha.Task ()
	.do (() => {
        console.log ('this code will be executed every 5 minutes');
    })
	.schedule.cron ('0 */5 * * * *')
	.start ();

is the same as the one before, or you can use the plain text expressions, such as

const simpleTask = new alpha.Task ()
	.do (() => {
        console.log ('this code will be executed every 5 minutes');
    })
	.schedule.text ('every 5 mins')
	.start ();

I strongly recommend reading the later.js docs, because that library is at the heart of Alpha.

We use the .start () function to schedule the task.

Pausing / Resuming a task

A task can be easily paused and resume by using the .pause () and .resume () methods.

Alternatively, .togglePause () can be used if the task needs to be toggled.

To find out if a task is paused or not, we can look at the .isPaused property of it.

const myTask = new alpha.Task ()
	.do (() => ...)
    .every (1).hour ()
	.start ();
console.log (myTask.isPaused) // false

myTask.pause ();
console.log (myTask.isPaused) // true

myTask.resume ();
console.log (myTask.isPaused) // false

Immediate tasks

Immediate tasks are executed as soon as .start () is called. We can set a task as immediate by calling .immediate () on it.

We can find out if a task is immediate by looking at its .isImmediate property;

const myTask = new alpha.Task ()
	.do (() => ...)
    .every (1).hour ()
	.immediate ()
	.start ();
console.log (myTask.isImmediate) //true

Receivers

In certain situations you may want your recurring function to pass data to a receiver function once it's done, this is useful when interacting with social media platforms which we will discuss later.

To add, or subscribe, a function or platform to a task, we use the .to method of the task.

const simpleTask = new alpha.Task ()
	.to ((actionObject) => {
        console.log (actionObject);
        /*
        actionObject will be
        {
        	myProperty: 5,
        	done: [Function]
        }
        */
    })
	.do (actionObject => {
        console.log ('this code will be executed every 5 minutes');
        actionObject.myProperty = 5;
        actionObject.done ();
    })
	.every (5).minute ()
	.start ();

Alpha automatically passes an action object to the function you give to .do, all you need to do is add your own properties to that object and call .done () on it. That object is then sent to all the receivers of the task.

Adding multiple receivers

We can do this by either passing them all to .to:

.to (myFirstReceiver, mySecondReceiver)

or calling .to multiple times.

myTask.to (myFirstReceiver);
myTask.to (mySecondReceiver);

Unsubscribing receivers

If you need, you can later unsubscribe a receiver function by calling .unsubscribe on the task and passing the function/s to that.

myTask.unsubscribe (myFirstReceiver);

myTask.unsubscribe (myFirstReceiver, mySecondReceiver);

Events

Receivers can send events back to the task, this is useful, for example, when a platform has posted some content and it needs to send back the post ID and whatnot.

const simpleTask = new alpha.Task ()
	.to ((arg, sendEvent) => {
        console.log (arg);
        sendEvent ('customEvent', 'Successfully console.log-ed the action object')
    })
	.do (actionObject => {
        actionObject.done ();
    })
	.onEvent ('customEvent', data => {
        console.log (data); //"Successfully console.log-ed..."
    });
	.every (5).minute ()
	.start ();

A task can have multiple event listeners, depending on what the function/s and platform/s passed to .to send back.

Naming a task

Tasks can be given names by calling .name (str: String) on them, which will set their .displayName and ._id to that string. This is especially useful when using the @alpha-manager/web-interface.

Platforms

Currently, the only official platform implementation is the @alpha-manager/fb module, which is a feature-rich wrapper for the Facebook API that can be passed as a receiver function, you can read more about it on its NPM/GitHub page.

Creating a platform (advanced)

If you wish to extend Alpha and create wrappers for different social media networks, you can do so by extending the Platform class.

For example:

(Twitter doesn't have a module yet, but it should in the future).

const alpha = require ('alpha');

class Twitter extends alpha.Platform {
    constructor () {
        super ();
        this.name = "Twitter"; // used by the web interface, can be left blank but it is recommended to give your platform a name
        this.requiredConfigs = {
            consumer_key: 'string', // can be any type supported by `typeof` OR 'any'
            consumer_secret: 'string',
            access_token_key: 'string',
            access_token_secret: 'string'
        }
    }
    onConfig (obj) {
        // do something with the config object
    }
    execute (actionObject, sendEvent) {
        // this is called everytime the task runs, do something with the action object
        // that the user created and called `.done ()` on in `.do ()`
        // you can also send events to the task by using the sendEvent function,
        // for example: sendEvent ('error', 'something bad happened');
    }
}

// then the user can just do

const twitterPlatform = new Twitter ().config ({
    consumer_key: '',
    consumer_secret: '',
    access_token_key: '',
    access_token_secret: ''
});

const myTask = new alpha.Task ()
	.to (twitterPlatform)
	.do (obj => {
        obj.done ();
    })
	.every (5).minutes ()
	.start ();

For the full experience, I recommend you check out the other modules

• Check out @alpha-manager/web-interface, a web interface that allows you to manage your tasks from any device, using a visual interface
• Check out the @alpha-manager/fb module, which is a feature-rich wrapper for the Facebook API that can be passed as a receiver function

Also, you are more than welcome to contribute and create your own modules that work with Alpha!