{"id":16593,"library":"NDDB","title":"NDDB Object Database","description":"NDDB (N-Dimensional DataBase) is a 100% JavaScript object database designed for both Node.js and browser environments. It offers a comprehensive set of features including indexing, views, hashes, joins, group-by operations, and various statistical functions (count, max, min, mean, stddev). The library supports saving and loading data from the file system (Node.js) and browser localStorage. Current stable version is 3.0.2, published approximately four years ago, suggesting a mature codebase in maintenance mode. Its key differentiators include a flexible API for complex data manipulation, support for cyclic objects, and a focus on developer-friendliness, making it suitable for applications requiring in-memory data management with advanced querying capabilities, such as simulations or interactive data visualizations.","status":"maintenance","version":"3.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/nodeGame/NDDB","tags":["javascript","db","no-sql","cyclic objects","nddb","database","index","views","nodegame"],"install":[{"cmd":"npm install NDDB","lang":"bash","label":"npm"},{"cmd":"yarn add NDDB","lang":"bash","label":"yarn"},{"cmd":"pnpm add NDDB","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import NDDB from 'NDDB';","symbol":"NDDB","correct":"const NDDB = require('NDDB');"},{"note":"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.","wrong":"let db = new NDDB();","symbol":"NDDB.db()","correct":"let db = NDDB.db();"},{"note":"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.","wrong":"import NDDB from 'NDDB'; // In browser environment\nrequire('NDDB'); // In browser environment","symbol":"NDDB (Browser Global)","correct":"<!-- Must load a version of NDDB that includes JSUS -->\n<script src=\"/path/to/nddb.js\"></script>\n<script>\n  const db = NDDB.db();\n</script>"}],"quickstart":{"code":"const NDDB = require('NDDB');\n\n// Create a new database instance\nlet db = NDDB.db();\n\n// Add a single item to the database\ndb.insert({\n    painter: \"Picasso\",\n    title: \"Les Demoiselles d'Avignon\",\n    year: 1907\n});\n\n// Import a collection of items\nlet items = [\n    { painter: \"Dali\", title: \"Portrait of Paul Eluard\", year: 1929, portrait: true },\n    { painter: \"Dali\", title: \"Barcelonese Mannequin\", year: 1927 },\n    { painter: \"Monet\", title: \"Water Lilies\", year: 1906 },\n    { painter: \"Monet\", title: \"Wheatstacks (End of Summer)\", year: 1891 },\n    { painter: \"Manet\", title: \"Olympia\", year: 1863 }\n];\ndb.importDB(items);\n\n// Retrieve the database size\nconsole.log('Database size:', db.size()); // Expected: 6\n\n// Select items based on criteria\nlet daliPaintings = db.select('painter', '=', 'Dali');\nconsole.log('Dali paintings count:', daliPaintings.size()); // Expected: 2\nconsole.log('First Dali painting title:', daliPaintings.first().title);\n\n// Select items using LIKE operator (case sensitive)\nlet monetPaintings = db.select('painter', 'LIKE', 'M_net');\nconsole.log('Monet-like paintings count:', monetPaintings.size()); // Expected: 3\n\n// You can chain operations\nlet oldPaintings = db.select('year', '<', 1900).and('painter', 'LIKE', 'M_net');\nconsole.log('Old Monet-like paintings count:', oldPaintings.size()); // Expected: 1 (Manet's Olympia)\n","lang":"javascript","description":"This quickstart demonstrates how to initialize NDDB, insert individual and multiple records, query the database using basic and advanced operators, and chain selection methods."},"warnings":[{"fix":"Replace `let db = new NDDB();` with `let db = NDDB.db();`.","message":"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.","severity":"deprecated","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.10.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"*"},{"fix":"Exercise caution when using in projects targeting very recent Node.js versions. Consider thorough testing or evaluating alternatives if encountering unexpected behavior.","message":"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.","severity":"gotcha","affected_versions":">=3.0.2"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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).","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.","error":"ReferenceError: require is not defined"},{"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`.","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.","error":"NDDB is not defined"},{"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.","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.","error":"TypeError: NDDB.db is not a function"},{"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()); }`.","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.","error":"TypeError: Cannot read properties of undefined (reading 'size')"}],"ecosystem":"npm"}