seneca

library0.6.0jsnpmunverified

Seneca is a mature Node.js microservices framework designed to help organize application business logic through a pattern-matching approach to message passing. Currently at stable version 3.38.0, its release cadence is active but irregular, with a focus on stability and a smaller core. Key differentiators include its flexible pattern-matching for defining commands, transport independence that abstracts message delivery, and a robust ecosystem of plugins for common microservice concerns like data storage, user management, and distributed logic. The framework emphasizes breaking down applications into 'stuff that happens' rather than strict data models, providing a flexible toolkit for building Minimum Viable Products and complex distributed systems. It supports Node.js versions 10 and above and ships with TypeScript types.

web-framework workflow http-networking

npm install seneca

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SENECA

seneca

web-frameworkjavascriptv0.6.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Seneca

✓ const Seneca = require('seneca')

✗ import Seneca from 'seneca'

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

Seneca

✓ import Seneca from 'seneca'

✗ const Seneca = require('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.

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)

Debug

Known issues

breakingSeneca 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.

affects: >=3.0.0

breakingSeneca 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')`.

affects: >=2.0.0 <3.0.0

gotchaSince 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.

affects: >=3.0.0

gotchaSeneca 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.

affects: >=3.3.0

gotchaEarlier 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.

affects: <3.7.0

Errors

Common errors & fixes

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

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', ... }

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

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

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.

Upgrade

Version history

0.6.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

23 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/senecajs/seneca ↗

packagehttps://www.npmjs.com/package/seneca ↗

homepagehttp://senecajs.org ↗