@slimio/addon v0.22.1

Addon

This package provide the foundation to build Addons that will rely and work with the Core. Addon is just a container that will help you as a developer.

Scheduler is a external SlimIO Package. If you want to know more about it, follow this link.

Requirements

• Node.js v10 or higher

Getting Started

This package is available in the Node Package Repository and can be easily installed with npm or yarn.

$ npm i @slimio/addon
# or
$ yarn add @slimio/addon

👀 For a guide on how create/setup a first addon, please check available documentations in our Governance repository.

Usage example

A sample cpu addon.

const Addon = require("@slimio/addon");

// Create addon
const CPU = new Addon("cpu");

// Register a callback
CPU.registerCallback(async function say_hello(name) {
    console.log(`hello ${name}`);
});

// Catch start event!
CPU.on("start", async() => {
    console.log("cpu addon started!");

    // Execute local callback
    await CPU.executeCallback("say_hello", void 0, "thomas"); // stdout "hello thomas";

    // Tell the core that your addon is ready!
    CPU.ready();
});

// Export addon for SlimIO Core.
module.exports = CPU;

You might find it useful to read the source codes of our other addons, let us give you some nice links:

Available events

Addon is extended with a SlimIO Safe EventEmitter. Six kinds of events can be triggered:

An addon have different given state during his life (started, awaken and ready). An addon is started when the core has recognized its existence and that it has been loaded successfully. The state ready have to be triggered by the developer itself in the start or awake event depending the need.

An addon wake up when all its dependencies are ready. A dependency can be added with the lockOn() method.

const myAddon("test").lockOn("events");

myAddon.on("awake", async() => {
    // Do something with events safely!
    const info = await myAddon.send("events.status");
});

Interval & Scheduling

The Addon instanciate is own interval to execute Scheduled callbacks. The default interval time is setup at 500 milliseconds. To know how work the walk() method of Scheduler, please look at this documentation.

You can configure the default interval by editing static Addon variables (this is not recommanded):

Addon.MAIN_INTERVAL_MS = 100; // 100ms

A concrete production example is to schedule a callback every 24 hours that start at midnight (but this callback can still be triggered manually by calling the callback).

const myAddon = new Addon("myAddon");

let isCalled = false;

async function ourJob() {
    isCalled = true;
    try {
        await new Promise((resolve) => setTimeout(resolve, 10000));
    }
    finally {
        isCalled = false;
    }
}

async function scheduledCallback() {
    if (isCalled) {
        return { error: "Job already running!" }
    }

    ourJob().catch((err) => myAddon.logger.writeLine(err));
    return { error: null };
}

myAddon
    .registerCallback(scheduledCallback)
    .schedule(new Scheduler({ interval: 86400, startDate: new Date(new Date().setHours(24, 0, 0, 0)) }));

API

Create a new Addon with a given name ! The name length must be more than two characters long. Available options are:

const myAddon = new Addon("myAddon", {
    version: "0.1.0",
    verbose: true,
    description: "My Custom Addon!"
});

Flag the addon as ready for the core.

const myAddon = new Addon("myAddon");

myAddon.on("start", () => {
    myAddon.ready();
})

Register a new Addon callback. The callback should be an Asynchronous Function (Synchronous function will be rejected with a TypeError).

There is two ways to register a callback:

myAddon.registerCallback("callback_name", async function() {
    console.log("callbackName has been executed!");
});

Please, be sure to avoid Anonymous function as much possible!

