{"id":16633,"library":"jsonjsdb","title":"Jsonjsdb - Client-side Relational Database","description":"Jsonjsdb is a client-side relational database library specifically designed for static Single Page Applications. It enables offline data storage and querying capabilities, functioning effectively whether the application is run locally via the `file://` protocol or served over HTTP/HTTPS (e.g., localhost or production servers). The current stable JavaScript version is 0.8.10, with the project showing a somewhat active release cadence, although many recent updates have focused on its Python counterpart. A key differentiator is its unique approach to handling database file extensions (`.json.js` for `file://` and `.json` for `http(s)://`) based on the protocol, and its reliance on HTML-embedded configuration, which distinguishes it from more traditional pure JavaScript database solutions.","status":"active","version":"0.8.10","language":"javascript","source_language":"en","source_url":"https://github.com/datannur/jsonjsdb#main","tags":["javascript","json","database","jsondb","jsonjsdb","local","file protocol","typescript"],"install":[{"cmd":"npm install jsonjsdb","lang":"bash","label":"npm"},{"cmd":"yarn add jsonjsdb","lang":"bash","label":"yarn"},{"cmd":"pnpm add jsonjsdb","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library primarily uses ES Module syntax, requiring `import` statements. CommonJS `require` might lead to 'Cannot use import statement outside a module' errors if the project isn't configured for it.","wrong":"const Jsonjsdb = require('jsonjsdb')","symbol":"Jsonjsdb","correct":"import Jsonjsdb from 'jsonjsdb'"},{"note":"For TypeScript projects, import types explicitly. The configuration is typically inferred from HTML attributes, but an interface for programmatic configuration might exist for advanced use cases.","symbol":"JsonjsdbConfig","correct":"import type { JsonjsdbConfig } from 'jsonjsdb'"},{"note":"The `init()` method is asynchronous and returns a Promise; it must be awaited to ensure the database is fully loaded before performing operations.","wrong":"db.init()","symbol":"init","correct":"await db.init()"}],"quickstart":{"code":"import Jsonjsdb from 'jsonjsdb';\n\nasync function initializeAndQueryDb() {\n  const db = new Jsonjsdb();\n  try {\n    // Initialize the database. This reads the __table__.json(.js) and table data.\n    await db.init();\n\n    // Example: Get all entries from a 'user' table\n    const users = db.getAll('user');\n    console.log('All users:', users);\n\n    // Example: Get a specific user by ID (assuming 'user' table has IDs like 123)\n    const specificUser = db.get('user', 123);\n    console.log('Specific user (ID 123):', specificUser);\n\n    // You can also demonstrate iteration or checking existence\n    db.foreach('product', (product) => {\n      console.log('Product found:', product.name);\n    });\n\n    if (db.exists('settings', 'app_name')) {\n      console.log('App name setting exists.');\n    }\n\n  } catch (error) {\n    console.error('Failed to initialize or query database:', error);\n    // Depending on the error, provide user guidance. E.g., check 'db' folder, config.\n  }\n}\n\ninitializeAndQueryDb();","lang":"typescript","description":"This quickstart demonstrates how to instantiate `Jsonjsdb`, initialize it asynchronously, and then perform basic data retrieval operations like getting all records from a table and retrieving a specific record by ID."},"warnings":[{"fix":"Ensure your build process or deployment script handles the correct file extension for your target environment (local `file://` vs. web server `http(s)://`). Consider using a build tool to generate both versions or dynamically rename during development/deployment.","message":"When running your application locally via the `file://` protocol, database table files must have a `.json.js` extension (e.g., `users.json.js`). When served over HTTP/HTTPS, they must have a `.json` extension (e.g., `users.json`). Failure to use the correct extension for the protocol will result in database loading errors.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Always check the HTML `div#jsonjsdb-config` element for database path (`data-path`), application name (`data-app-name`), and database key (`data-db-key`). Ensure these attributes are correctly set or provided programmatically if the `Jsonjsdb` constructor supports it.","message":"The library primarily uses HTML-embedded configuration via a `div` element with `id=\"jsonjsdb-config\"` and `data-` attributes. Developers accustomed to pure JavaScript configuration might overlook this, leading to unexpected default behavior or configuration issues.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"When upgrading between minor `0.x` versions, thoroughly review the project's main documentation (beyond the specific package README) and any available release notes for potential API changes or configuration adjustments, especially regarding `init()` options or data retrieval methods.","message":"While no specific breaking changes for the JavaScript core were detailed in the provided changelog, minor version increments in pre-1.0 software (like `0.x` to `0.8.x`) often introduce breaking changes in APIs, configuration, or expected behavior without extensive migration guides.","severity":"breaking","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure your database files are named with a `.json.js` extension (e.g., `users.json.js`) when running locally via `file://`. For HTTP/HTTPS, they should be `.json`.","cause":"The browser is attempting to load `.json` files over the `file://` protocol (e.g., when opening `index.html` directly), but the database expects `.json.js` files in this environment.","error":"Failed to load resource: net::ERR_FILE_NOT_FOUND (or similar HTTP 404 for JSON files)"},{"fix":"Verify that `import Jsonjsdb from 'jsonjsdb'` is used for ES Modules, and that `const db = new Jsonjsdb()` successfully creates an instance before calling `db.init()`.","cause":"The `db` instance was not correctly created, or `init()` was called on an undefined variable. More commonly, if using ESM, `require('jsonjsdb')` was used instead of `import Jsonjsdb from 'jsonjsdb'`.","error":"TypeError: db.init is not a function (or: Cannot read properties of undefined (reading 'init'))"},{"fix":"Check the `_db_` folder (or configured `data-path`) for the `__table__.json` (or `__table__.json.js`) file and ensure it correctly lists all available table names. Also, verify that the table data files themselves are present and correctly named.","cause":"The specified table name does not exist, or the `__table__.json` (or `__table__.json.js`) file, which lists all tables, is missing or incorrectly formatted.","error":"Uncaught (in promise) Error: Table 'tableName' not found in database."}],"ecosystem":"npm"}