Extends senecajs microservice library: offhandedly, with respect

seneca-extended

What is it and what is for

When i started building application using senecajs framework, i didn't find the easy ways to solve some of problems:

• ability to use promises
• throw errors on server and catch them by client (with custom payload)
• initialize plugins on asynchronius way before load them into framework
• log messages in own format instead of verbose seneca output
• some other stuff

This wrapper try to solve most of this troubles, offering common interface without changing the basic functionality in my own way.

WARN: this module don't works in nodejs <6.x (no time for babel, feel free to pull reques with babel support if you need earlier versions support)

Install

$ npm install seneca-extended

Test

$ npm run test

Quck Example

1const ld = require('lodash')
2const seneca = require('../src')()
3// `seneca` is fully usable seneca instance with build-in additional features
4
5/** default senecajs plugin **/
6const basicPlugin = function (config) {
7
8  this.add({ role: 'example', method: 'ping' }, (message, done) => {
9    // in case of exception here - error will not pass to remote client
10    done(null, { ping: 'pong'} )
11  })
12
13  this.add('role:example,method:error', (message, done) => {
14    this.emitError(new Error('this error will be passed to client'), done)
15  })
16}
17
18/** extended plugin **/
19const route = {
20  ping: 'role:example,method:ping',
21  error: 'role:example,method:error'
22}
23const extendedPlugin = {
24  name: 'example', // exported routes will be available in: seneca.routes.example.*
25  routes: ld.pick(route, ['ping']) // will export only route 'ping' for example
26  init: function (senecaInstance, config) {
27    // this method will be called on plugin load, async code can be used here
28    return Promise.delay(300)
29  },
30  seneca: function (config) {
31    // basoc seneca route add
32    this.add('role:example,method:sometest', (message, done) => done(null, { ping: 'sometes'} ))
33    this.addAsync(route.ping, message => {
34      // we are in promise now, so can just return result - all error will be handled
35      return { ping: 'pong' }
36    })
37    this.addAsync(route.error, message => {
38      const error = new Error('this error will be passed to client')
39      error.payload = { additional: 'payload' } // we can evend add payload
40      throw error
41    })
42  },
43  someOther: function () {
44    // we can export other method for futher usage
45    // ex.: route schemas/specifications, helper methods etc
46  }
47}
48
49
50const sampleOptions = { some: 'config' }
51
52// now seneca able to load not only synchronous code...
53seneca.useAsync(basicPlugin, sampleOptions) // same as synchronous seneca.use
54seneca.actAsync('role:example,method:error').catch(err => {
55  console.log('catched from error:', err.message)
56})
57
58// ... but also preload plugins methods as promises
59seneca.useAsync(extendedPlugin, sampleOptions).then(() => {
60  console.log('async plugins loaded and usable now')
61  // 'role:example,method:ping'
62  seneca.actAsync(seneca.example.ping, { some: 'payload' }).then(res => {
63    console.log('got from ping:', res)
64  })
65})
66
67// Output:
68// async plugins loaded and usable now
69// catched from error: this error will be passed to client
70// got from ping: { ping: 'pong' }

Advanced example: custom microservice with deployment into kubernetes, configuration files and common launcher - micro-test (maybe outdated)

API

Core documentation available at oficial API page. Following methods are added by seneca-extended and not usable without this module:

.addAsync(route, promisifiedCallback)

Extened version of seneca.add with promisified callback.

.useAsync(plugin, [config]) -> Promise

Extened version of seneca.use with ability to load promisified plugins.

.emitError(Error, callback)

1this.add('...', (message, done) => {
2  try {
3    // some code
4    done()
5  } catch (err) {
6    // now remote clients will catch this error
7    this.emitError(err, done)
8  }
9})

.actCustom(...)

Extended version of seneca.act with error catching (useful if you dont need response)

.actAsync

Promisified version of seneca.actCustom.

1seneca.actAsync('some:route').then(console.log).catch(console.log)

.logger.warn, .logger.debug, .logger.info, .logger.error

Lightweight logger without default seneca verbosity (should be, just lightweight now :) .