{"id":11997,"library":"seneca-basic","title":"Seneca Basic Utility Plugin","description":"seneca-basic is a foundational utility plugin for the Seneca.js microservices framework. It provides a small, essential set of action patterns for internal per-process communication, primarily through a 'notes' mechanism, allowing plugins to store and retrieve keyed values or lists. These patterns include `set`, `get`, `push`, `list`, and `pop` for `role:basic, note:true` actions. The package is often bundled by default within the main `seneca` module, simplifying its integration for most users. Its current stable version is 1.0.0, though the latest detailed release notes visible are from v0.5.0 in 2016, indicating a mature and stable, rather than rapidly evolving, project. Release cadence is infrequent, likely tied to Seneca's own maintenance cycles. Its key differentiator is its tightly integrated role within the Seneca ecosystem, providing a lightweight, built-in mechanism for internal plugin coordination without external dependencies.","status":"maintenance","version":"1.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/senecajs/seneca-basic","tags":["javascript","seneca","plugin","util","utility","basic"],"install":[{"cmd":"npm install seneca-basic","lang":"bash","label":"npm"},{"cmd":"yarn add seneca-basic","lang":"bash","label":"yarn"},{"cmd":"pnpm add seneca-basic","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package is a plugin for Seneca.js and requires a Seneca instance to function.","package":"seneca","optional":false}],"imports":[{"note":"Seneca.js, and by extension seneca-basic, primarily uses CommonJS `require` for module loading. Direct ESM `import` is not supported without a CommonJS wrapper or bundler.","wrong":"import seneca from 'seneca'","symbol":"seneca","correct":"const seneca = require('seneca')"},{"note":"The plugin is typically loaded via `seneca.use()` with a CommonJS `require`. Ensure 'basic' is disabled in `default_plugins` if you're loading it explicitly.","wrong":"import senecaBasic from 'seneca-basic'","symbol":"seneca-basic plugin","correct":"seneca.use(require('seneca-basic'))"},{"note":"To explicitly load `seneca-basic`, you must first disable the default inclusion of the 'basic' plugin when initializing Seneca.","wrong":"const seneca = require('seneca')().use('basic')","symbol":"Basic plugin config","correct":"const seneca = require('seneca')({ default_plugins: { 'basic': false } })"}],"quickstart":{"code":"const seneca = require('seneca')({\n  default_plugins: {\n    'basic': false\n  }\n})\n\nseneca.use(require('seneca-basic'))\n\nasync function run() {\n  // Set a note\n  await seneca.act({ role: 'basic', note: true, cmd: 'set', key: 'myKey', value: 'Hello Seneca!' })\n  console.log('Note 'myKey' set.')\n\n  // Get a note\n  const resultGet = await seneca.act({ role: 'basic', note: true, cmd: 'get', key: 'myKey' })\n  console.log(`Retrieved 'myKey': ${resultGet.value}`)\n\n  // Push to a list\n  await seneca.act({ role: 'basic', note: true, cmd: 'push', key: 'myList', value: 10 })\n  await seneca.act({ role: 'basic', note: true, cmd: 'push', key: 'myList', value: 20 })\n  console.log('Pushed values to 'myList'.')\n\n  // Get the list\n  const resultList = await seneca.act({ role: 'basic', note: true, cmd: 'list', key: 'myList' })\n  console.log(`Retrieved 'myList': ${resultList.value}`)\n\n  // Pop from the list\n  const resultPop = await seneca.act({ role: 'basic', note: true, cmd: 'pop', key: 'myList' })\n  console.log(`Popped from 'myList': ${resultPop.value}`)\n\n  const finalResultList = await seneca.act({ role: 'basic', note: true, cmd: 'list', key: 'myList' })\n  console.log(`'myList' after pop: ${finalResultList.value}`)\n\n  await seneca.close()\n  console.log('Seneca instance closed.')\n}\n\nrun().catch(console.error)\n","lang":"javascript","description":"This quickstart initializes Seneca, explicitly loads the seneca-basic plugin, and demonstrates setting, getting, pushing, listing, and popping 'note' values."},"warnings":[{"fix":"Upgrade your Node.js runtime to version 6 or newer. The current recommended Node.js LTS version is generally advised for all Seneca.js projects.","message":"Version 0.5.0 of seneca-basic dropped support for Node.js versions 0.10, 0.12, and 5. Ensure you are running Node.js 6 or higher for compatibility.","severity":"breaking","affected_versions":">=0.5.0"},{"fix":"When initializing Seneca for explicit loading, pass `{ default_plugins: { 'basic': false } }` as a configuration option: `const seneca = require('seneca')({ default_plugins: { 'basic': false } })`.","message":"seneca-basic is typically included by default when you initialize a Seneca instance. If you intend to explicitly load it via `seneca.use(require('seneca-basic'))`, you must disable its default inclusion first, otherwise the plugin may be registered twice or behave unexpectedly.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Use CommonJS `require()` statements for importing `seneca` and `seneca-basic`. If you must use ESM, consider using `createRequire` from the `module` package or a build tool like Webpack/Rollup that can handle CommonJS modules in an ESM project.","message":"This package, like the core Seneca.js framework, is built with CommonJS modules in mind. Attempting to use ES module `import` syntax directly will result in errors in a standard Node.js environment without a transpiler or CommonJS wrapper.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"For persistent data storage, inter-service communication, or public APIs, utilize dedicated Seneca patterns like `role:entity` for data persistence or define specific service endpoints for API interactions.","message":"The package's primary purpose is for internal note-taking within a Seneca microservice process. It is not designed as a general-purpose key-value store or inter-process communication mechanism across different microservices or external applications.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure your file is treated as a CommonJS module (e.g., `.js` file without `\"type\": \"module\"` in `package.json`, or explicitly `.cjs` extension). Alternatively, if using ESM, use `import()` or `createRequire` for compatibility.","cause":"Attempting to use CommonJS `require()` in an ECMAScript module (ESM) context without proper setup.","error":"ReferenceError: require is not defined"},{"fix":"When initializing Seneca, disable the default `basic` plugin: `const seneca = require('seneca')({ default_plugins: { 'basic': false } })`.","cause":"The 'basic' plugin is being loaded twice because it's included by default and then explicitly loaded again via `seneca.use()` without disabling the default.","error":"Error: Seneca: plugin 'basic' already exists."},{"fix":"Verify that `seneca.use(require('seneca-basic'))` is correctly called and that no errors occurred during plugin loading. Ensure `default_plugins.basic` is set to `false` if loading explicitly.","cause":"The `seneca-basic` plugin has not been successfully loaded into the Seneca instance.","error":"Error: seneca: no action found for pattern { role: 'basic', note: true, cmd: 'set', ... }"}],"ecosystem":"npm"}