{
  "compilerOptions": {
    "paths": {
      "seneca": ["./vendor/seneca/seneca.ts"]
    },
    "resolveJsonModule": true,
    "esModuleInterop": true
  }
}

Public API

init (default export)

function init(seneca_options?: Record<string, any>, more_options?: Record<string, any>): Instance

The main factory. Call init() (or require('seneca')()) to create a new Seneca instance. Pass an options object to configure tag, timeout, idlen, test, quiet, log, and default_plugins. Returns an Instance that exposes the full Seneca API. Call a second time to get an independent instance.

Instance

type Instance = ReturnType<typeof make_seneca> & Record<string, any>

The live Seneca object returned by init(). It carries all chainable methods (use, add, act, listen, client, ready, close, prior, decorate, etc.). Methods are chainable. The index signature (Record<string, any>) reflects runtime decoration by plugins.

init.util

var util: {
  Eraro: any
  Jsonic: any
  Nid: typeof Nid
  Patrun: typeof Patrun
  Gex: typeof Gex
  Gubu: Gubu
  pins: any
  clean: any
  pattern: any
  print: any
  error: any
  deep: any
  deepextend: any
  parsepattern: any
  pincanon: any
  router: () => any
  resolve_option: any
  flatten: any
}

Static utility bag exposed on the init function itself (not on instances). Use init.util.Jsonic for pattern-string parsing, init.util.deep for deep-merging option objects, and init.util.Patrun / init.util.Gex when writing custom routers or test assertions.

Working examples

Scenario - Define and call a local action

Register a pattern handler on an instance and invoke it in-process. The add method binds a pattern; act dispatches a message and receives the reply via callback.

import init from './vendor/seneca/seneca.js'

const seneca = init({ test: true })

seneca.add({ cmd: 'greet' }, function (msg: any, reply: Function) {
  reply(null, { greeting: `Hello, ${msg.name}` })
})

seneca.act({ cmd: 'greet', name: 'World' }, function (err: any, result: any) {
  if (err) throw err
  console.log(result.greeting) // Hello, World
})

Scenario - Plugin composition with prior chaining

Plugins extend behaviour by adding handlers on the same pattern. prior delegates to the previously registered handler, enabling middleware-style composition.

import init from './vendor/seneca/seneca.js'

function basePlugin(this: any) {
  this.add('cmd:score', function (msg: any, reply: Function) {
    reply(null, { score: 10 })
  })
}

function bonusPlugin(this: any) {
  this.add('cmd:score', function (this: any, msg: any, reply: Function) {
    this.prior(msg, function (err: any, result: any) {
      if (err) return reply(err)
      reply(null, { score: result.score + 5 })
    })
  })
}

const seneca = init()
  .use(basePlugin)
  .use(bonusPlugin)

seneca.act('cmd:score', function (err: any, result: any) {
  console.log(result.score) // 15
})

Scenario - ready callback and graceful shutdown

Use ready to defer work until all plugins have initialised, and close to drain the gate executor and shut down cleanly.

import init from './vendor/seneca/seneca.js'

function myPlugin(this: any) {
  this.add('role:data,cmd:list', function (msg: any, reply: Function) {
    reply(null, { items: ['a', 'b', 'c'] })
  })
}

const seneca = init({ timeout: 5000, tag: 'app1' })
  .use(myPlugin)
  .ready(function (this: any) {
    this.act('role:data,cmd:list', function (err: any, out: any) {
      console.log(out.items) // ['a', 'b', 'c']
      seneca.close(function () {
        console.log('shutdown complete')
      })
    })
  })

File walkthrough

• seneca.js — compiled CJS entry; defines option_defaults, constructs the Seneca prototype, and exports the init factory with its static properties.
• seneca.ts — TypeScript source mirroring seneca.js; authoritative for understanding construction logic and option schema.
• seneca.d.ts — declaration file; defines the Instance type alias and the init namespace with util, valid, and test$ statics.
• lib/act.js / lib/act.ts / lib/act.d.ts — implements act message dispatch logic.
• lib/add.js / lib/add.ts / lib/add.d.ts — implements add pattern registration.
• lib/actions.js / lib/actions.ts / lib/actions.d.ts — wires built-in system actions onto an instance.
• docs/examples/ — runnable Node.js scripts demonstrating sales-tax service, two-microservice setup, plugin authoring, error handling, and logging.
• package.json — declares user@example.com and all runtime dependencies.
• tsconfig.json — TypeScript project configuration used when compiling from source.
• .eslintrc.js — ESLint rules; ignores test/, docs/examples/, and trial/.

Common pitfalls and fixes

• CJS / ESM interop: seneca.js uses exports not export default; when importing in ESM use import init from 'seneca' only with "esModuleInterop": true in tsconfig.json.
• resolveJsonModule missing: seneca.ts imports ./package.json directly; add "resolveJsonModule": true to compilerOptions or the TypeScript build will fail.
• Callback style vs. async: The core act API is callback-based; wrapping with util.promisify will not work correctly because the callback receives (err, result) but prior chains depend on the synchronous call stack — use the provided callback form.
• Timeout on slow plugins: The default timeout is 22222 ms; if plugin init functions do async work exceeding this, the instance will emit a timeout error — increase timeout in init({ timeout: 60000 }).
• Plugin this context: Plugin functions passed to .use() must be regular function declarations, not arrow functions, because Seneca binds the instance to this inside the plugin body.
• Multiple instances sharing state: Each init() call creates an independent instance; do not share mutable state (e.g. external DB connections) across instances without explicit coordination — pass them via plugin options.

Vibe-coding prompt template

I have a copy of the Seneca microservice framework source in ./vendor/seneca/
and a usage guide at ./USAGE.md. The upstream npm package is user@example.com

Please integrate Seneca into my existing Node.js/TypeScript project step by step:

1. Read USAGE.md and the file listing under source/ to understand what is available.
2. Install all required dependencies listed in USAGE.md into my project's package.json.
3. Update my tsconfig.json with esModuleInterop and resolveJsonModule as described.
4. Create a seneca-instance.ts module that initialises a shared Seneca instance
   using init() from ./vendor/seneca/seneca.js with appropriate options for my project.
5. Add at least one plugin that registers a pattern handler relevant to my domain.
6. Wire a ready() callback that verifies the instance starts cleanly.
7. Show how to call act() to dispatch a message and handle the response.
8. Point out any pitfalls from USAGE.md that apply to my setup and how to avoid them.

License and credit

Seneca is released under the MIT License (see source/LICENSE). Copyright 2010-2023 Richard Rodger and other contributors. Upstream package: seneca on npm. Sponsored and supported by Voxgig.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.