Jsonjsdb - Client-side Relational Database

Common errors

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

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

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

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

Warnings

• gotcha 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.
  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.
• gotcha 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.
  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.
• breaking 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.
  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.

Install

• npm install jsonjsdb npm
• yarn add jsonjsdb yarn
• pnpm add jsonjsdb pnpm

Imports

• Jsonjsdb
  wrong:

  const Jsonjsdb = require('jsonjsdb')

  correct:

  import Jsonjsdb from '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
  wrong:

  db.init()

  correct:

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

Quickstart

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();