{"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,"search_vec":"'0.8.10':57 'activ':64 'although':67 'applic':22,35 'approach':83 'base':96 'cadenc':66 'capabl':30 'client':3,11 'client-sid':2,10 'configur':107 'counterpart':76 'current':52 'data':26 'databas':6,14,86,116,120 'design':17 'differenti':79 'distinguish':109 'e.g':46 'effect':32 'embed':106 'enabl':24 'extens':88 'file':87,124 'focus':72 'function':31 'handl':85 'html':105 'html-embed':104 'http':94 'http/https':45 'javascript':54,115,118 'json':92,119 'json.js':89 'jsondb':121 'jsonjsdb':1,7,122 'key':78 'librari':15 'local':38,123 'localhost':47 'mani':68 'offlin':25 'page':21 'product':49 'project':60 'protocol':41,99,125 'pure':114 'python':75 'queri':29 'recent':69 'relat':5,13 'releas':65 'relianc':102 'run':37 'serv':43 'server':50 'show':61 'side':4,12 'singl':20 'solut':117 'somewhat':63 'specif':16 'stabl':53 'static':19 'storag':27 'tradit':113 'typescript':126 'uniqu':82 'updat':70 'version':55 'via':39 'whether':33","created_at":"2026-04-22T05:18:14.933440+00:00","updated_at":"2026-04-22T05:18:14.933440+00:00","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","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.8.11","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/datannur/jsonjsdb.git#main","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/jsonjsdb","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database","web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-21","install_tag":null}}