Or by passing the callback reference as the name (The function can't be anonymous, else it will throw an Error).

async function callback_name() {
    console.log("callbackName has been executed!");
}
myAddon.registerCallback(callback_name);

Callback name should be writted by following the snake_case convention snake_case !

Execute a callback (It will return a Promise). The method can take infinity of arguments (they will be returned as normal arguments of the callback).

const myAddon = new Addon("myAddon");

myAddon.registerCallback(async function cb_test() {
    return "hello world!";
});

myAddon.on("start", async function() {
    const ret = await myAddon.executeCallback("cb_test");
    console.log(ret); // stdout "hello world!"
});

Schedule a callback execution interval. Use the package @slimio/scheduler to achieve a scheduler !

const Scheduler = require("@slimio/scheduler");
const Addon = require("@slimio/addon");

const myAddon = new Addon("myAddon");

myAddon.registerCallback(async function sayHelloEveryOneSecond() {
    console.log("hello world");
});
myAddon.schedule("sayHelloEveryOneSecond", new Scheduler({ interval: 1 }));

Setup a list of deprecated alias for a given callbackName. A NodeJS Warning will be throw if these alias are used (to warn developer/integrator to upgrade addon version).

const myAddon = new Addon("myAddon");

myAddon.registerCallback(async function new_test() {
    console.log("hello world!");
});
myAddon.setDeprecatedAlias("new_test", ["old_test"]);

Wait for an addon to be declared "ready" to awake local Addon. Rules argument is an Object described as follow:

export interface Rules {
    startAfter?: boolean;
    lockCallback?: boolean;
}

The default rule values are defined as: { startAfter = true, lockCallback = false }

• startAfter: Ask our local addon to start after the given addonName.
• lockCallback: Lock callback execution when our local addon is not awake.

const myAddon = new Addon("myAddon").lockOn("events");

myAddon.on("awake", () => {
    console.log("events is ready!");
    myAddon.ready();
});

Subscribe to a given subject. Available "core" Subjects are:

interface Subjects {
    Addon: {
        readonly Ready: string;
    };
    Alarm: {
        readonly Open: string;
        readonly Update: string;
        readonly Close: string;
    };
    Metrics: {
        readonly Update: string;
    }
}

const myAddon = new Addon("myAddon");

myAddon.of(Addon.Subjects.Addon.Ready).subscribe((addonName) => {
    console.log(`Addon with name ${addonName} is Ready !`);
});

Send a lazy message to a given target formatted as following: addon.callback. The returned value is an Observable (package zen-observable).

const myAddon = new Addon("myAddon");

myAddon.on("start", function() {
    myAddon
        .sendMessage("cpu.status")
        .subscribe(console.log);
    myAddon.ready();
});

Available options are:

Send one lazy message to a given target formatted as following: addon.callback. The returned value is a Promise (Use sendMessage under the hood).

const myAddon = new Addon("myAddon");

myAddon.on("start", async function() {
    const addons = await myAddon.sendOne("gate.list_addons");
    console.log(addons);

    myAddon.ready();
});

Available options are the same as sendMessage(). If options is an Array, the message options will be constructed as follow

{ args: [] }

Register a driftless timer interval that will be managed by the Addon itself. These intervals are only executed when the addon is awake. These functions (intervals) are protected against UnhandledPromiseRejection (so any errors will not lead the process to exit).

Intervals are erased when the stop event is triggered to avoid excessive use of memory (So think to register these intervals in the start event).

const myAddon = new Addon("myAddon").lockOn("otherAddon");

async function myInterval() {
    console.log("Hey ! I'm awake and will be executed every 5 seconds");
}

myAddon.on("start", () => {
    myAddon.registerInterval(myInterval, 5000);
});

The method registerInterval return a unique id which can be used to retrieve the original Node.js timer etc...

const uid = myAddon.registerInterval(myInterval, 5000);

const { ms, callback, nodeTimer } = myAddon.intervals.get(uid);
nodeTimer.unref()

Static method

isAddon(obj: any): boolean

Detect if obj is an Addon (use a Symbol under the hood).

const myAddon = new Addon("myAddon");

console.log(Addon.isAddon(myAddon)); // true

Streaming Communication

SlimIO Callback support NodeJS Write Streams. Take the following example:

const streamAddon = new Addon("streamAddon");

streamAddon.registerCallback(async function stream_com() {
    const WStream = new Addon.Stream();
    setTimeout(() => {
        WStream.write("msg1");
    }, 100);
    setTimeout(() => {
        WStream.write("msg2");
        WStream.end();
    }, 200);
    return WStream;
});

module.exports = streamAddon;

And now if we call this callback from an another Addon:

const myAddon = new Addon("myAddon");

myAddon.on("start", () => {
    myAddon.ready();
});

myAddon.on("addonLoaded", (addonName) => {
    if (addonName === "streamAddon") {
        myAddon.sendMessage("streamAddon.stream_com").subscribe(
            (message) => console.log(message),
            () => console.log("Stream completed!")
        )
    }
});

Dependencies

License

MIT