The Seneca API is pretty tiny. We try hard to keep any non-essential functionality out of core. Instead, we push it out to plugins. The core API is documented below. If you have any further questions, get in touch. We love to talk!
Creates a new instance of Seneca with the provided options.
Optional. The options you wish to provide to the instance of seneca being created. When no options are provided the defaults in the usage section below are provided.
var Seneca = require('seneca')
var seneca = Seneca({
tag: 'some-name',
timeout: 500,
log: 'silent',
debug: {
undead: false,
short_logs: false,
},
strict: {
result: true,
add: false,
find: true,
maxloop: 11
}
})
var Seneca = require('seneca')
var instanceA = Seneca()
var instanceB = Seneca()
require('seneca')
.use('entity')
.client({pin: 'cmd:start', port: 4300})
.listen()
options.tag
is '-'
.options.timeout
is ``options.log
is ``The close method gracefully closes Seneca. An optional callback can be provided to check for completion and handle any errors that occur during gracefully closing.
A callback that is fired when .close
is complete. If an error occurred during close it
will be provided to you in the callback you supply.
var seneca = require('seneca')
seneca.close((err) => {
if (err) console.log(err)
else console.log('close complete!')
})
…
The .act
method sends a given message to any interested handlers. The message sent is
‘matched’ by 1 or more handlers and a reply may or may not be returned. A message is
processed is based on the transport mechanism used to send it.
The message you wish to send over seneca’s transport pipeline. Alternatively, if using
Jsonic, this param will be merged with the payload
param to form the complete message.
Optional. An object payload to handle cases where Jsonic strings are used.
Optional. When an act is fired the handler can optionally respond. To handle this reply
provide a callback function with the signature function (err, reply)
. If no callback
is provided Seneca will simply discard the reply.
seneca.act(data)
seneca.act(data, (err, reply) => {
if (err) console.log(err)
else console.log(reply)
})
seneca.act('role:store,cmd:update', data)
seneca.act('role:store,cmd:save', data, (err, reply) => {
if (err) console.log(err)
else console.log(reply)
})
…
The .add
method allows handlers to be added to an instance of Seneca for the purposes
of processing messages. Messages are matched against the pattern
param and optionally
validated using the spec
param. Handlers must call done but do not have to provide a
return value if one does not make sense.
The pattern to filter the handler to; only messages which match the pattern provided will be passed to the handler. The pattern can be a plain object or JSonic string.
Optional. A parambulator spec object for validating the matched message. Messages that do not match are rejected with an error returned to the caller if applicable.
The handler that processes the message. Messages are provided as plain objects via the
msg
param. When processing is complete or errors the done
callback can be used to
complete execution. The signature for done
is function (err, reply)
.
…
…
The .has
method will return a true or false depending on wether or not the provided
pattern has a matching handler. Has will also emit true if a pattern has been pinned
via a .client()
.
The pattern to verify against. The input can be either a plain Javascript object or a JSonic string. It does not matter if a string or object was used when adding the handler.
'use strict'
var seneca = require('seneca')()
seneca.add('some:pattern', (msg, done) => {done()})
console.log(seneca.has('some:pattern'))
console.log(seneca.has({some:'pattern'}))
// Output:
// true
// true
'use strict'
var seneca = require('seneca')()
seneca.client({pin: 'some:pin'})
console.log(seneca.has('some:pin'))
// Output:
// true
.listen
will not match to true, since they are used as a filter.true
does not ensure a successful call, only that a handler is known.The .sub
method allows the ability to listen for any messages that are emitted in the
local Seneca instance. It provides a way to listen for the message sent, not the result
of that message.
The pattern to match against for the provided handler.
…
…
…
The .listen
methods creates a listener that can handle messages external from external
sources. By default HTTP is used but both transport and related options can be set via
the options
param.
The options used to decide which underlying transport to use. Additional options in this object will be passed on to the chosen transport.
…
…
The .client
methods creates a client that can send messages to external sources. By
default HTTP is used. Transport type and other options can be set by passing an object
via the options
param.
The options used to decide which underlying transport to use. Additional options in this object will be passed on to the chosen transport.
seneca.listen({
type:
})
seneca
.listen({type: 'tcp', port: '3060', pin: 'role:supplier'})
.listen({type: 'http', port: '3060', pin: 'role:supplier'})
options.type
is HTTP
.options.port
is 101010
.options.pin
can be a JSonic string or plain object.The .use()
method provides the ability to load plugins into seneca. Plugins are the
primary method of composition in Seneca and should be used liberally.
…
…
…
…
The .ready()
method fires the provided callback every time a set of plugins has been
loaded. Ready will only fire if one or more plugins are loaded. Multiple calls are
supported.
The callback to execute when a set of plugins have been loaded. Any errors raised during
plugin loading will be reported to the callback via the err
param.
'use strict'
var seneca = require('seneca')()
function a () {console.log('plugin 1')}
function b () {console.log('plugin 2')}
seneca.use(a)
seneca.use(b)
seneca.ready(function (err) {
if (err) process.exit(1)
console.log('ready fired')
})
'use strict'
var seneca = require('seneca')()
function a () {console.log('plugin 1')}
function b () {console.log('plugin 2')}
function c () {console.log('plugin 3')}
function d () {console.log('plugin 4')}
seneca.use(a)
seneca.use(b)
seneca.ready((err) => {
if (err) process.exit(1)
console.log('ready 1 fired')
seneca.use(c)
seneca.use(d)
seneca.ready (function (err) {
if (err) process.exit(1)
console.log('ready 2 fired')
})
})
ready
inside of plugins is not considered supportedready
methods will be fired in the order they are encounteredThe export
method provides the ability for plugins to export named functions or objects
for use in later loaded plugins or in your own implementations.
The name of the object or function you wish to export.
…
The log.level
method set provides the ability to log directly off the Seneca instance.
By default Seneca includes a logging adaptor that emits JSON based logs.
You can swap out this adaptor for others. See Logging with Seneca for more information on adaptors.
The data to be logged.
warn
log level in Senecavar seneca = Seneca({
log: { level: 'warn+' }
})
seneca.log.debug('debug log level')
seneca.log.info('info log level')
seneca.log.warn('warn log level')
seneca.log.error('error log level')
seneca.log.fatal('fatal log level')
// Output:
// ["warn log level"]
// ["error log level"]
// ["fatal log level"]
test
log level in Senecavar seneca = Seneca({
log: 'test'
})
var seneca = Seneca({
log: { level: 'error+' }
})
seneca.log.warn({notice: 'warn log level'})
seneca.log.error({notice: 'error log level'})
seneca.log.fatal({notice: 'fatal log level'})
// Output:
// {"notice":"error log level","level":"error","seneca":"c8i.../147.../13586/3.0.0/-","when":1472737155055}
// {"notice":"fatal log level","level":"fatal","seneca":"c8i.../147.../13586/3.0.0/-","when":1472737155060}
debug
, info
, warn
, error
, fatal
info+
means info and above: info, warn, error, fatalConvenience shortcut log levels:
all
sets log level to debug+
,silent
sets log level to none
,test
represents the error+
levelThe default logging level is info+
.
The decorate
method provides the ability to decorate Seneca with functions or objects
in a safe manner. Trying to register a name that is already reserved will throw.
The name you wish to call the decorated function or object.
The handler the decorate seneca with. This can be a function or an object.
var seneca = require('seneca')
seneca.decorate('stamp', (pattern) => {
console.log(Date.now(), pattern)
})
seneca.stamp('role:echo')
var seneca = require('seneca')()
function plugin (opts) {
var seneca = this
seneca.decorate('stamp', (pattern) => {
console.log(Date.now(), pattern)
})
return {name: 'timestamper'}
}
seneca
.use(plugin)
.ready((err) => {
seneca.stamp('role:echo')
})
Issues? From spelling errors to broken tutorials and everything in between, report them here.