NDDB Object Database

Common errors

• ReferenceError: require is not defined

  cause Attempting to use `require()` syntax in a browser environment without a module bundler, or in a Node.js ES module context where `require` is not available.
  fix For browsers, ensure the NDDB script is loaded via a `<script>` tag and access `NDDB` globally. For Node.js ES module environments, either switch to CommonJS or use dynamic `import()` if NDDB provided ESM exports (which it typically doesn't directly).

• NDDB is not defined

  cause The NDDB script file was not correctly loaded in the browser, or `require('NDDB')` failed in Node.js, or an `import` statement for a non-ESM module failed.
  fix Verify the `<script>` tag path in HTML or the `require()` path in Node.js. Check the console for script loading errors. If using ES modules in Node.js, ensure `const NDDB = require('NDDB');` is used instead of `import`.

• TypeError: NDDB.db is not a function

  cause Attempting to call `NDDB.db()` when `NDDB` itself is not the constructor function, possibly due to a `require('NDDB').NDDB` legacy import, or if `new NDDB()` was incorrectly used in a way that overwrites the `db` static method.
  fix Ensure `const NDDB = require('NDDB');` is the primary import. If using a legacy setup, verify `NDDB` points to the correct top-level constructor/factory.

• TypeError: Cannot read properties of undefined (reading 'size')

  cause This usually occurs after a `db.select()` call where the selection yielded no results, and a subsequent method like `size()` or `first()` is called on an `undefined` or null result, or on an empty NDDB instance.
  fix Always check the result of selection methods before chaining further operations, e.g., `let selected = db.select('key', '=', 'value'); if (selected.size() > 0) { console.log(selected.first()); }`.

Warnings

• deprecated The `new NDDB()` constructor for creating database instances is considered legacy. While it may still work, the officially recommended approach is to use the static factory method `NDDB.db()` to ensure future compatibility and consistent behavior.
  Fix: Replace `let db = new NDDB();` with `let db = NDDB.db();`.
• gotcha NDDB is primarily a CommonJS module. Direct ES module `import` statements (e.g., `import NDDB from 'NDDB';`) will not work out-of-the-box in Node.js environments without specific configuration (e.g., `type: 'module'` in package.json and corresponding export syntax) or a transpilation step.
  Fix: In Node.js, use `const NDDB = require('NDDB');`. If ESM is strictly required, consider a CommonJS wrapper or a build tool that handles module interoperability.
• gotcha When loading NDDB in a browser, you must include a version of the script that bundles its dependencies, particularly `JSUS`. The standalone `NDDB` script may not function correctly if `JSUS` is not available in the global scope.
  Fix: Ensure you are using a 'build/' directory version of `nddb.js` that includes `JSUS`, or include `JSUS` separately before `nddb.js` in your HTML `<script>` tags.
• gotcha The `engines.node` field specifies `>=0.10.0`, which is a very old Node.js version. While NDDB might technically run on newer versions, its lack of recent updates (last publish 4 years ago) could imply it hasn't been thoroughly tested against the latest Node.js runtime changes or modern JavaScript features. There might be subtle incompatibilities or performance issues with very new Node.js versions.
  Fix: Exercise caution when using in projects targeting very recent Node.js versions. Consider thorough testing or evaluating alternatives if encountering unexpected behavior.

Install

• npm install NDDB npm
• yarn add NDDB yarn
• pnpm add NDDB pnpm

Imports

• NDDB
  wrong:

  import NDDB from 'NDDB';

  correct:

  const NDDB = require('NDDB');

  NDDB is primarily a CommonJS module. Attempting to import it directly using ES module syntax (`import`) will likely result in a runtime error (e.g., `ERR_REQUIRE_ESM`) in Node.js environments unless explicitly transpiled or wrapped.
• NDDB.db()
  wrong:

  let db = new NDDB();

  correct:

  let db = NDDB.db();

  Since version 3, the recommended way to create a new NDDB instance is via the static `NDDB.db()` factory method. The `new NDDB()` constructor is considered legacy.
• NDDB (Browser Global)
  wrong:

  import NDDB from 'NDDB'; // In browser environment
  require('NDDB'); // In browser environment

  correct:

  <!-- Must load a version of NDDB that includes JSUS -->
  <script src="/path/to/nddb.js"></script>
  <script>
    const db = NDDB.db();
  </script>

  In a browser environment, NDDB is exposed as a global variable `NDDB` after including its script. Direct CommonJS `require()` or ES module `import` syntax is not natively supported without a build step.

Quickstart

This quickstart demonstrates how to initialize NDDB, insert individual and multiple records, query the database using basic and advanced operators, and chain selection methods.

const NDDB = require('NDDB');

// Create a new database instance
let db = NDDB.db();

// Add a single item to the database
db.insert({
    painter: "Picasso",
    title: "Les Demoiselles d'Avignon",
    year: 1907
});

// Import a collection of items
let items = [
    { painter: "Dali", title: "Portrait of Paul Eluard", year: 1929, portrait: true },
    { painter: "Dali", title: "Barcelonese Mannequin", year: 1927 },
    { painter: "Monet", title: "Water Lilies", year: 1906 },
    { painter: "Monet", title: "Wheatstacks (End of Summer)", year: 1891 },
    { painter: "Manet", title: "Olympia", year: 1863 }
];
db.importDB(items);

// Retrieve the database size
console.log('Database size:', db.size()); // Expected: 6

// Select items based on criteria
let daliPaintings = db.select('painter', '=', 'Dali');
console.log('Dali paintings count:', daliPaintings.size()); // Expected: 2
console.log('First Dali painting title:', daliPaintings.first().title);

// Select items using LIKE operator (case sensitive)
let monetPaintings = db.select('painter', 'LIKE', 'M_net');
console.log('Monet-like paintings count:', monetPaintings.size()); // Expected: 3

// You can chain operations
let oldPaintings = db.select('year', '<', 1900).and('painter', 'LIKE', 'M_net');
console.log('Old Monet-like paintings count:', oldPaintings.size()); // Expected: 1 (Manet's Olympia)