README

Abstractor

Node.js abstraction layer and automation framework.

Introduction
- Messages
- Nodes
- Examples
- Installation
  - Dependencies
- Debugging
Documentation
- Built in nodes
  - Cache
  - Cron
  - CSV
  - Delay
  - Exec
  - File-read
  - File-watch
  - File-write
  - Generic
  - Heartbeat
  - HTML Parser
  - HTTP Client
  - HTTP Server
  - JSON
  - Junction
  - Kill
  - Mail
  - Map
  - MQTT
  - MSSQL
  - MySQL
  - Retry
  - Split
  - Strip
  - Sun
  - Telldus device
  - Telldus sensor
  - Template
  - Websocket Server
  - Websocket Client
  - Queue
- Third party nodes
License

Introduction

The basic idea behind abstractor is that more or less standardised messages is passed between nodes to form an application.

Messages

A message normally consist of a topic and a payload, but can have any number of additional attributes depending on which node it has passed, or will pass.

When writing simple applications, you won't have to fiddle with messages manually. They will silently pass between the nodes you set up.

As an example, a message originating from the MQTT-node will look something like this ...

{
    topic: "indoor/livingroom/roof/lights",
    payload: "on",
    qos: 2,
    retain: false
}

... and a message on it's way to the file-write node will look like this ...

{
    path: "~/abstractor.log",
    flag: "a", 			// "a" == append, "w" == overwrite
    payload: "This will be appended to abstractor.log"
}

Both path and flag can be set at node level too, see next section.

Nodes

Nodes are essentially customized functions, which are designed to execute a specific task as efficiently and transparent as possible.

Some nodes can both receive and emit messages. One such example is the json node, which converts the payload to a json string if it is a javascript object and vice versa.

The nodes connect to each other through pre-defined events, most nodes emit "success" or "failure" on completion. See the documentation for information on what each node can emit.

Examples

To put it all together, an example that continously tail a file on changes and output the last 10 rows to the console.

var

    // Initialize abstractor
    abstractor = require("abstractor"),
    
    // Create node factory
    factory = abstractor()

    // Create nodes
    
    // - Create instance of file-watch node, tell the node to monitor `/var/log/syslog`
    //   This node will emit "success" every time the file changes
    watchNode = 	factory( "file-watch", { path: '/var/log/syslog' }),
    
    // - Create a file-read node, tell it to only read the last 10 rows.
    //   On completion, "success" will be emitted.
    readNode = 		factory( "file-read", { tail: 10 }),
    
    // - In this example, we create a generic node (function wrapper) that just print the payload
    //   to the console.
    outputNode = 	factory( "generic", function (msg) { console.log(msg.payload); });

// Ok, the building blocks is ready, we just got to stack them up.
watchNode.on("success", readNode);
readNode.on("success", outputNode);

More examples available at /examples

Installation

The simplest way to get Abstractor is through npm. Simply run the following in your command line from your project folder.

npm install abstractor

Dependencies

Abstractor itself has very few dependencies. However, certain embedded modules dynamically includes third party libraries. As an example, The telldus modules need http://github.com/hexagon/telldus to work.

The framework will raise an run time error if it is missing an dependency.

Debugging

logLevel

The logger has 5 levels of verbosity

0 = Silent
1 = adds errors
2 = adds warnings
3 = adds logs
4 = adds notices (default)
5 = adds full message for each invoke

Default mode (4) outputs a timestamped log everytime a node triggers a message.

var

    // Initialize abstractor
    factory = require('abstractor')({logLevel: 4}),

// ...

Will result in something like ...

[2016-10-02 21:50:12] CORE > Abstractor ready
[2016-10-02 21:50:12] CORE > Imported node json on the fly.
[2016-10-02 21:50:12] CORE > Imported node file-write on the fly.
[2016-10-02 21:50:12] CORE > Imported node file-read on the fly.
[2016-10-02 21:50:12] JSON > success
[2016-10-02 21:50:12] FILEWRITE > success

For more; see examples/ folder.

Documentation

Below is just a brief description of each of the nodes. For in-depth documentation, see the source files at /lib/nodes/.

Built in nodes

Cache

In memory key/value storage, great for storing the last payload of a specific topic.

Usage no npm install needed!

README

Abstractor

Introduction

Messages

Nodes

Examples

Installation

Dependencies

Debugging

logLevel

Documentation

Built in nodes

Cache

Cron

CSV

Delay

Exec

File-Read

File-Watch

File-Write

Generic

Heartbeat

HTML Parser

HTTP Client

HTTP Server

JSON

Junction

Kill

Mail

Map

MQTT

MSSQL

MySQL

Retry

Split

Strip

Sun

Telldus device

Telldus sensor

Template

Websocket Server

Websocket Client

Queue

Third party nodes

License