Seneca Microservices Framework

Common errors

• Error: Seneca: Plugin 'seneca-entity' not found.

  cause The `seneca-entity` plugin, responsible for database entity operations, was removed from Seneca's core distribution in v2.0.0 and must now be explicitly installed and loaded.
  fix Install the plugin via `npm install seneca-entity` and add `seneca.use('entity')` to your Seneca instance initialization.

• Error: Seneca: No matching action for pattern { cmd: 'my-command', ... }

  cause The message sent via `seneca.act()` does not match any registered action patterns (`seneca.add()`). This can be due to a typo, an unloaded plugin that defines the action, or incorrect message parameters.
  fix Verify the exact pattern used in `seneca.act()` matches an existing `seneca.add()` definition. Ensure all necessary plugins defining actions are loaded using `seneca.use()`, and check that message properties align with the pattern's requirements.

• TypeError: Seneca is not a constructor

  cause This error typically occurs when attempting to call `new Seneca()` or `Seneca()` when `Seneca` was imported using a CommonJS `require` statement, but the module is expecting a default export in an ESM context, or vice-versa.
  fix If using CommonJS, ensure you're using `const Seneca = require('seneca'); const seneca = Seneca();`. If using ESM, ensure `import Seneca from 'seneca'; const seneca = Seneca();` and that your Node.js environment is configured for ESM.

• Error: listen() failed: port already in use

  cause The specified port for a Seneca transport listener (e.g., HTTP) is already being used by another process or another instance of your application.
  fix Ensure that no other applications or services are running on the desired port. If running multiple Seneca instances, configure each to use a unique port for its listeners, or ensure previous processes are properly shut down before starting new ones.

Warnings

• breaking Seneca v3.0.0 removed all default plugins (except `seneca-transport`) to make the core smaller and more stable. Applications upgrading from v2.x or earlier must explicitly install and load any previously implicitly available plugins (e.g., `seneca-basic`, `seneca-web`, etc.).
  Fix: Identify missing plugin functionality, install the corresponding `seneca-` plugin from npm, and add `seneca.use('plugin-name')` to your Seneca instance initialization.
• breaking Seneca v2.0.0 made a significant change by no longer installing and using the `seneca-entity` plugin by default. Projects relying on database entity interactions implicitly will encounter errors.
  Fix: To restore entity functionality, install `seneca-entity` (`npm install seneca-entity`) and explicitly load it with `seneca.use('entity')`.
• gotcha Since v3.0.0, Seneca defaults to JSON output for logs. If you relied on the previous 'pretty' logging format or had custom log handlers, you will need to adjust your logging configuration or use the `seneca-legacy-logger` plugin.
  Fix: For pretty logging, install `seneca-legacy-logger` and use it. For custom loggers, ensure they are compatible with JSON input or update them accordingly.
• gotcha Seneca v3.3.0 introduced a change allowing action callbacks to omit the Error parameter (hapi style). While this adds flexibility, it can lead to inconsistent callback signatures if not managed carefully across your codebase.
  Fix: Review your action callback implementations to standardize on an error-first or error-omitting style for consistency, especially when integrating with new plugins or migrating old code.
• gotcha Earlier versions of Seneca (prior to v3.7.0 and v3.2.0) had known memory leak issues, specifically related to the history mechanism and Gate Executor timeouts. Running older 3.x versions might lead to resource exhaustion over time.
  Fix: It is highly recommended to upgrade to the latest stable 3.x version of Seneca to benefit from critical memory leak and stability fixes.

Install

• npm install seneca npm
• yarn add seneca yarn
• pnpm add seneca pnpm

Imports

• Seneca
  wrong:

  import Seneca from 'seneca'

  correct:

  const Seneca = require('seneca')

  CommonJS `require` is the primary usage pattern demonstrated in official examples, compatible with Node.js >=10.
• Seneca
  wrong:

  const Seneca = require('seneca')

  correct:

  import Seneca from 'seneca'

  For ESM environments (Node.js versions with stable ESM support), `Seneca` is the default export. Ensure your project is configured for ESM if using this import style.
• Seneca.util

  const Seneca = require('seneca'); const { Eraro, Jsonic, Nid, Patrun } = Seneca.util;

  Utility modules like Eraro, Jsonic, Nid, and Patrun are exposed directly on the main Seneca export via `Seneca.util` since v3.7.0. They are not separate top-level imports.

Quickstart

This example demonstrates defining and loading plugins, setting up HTTP listeners for microservices, and client-side message dispatching with pattern matching and priority handling.

'use strict'

var Seneca = require('seneca')

function rejector () {
  this.add('cmd:run', (msg, done) => {
    return done(null, {tag: 'rejector'})
  })
}

function approver () {
  this.add('cmd:run', (msg, done) => {
    return done(null, {tag: 'approver'})
  })
}

function local () {
  this.add('cmd:run', function (msg, done) {
    this.prior(msg, (err, reply) => {
      return done(null, {tag: reply ? reply.tag : 'local'})
    })
  })
}

Seneca()
  .use(approver)
  .listen({type: 'http', port: '8260', pin: 'cmd:*'})

Seneca()
  .use(rejector)
  .listen(8270)

function handler (err, reply) {
  console.log(err, reply)
}

Seneca()
  .use(local)
  .act('cmd:run', handler)

Seneca()
  .client({port: 8270, pin: 'cmd:run'})
  .client({port: 8260, pin: 'cmd:run'})
  .use(local)
  .act('cmd:run', handler)

Seneca()
  .client({port: 8260, pin: 'cmd:run'})
  .client({port: 8270, pin: 'cmd:run'})
  .use(local)
  .act('cmd:run', handler)