Barrel JS

Note: This is an alpha preview

Barrel JS is a minimal, event-driven framework for Node to build microservices and integrations.

The goal of the project is to provide a simple way to build integrations with external API services, enabled by an event driven architecture.

These are the principles:

• Messages: Messages are JSON objects. They can have any internal structure you like. Messages can be received via HTTP/S or through internal dispatchers. You just listen and act on messages you care about.
• Pattern matching: Instead of parsing each message or request, you just define which parts of a message you care about.
• Service oriented: You can send messages through services, separating your business logic from message parsing.
• Extensibility: Functionality is expressed as a set of plugins which can be composed together as microservices. (TBD)

Install

NPM

npm install @barreljs/core

Yarn

yarn add @barreljs/core

Getting started

const Barrel = require('@barreljs/core')

const barrel = new Barrel()

barrel.start()

This will spin up a route on <your-host>:3141/barrel that accepts valid JSON POST requests. You can configure this by passing a configuration object to the constructor.

To capture incoming requests, you can create listeners that filter the body based on the listener's pattern and execute a given function.

barrel.on({action: "name"}, async ({ values, ack }) => {
    console.log('values containing action property "name"', values)

    // sends an empty 200 response
    done()
})

barrel.on({action: /^action-\w*$/}, async ({ values, ack }) => {
    console.log('values containing action property matching the given RegEx', values)

    // sends an empty 200 response
    done()
})

Alternatively you can use any valid JSONPath Plus selector as a pattern.

barrel.on('$..city', async ({ values, ack }) => {
    console.log('values containing city property', values)

    // sends an empty 200 response
    done()
})

Services

Services can execute requests or actions. Each service requires a unique name property and either an actions or requests object. Requests execute HTTP requests to other services. Actions are just normal funtions that will be executed. Each service can contain requests and actions, but all properties within those two objects must be unique.

const service = {
        name: 'weather',
        requests: {
            search: (city) => ({
                method: 'GET',
                url: 'https://www.metaweather.com/api/location/search',
                params: {
                    query: city
                }
            }),
            get: (id, city) => ({
                method: 'POST',
                url: `https://www.metaweather.com/api/location/${id}`,
                data: {
                    city: city
                }
            })
        },
        actions: {
            average: (temp1, temp2, temp3) => {
                return (temp1+temp2+temp3)/3;
            }
        }

    }

These services can be registered in a Barrel

barrel.register(service)

// or if you have multiple services in an array
barrel.registerAll([service])

and executed using the service's name and action or request identifier

const result = await barrel.execute('weather.search', 'san francisco')

//or
const average = await barrel.execute('weather.average', 67.11, 34.25, 88.91)

Request

Requests are a function that return a valid request object.

| Property | Type | Required | Description | | ---- | ---- | ---- | ---- | | method | String | Yes | Any valid HTTP method | | url | String | Yes | A valid url | | params | JSON | No | An object that is converted into URL parameter | | data | JSON | No | An object that is converted into a JSON body | | urlencoded | Boolean | No | Indicates that a request should be send as application/x-www-form-urlencoded instead of application/json if set to true |

Action

Actions are simple functions wrapped in a service.

Configuration

The constructor accepts a configuration object with following properties. These are the defaults:

{
    method: 'POST', // any valid HTTP method
    port: 3141, // a valid port number
    route: '/barrel', // the route for incoming requests
    middlewares: [], // an array of middlewares to run for each incoming request
    bodyParser: bodyParser.json(), // body-parser
    debug: false, // true or false
}

Methods

.start()

Starts the barrel server.

.on(pattern, callback)

Creates a listener for incoming requests.

| Property | Type | Description | | ---- | ---- | ---- | | pattern | JSON or String (JSON Path Plus expression) | The pattern to match incoming JSON payloads or dispatchers | | callback | Function | A function that is executed when an incoming requests matches the pattern |

callback

The callback function receives an object with following properties:

| Property | Type | Description | | ---- | ---- | ---- | | values | Object | A values object including the values matching the pattern | | context | Object | A context object that was passed down from a dispatcher | | message | Object | The original message | | done | Function | A function that returns a 200 HTTP response in case that listener was executed in the context of an HTTP request |

values object

The values object has following properties:

| Property | Type | Description | | ---- | ---- | ---- | | all() | Array | Returns an array of all values | | first() | Object | Returns the first value | | last() | Object | Returns the last value | | get(index) | Function | Returns the entry at given index or false | | length | Int | Number of matching values |

Example

barrel.on({id: '$any'}, ({values, context, done}) => {
    console.log(values.all())
    console.log(context)
    done()
})

.error(callback)

Custom error handler

| Property | Type | Description | | ---- | ---- | ---- | | callback | Function | A function that is executed when an error occurs |

Example

barrel.error((error) => {
    console.error(error)
})

register(service)

Registers a valid service object.

| Property | Type | Description | | ---- | ---- | ---- | | service | Object | A valid service object |

Example

barrel.register({... a valid service object ...})

registerAll(services)

Registers an array of services.

| Property | Type | Description | | ---- | ---- | ---- | | services | Array | An array of valid service objects |

Example

barrel.registerAll([{... a valid service object ...}])

act(action, ..args)

Executes an action defined in a service object.

| Property | Type | Description | | ---- | ---- | ---- | | action | String | An action identifier for a service action, e.g. weather.average | | ...args | Arguments | Any number of arguments passed down to the action or request |

Example

barrel.act('weather.average', 67.11, 34.25, 88.91)

call(request, ..args)

Executes a request defined in a service object.

| Property | Type | Description | | ---- | ---- | ---- | | request | String | A request identifier for a service request, e.g. weather.search | | ...args | Arguments | Any number of arguments passed down to the action or request |

Example

barrel.call('weather.search', 'san francisco')

dispatch(msg, context)

Dispatches a message object that matches a pattern of a listener.

| Property | Type | Description | | ---- | ---- | ---- | | msg | String or JSON | A message object that triggers a listener of a matching pattern | | context | JSON | An object that is passed down to the given listener as context |

Example

barrel.dispatch({action: "name"}, {dispatcher: true})

License

MIT. See license.