Seneca Basic Utility Plugin

Common errors

• ReferenceError: require is not defined

  cause Attempting to use CommonJS `require()` in an ECMAScript module (ESM) context without proper setup.
  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.

• Error: Seneca: plugin 'basic' already exists.

  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.
  fix When initializing Seneca, disable the default `basic` plugin: `const seneca = require('seneca')({ default_plugins: { 'basic': false } })`.

• Error: seneca: no action found for pattern { role: 'basic', note: true, cmd: 'set', ... }

  cause The `seneca-basic` plugin has not been successfully loaded into the Seneca instance.
  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.

Warnings

• breaking 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.
  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.
• gotcha 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.
  Fix: When initializing Seneca for explicit loading, pass `{ default_plugins: { 'basic': false } }` as a configuration option: `const seneca = require('seneca')({ default_plugins: { 'basic': false } })`.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install seneca-basic npm
• yarn add seneca-basic yarn
• pnpm add seneca-basic pnpm

Imports

• seneca
  wrong:

  import seneca from 'seneca'

  correct:

  const seneca = require('seneca')

  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.
• seneca-basic plugin
  wrong:

  import senecaBasic from 'seneca-basic'

  correct:

  seneca.use(require('seneca-basic'))

  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.
• Basic plugin config
  wrong:

  const seneca = require('seneca')().use('basic')

  correct:

  const seneca = require('seneca')({ default_plugins: { 'basic': false } })

  To explicitly load `seneca-basic`, you must first disable the default inclusion of the 'basic' plugin when initializing Seneca.

Quickstart

This quickstart initializes Seneca, explicitly loads the seneca-basic plugin, and demonstrates setting, getting, pushing, listing, and popping 'note' values.

const seneca = require('seneca')({
  default_plugins: {
    'basic': false
  }
})

seneca.use(require('seneca-basic'))

async function run() {
  // Set a note
  await seneca.act({ role: 'basic', note: true, cmd: 'set', key: 'myKey', value: 'Hello Seneca!' })
  console.log('Note 'myKey' set.')

  // Get a note
  const resultGet = await seneca.act({ role: 'basic', note: true, cmd: 'get', key: 'myKey' })
  console.log(`Retrieved 'myKey': ${resultGet.value}`)

  // Push to a list
  await seneca.act({ role: 'basic', note: true, cmd: 'push', key: 'myList', value: 10 })
  await seneca.act({ role: 'basic', note: true, cmd: 'push', key: 'myList', value: 20 })
  console.log('Pushed values to 'myList'.')

  // Get the list
  const resultList = await seneca.act({ role: 'basic', note: true, cmd: 'list', key: 'myList' })
  console.log(`Retrieved 'myList': ${resultList.value}`)

  // Pop from the list
  const resultPop = await seneca.act({ role: 'basic', note: true, cmd: 'pop', key: 'myList' })
  console.log(`Popped from 'myList': ${resultPop.value}`)

  const finalResultList = await seneca.act({ role: 'basic', note: true, cmd: 'list', key: 'myList' })
  console.log(`'myList' after pop: ${finalResultList.value}`)

  await seneca.close()
  console.log('Seneca instance closed.')
}

run().catch(console.error)