ozone-service

The Node.js service library for Ozone (Node 8+)

What is it

In principle, this package acts as an asynchronous wrapper for the Ozone package. It's goal is to provide the ability to modify and update it's instance based on external intents and state updates.

Learn more about Ozone

Installation

Before installing, make sure your system is qualified to use the Ozone subsystem by checking out the Ozone readme. In short, as long as you are running a modern Unix-like operating system or environment, Ozone should be able to run.

To use the ozone service package, install this as a dependency for your npm project

npm (latest)

npm i -S @o3/service

git (latest)

git clone https://github.com/flynnham/ozone-service.git

Usage

Pre-configure

Be sure to configure Ozone to recognize your service otherwise it won't be loaded.

Initialization

Assuming a live Ozone core instance is running, the first step to starting an Ozone service is to await the ozone service initializer.

Example

const ozoneService = require('@o3/service/init');

// Because we are using async we need to (unfortunately) wrap the context in order to use it
(async function(){
	// Let's attempt to start the service
	const service = await ozoneService();

	// now that the service is running, let's include the base state and intents
	const { state, intent } = require('@o3/service');

	// tell the core we are ready (needs to be ready before any intents are recieved)
	await state.ready();
})();

Full examples avaliable here

The above code will do the absolute minimum required to start a properly configured Ozone service. Once we know it's been configured we can start sending intents and working with the multi-instance state.

State

async state.ready()

Waits for the core to signal that services are now ready

state.addListener(name, callback(state))

Adds a listener to the core global context. Each listener should have a unique name so it can be remved when needed.

state.removeListener(name)

Removes a state listener by name

state.update(key, mutator function(currentState))

Updates the state specified by the key. Mutator is a function that must return a modified or new version of the old state. Key must exactly match the state attribute defined with the service configuration.

Intent

intent.send([ name, data || {} ],...)

Sends a list of intentions all with their own unique set of data. This arrives to the core as a bundle and are processed as such. Data must be of type Object

intent.addListener(intent, callback(data))

Listens for a properly configured intention and will run based on the code. In future versions, name will also be of type Array, allowing for multiple listeners.