@nxus/core

A framework for building light-weight, event-driven data processing apps.

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
@nxus/core
0202.4.0-98 years ago9 years agoMinified + gzip package size for @nxus/core in KB

Readme

@nxus/core

\

Build Status
The Nxus Core package includes the basic Application framework for building a Nxus app.

Introduction

You'll probably find the following resources useful background and help in building Nxus applcations.

Documentation

The full set of Nxus docs is available at .

Installation

> npm install @nxus/core --save

Usage

In your root application, create a new Application instance:
import {Application} from '@nxus/core'

let app = new Application(options)

app.start()

export default app

Events

Nxus is built around the concept of a boot cycle. The application dispatches events in the following order:
  1. init: indicates the application is starting up and initializing modules. Other modules are not gauranteed to be available at this phase.
  2. load: modules are initialized and loading. This is the place to do any internal setup (outside of the constructor). Other modules are not gauranteed to be available at this phase.
  3. startup: all modules have been loaded and are available. This is the place to do any setup that requires data/input from other modules (like Storage).
  4. launch: the application is launching and all services have been started. Routes are accessible. Use onceAfter('launch') to gaurantee execution after the application has completely launched.

Module Loading

By defaul the Application will look for other Nxus modules in the following order:
  1. @nxus namespaced npm modules in your package.json file.
  2. Any packages that match the 'namespace-' pattern passed in the namespace application config option.
  3. folders in the ./modules folder in the root of your project
  4. any modules specified in the modules option passed into Application on instantiation.

Module Access

In order to access module commands, use the Application.get() method.
let router = Application.get('router')

Application Configuration Options

Available options are:
appDir: the location to use to load the default 'package.json' file.
namespace: any additional namespaces to use to load modules in the node\_modules folder. Can be a string or array of strings.
modules: an array of paths to require into the application
debug: Boolean to display debug messages, including startup banner
script: Boolean to indicate the application is a CLI script, silences all logging/output messages except for explicit console.log calls

API

Application

Extends Dispatcher
The Core Application class.
Parameters
  • opts Object the configuration options

Examples
import {Application} from '@nxus/core'
let app = new Application(options)
app.start()
export default app

boot

Boots the application, cycling through the internal boot stages.
Note: Should rarely be called directly. Instead use #start
Returns Promise

get

Returns an internal Module object for the given name.
Parameters
  • name string The name of the module to return

Returns
Module

init

Initializes the application by loading plugins, then booting the application.
Note: this should rarely be called directly. Instead use #start
Returns
Promise

restart

Restarts the Nxus application.
Returns
Promise

start

Starts the Nxus application.
Returns
Promise

stop

Stops the currently running application, removing all event listeners.
Returns
Promise

PluginManager

The PluginManager handles all of the module loading. Load order is as follows:
  1. Packages in node\_modules that match the passed namespace config option, and packages in the @nxus namespace.
  2. Folders in the /modules directory.
  3. Filepaths passed in the modules config option

accumulatePackage

Creates the internal representation of a package
Parameters
  • packages array the list of active packages being loaded by Nxus
  • directory
string the directory of the new package to load
Returns object the package, as returned by require

arrayify

Helper method to ensure a passed variable is an array. Wraps the value in an array if it isn't already.
Parameters
  • el anything the item to ensure is an array

Returns
Array either a new empty array, or el as is if its an array, or el wrapped in an array.

getDeps

Loads the dependencies for a particular package, as defined by the 'dependencies' object in the package.json file.
Parameters
  • pkg object the package object generated by accumulatePackage()

Returns
array an array of the package's dependencies, as filepaths or node\_module names

getPluginPackageJson

Loads the package.json file for the specified packages.
Parameters
  • path string the root package folder path

Returns
object the parsed json object in package.json

loadCustomPlugins

Loads custom plugins in the /modules directory
Parameters
  • options object configuration options
  • packages
packages the array of packages currently loaded by Nxus

loadPackage

Loads a package
Parameters
  • name string The name of the package
  • directory
