jsonjsdb

library0.8.11jsnpmunverified

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.

database web-framework

npm install jsonjsdb

github ↗package ↗

INSTALL

IMPORT

SIG · JSONJSDB

jsonjsdb

databasejavascriptv0.8.11

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Jsonjsdb

✓ import Jsonjsdb from 'jsonjsdb'

✗ const Jsonjsdb = require('jsonjsdb')

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.

JsonjsdbConfig

✓ import type { JsonjsdbConfig } from 'jsonjsdb'

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.

init

✓ await db.init()

✗ db.init()

The `init()` method is asynchronous and returns a Promise; it must be awaited to ensure the database is fully loaded before performing operations.

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.

import Jsonjsdb from 'jsonjsdb'; async function initializeAndQueryDb() { const db = new Jsonjsdb(); try { // Initialize the database. This reads the __table__.json(.js) and table data. await db.init(); // Example: Get all entries from a 'user' table const users = db.getAll('user'); console.log('All users:', users); // Example: Get a specific user by ID (assuming 'user' table has IDs like 123) const specificUser = db.get('user', 123); console.log('Specific user (ID 123):', specificUser); // You can also demonstrate iteration or checking existence db.foreach('product', (product) => { console.log('Product found:', product.name); }); if (db.exists('settings', 'app_name')) { console.log('App name setting exists.'); } } catch (error) { console.error('Failed to initialize or query database:', error); // Depending on the error, provide user guidance. E.g., check 'db' folder, config. } } initializeAndQueryDb();

Debug

Known issues

gotchaWhen 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.

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.

affects: >=0.1.0

gotchaThe 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.

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.

affects: >=0.1.0

breakingWhile 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.

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.

affects: >=0.1.0

Errors

Common errors & fixes

Failed to load resource: net::ERR_FILE_NOT_FOUND (or similar HTTP 404 for JSON files)

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.

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`.

TypeError: db.init is not a function (or: Cannot read properties of undefined (reading 'init'))

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'`.

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()`.

Uncaught (in promise) Error: Table 'tableName' not found in database.

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.

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.

Upgrade

Version history

0.8.11latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

13 hits · last 30 days

node

Resources

githubhttps://github.com/datannur/jsonjsdb.git#main ↗

packagehttps://www.npmjs.com/package/jsonjsdb ↗