@nxus/core
\
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.- Getting Started (TODO)
- Design Patterns (TODO)
- Nxus Modules (TODO)
- Recipes (TODO)
- Developing a (TODO)
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:init
: indicates the application is starting up and initializing modules. Other modules are not gauranteed to be available at this phase.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.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).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:- @nxus namespaced npm modules in your
package.json
file. - Any packages that match the 'namespace-' pattern passed in the
namespace
application config option. - folders in the ./modules folder in the root of your project
- 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 DispatcherThe 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:- Packages in node\_modules that match the passed
namespace
config option, and packages in the@nxus
namespace. - Folders in the /modules directory.
- Filepaths passed in the
modules
config option
accumulatePackage
Creates the internal representation of a packageParameters
packages
array the list of active packages being loaded by Nxusdirectory
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 directoryParameters
options
object configuration optionspackages
loadPackage
Loads a packageParameters
name
string The name of the packagedirectory
packages
loadPackages
Loads all Nxus pacakges for an applicationParameters
options
object options to use to load the packagespackages
loadPassedPlugins
Loads manually passed in packages by pathParameters
options
object configuration optionspackages
Dispatcher
Extends EventEmitterThe 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 tolistener
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 tolistener
emit
Emits an event, calling all registered handlers.Parameters
event
string The name of the event to emit.args
Returns Promise Returns a promise that resolves when all handlers have completed, with any returned results as an array.
once
Bind to an event onceParameters
event
string The name of the event to bind tolistener
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 tolistener
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 tolistener
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):- Opts loaded into the application object.
- Opts in the
config
hash of the project package.json file - 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 variablesReturns object A hash of the current environment variables
getNodeEnv
Returns the current NODE\_ENVReturns string the current NODE\_ENV
getPackageJSONConfig
Gets the local package.json file and tries to find an internalconfig
keyReturns object the intenral
config
object or an empty object if it isn't defined.Module
Extends DispatcherThe 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 providesParameters
name
string The name of the gather eventargs
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 eventhandler
provide
Provide arguments to a delayed gather() call.Parameters
name
string The name of the gather eventargs
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 eventargs
Returns Promise Resolves when the event is eventually handled
request
Request the result of processing a named eventParameters
name
string The name of the request eventargs
Returns Promise Resolves to the result of the event's handler
respond
Respond to a named eventParameters
name
string The name of the request eventhandler
use
Let another instance use this module's events to reduce boilerplate callsParameters
instance