string A path to the package
  • packages
  • array An array of the currently loaded packages

    loadPackages

    Loads all Nxus pacakges for an application
    Parameters
    • options object options to use to load the packages
    • packages
    packages the array of packages currently loaded by Nxus

    loadPassedPlugins

    Loads manually passed in packages by path
    Parameters
    • options object configuration options
    • packages
    packages the array of packages currently loaded by Nxus

    Dispatcher

    Extends EventEmitter
    The core Dispatcher class, which implements promisified
    Examples
    import { Dispatcher } from '@nxus/core'
    class MyClass extends Dispatcher {
      ...
    }

    after

    Bind to after an event. Receives the event handlers results, should return modified results or nothing.
    Parameters
    • event string The name of the event to bind to
    • listener
    callable The after handler for the event

    before

    Bind to before an event. Receives the event arguments, should return modified arguments or nothing.
    Parameters
    • event string The name of the event to bind to
    • listener
    callable The before handler for the event

    emit

    Emits an event, calling all registered handlers.
    Parameters
    • event string The name of the event to emit.
    • args
    ...Any Arguments to the event handlers
    Returns Promise Returns a promise that resolves when all handlers have completed, with any returned results as an array.

    once

    Bind to an event once
    Parameters
    • event string The name of the event to bind to
    • listener
    callable= The handler for the event
    Returns Promise Returns a promise that resolves when the event fires

    onceAfter

    Bind once to after an event. Receives the event handlers results, should return modified results or nothing.
    Parameters
    • event string The name of the event to bind to
    • listener
    callable The after handler for the event
    Returns Promise Returns a promise that resolves when the event fires

    onceBefore

    Bind once to before an event. Receives the event arguments, should return modified arguments or nothing.
    Parameters
    • event string The name of the event to bind to
    • listener
    callable The before handler for the event
    Returns Promise Returns a promise that resolves when the event fires

    ConfigurationManager

    ConfigurationManager loads the internal app.config hash using the following order (each overwrites any values of the previous):
    1. Opts loaded into the application object.
    2. Opts in the config hash of the project package.json file
    3. Any environment variables

    getConfig

    Returns the final config option using the loading order described above.
    Returns
    object the final composed configuration object.

    getEnvironmentVariables

    Extracts the currently avaiable environment variables
    Returns
    object A hash of the current environment variables

    getNodeEnv

    Returns the current NODE\_ENV
    Returns
    string the current NODE\_ENV

    getPackageJSONConfig

    Gets the local package.json file and tries to find an internal config key
    Returns
    object the intenral config object or an empty object if it isn't defined.

    Module

    Extends Dispatcher
    The core Module class. This provides a messaging proxy layer between modules and calling code. The main advantage of this proxy class is that missing modules won't cause exceptions in the code.
    Modules are accessed through the Application.get() method
    Examples
    let router = app.get('router')
    
    Producer modules should register themselves with the use() method, and define gather() and respond() handlers:

    app.get('router').use(this).gather('route')

    app.get('templater').use(this).respond('template')
    
    Consumer modules should get the module they need to use and call provide or request

    app.get('router').provide('route', ...)

    app.get('templater').request('render', ...)
    
    Modules proxy event names as methods to provide/request, so these are synomymous with above:

    app.get('router').route(...)

    app.get('templater').render(...)
    
    Default implementations should be indicated by using default() to occur before provide()
    Overriding another implementation can use replace() to occur after provide()

    app.get('router').default('route', GET', '/', ...)

    app.get('router').replace('route', GET', '/', ...)
    
    Provide, default, and replace all return a proxy object if called with no arguments, so these are synonymous with above:

    app.get('router').default().route('GET', '/', ...)

    app.get('router').replace().route('GET', '/', ...)

    default

    Provide default arguments to a delayed gather() call, before other provides
    Parameters
    • name string The name of the gather event
    • args
    ...Any Arguments to provide to the gather event
    Returns Promise Resolves when the event is eventually handled

    gather

    Receive arguments provided to a delayed gather() call.
    Parameters
    • name string The name of the gather event
    • handler
    callable The handler for each provided value

    provide

    Provide arguments to a delayed gather() call.
    Parameters
    • name string The name of the gather event
    • args
    ...Any Arguments to provide to the gather event
    Returns Promise Resolves when the event is eventually handled

    replace

    Provide a replacement for a delayed gather() call (after others are provided)
    Parameters
    • name string The name of the gather event
    • args
    ...Any Arguments to provide to the gather event
    Returns Promise Resolves when the event is eventually handled

    request

    Request the result of processing a named event
    Parameters
    • name string The name of the request event
    • args
    ...Any Arguments to provide to the responder
    Returns Promise Resolves to the result of the event's handler

    respond

    Respond to a named event
    Parameters
    • name string The name of the request event
    • handler
    callable The handler for the request

    use

    Let another instance use this module's events to reduce boilerplate calls
    Parameters
    • instance

    Watcher

    The Watcher class monitors the project directory and restarts the application whenever there is a change in files detected. Useful for development.