TwinDB Local Database

Common errors

• ReferenceError: require is not defined in ES module scope

  cause Attempting to use CommonJS `require()` syntax to import `twin-db` in an ES module environment, or `twin-db` is being imported as an ES module in a project not configured for ESM.
  fix Change `const TwinDB = require('twin-db');` to `import TwinDB from 'twin-db';`. Also, ensure your `package.json` file includes `"type": "module"`.

• Value at path 'user.settings' is null after set operation.

  cause You attempted to store a non-JSON serializable value (e.g., a JavaScript function, `undefined`, or a class instance) at the specified path.
  fix TwinDB converts non-JSON values to `null`. Review the value you are passing to the `set` method and ensure it is a valid JSON type (string, number, boolean, array, object, or `null`).

• TypeError: Cannot read properties of undefined (reading 'sum')

  cause This error might occur if you're attempting to call `database.sum()` or similar methods on a path that expects a number but currently holds a non-numeric value or doesn't exist in older versions.
  fix Ensure the target path for `sum` or `sub` operations holds a numeric value. If the path might be missing, consider upgrading to `twin-db >=1.1.0` for automatic initialization or manually `set` an initial numeric value (e.g., `0`) first.

Warnings

• breaking TwinDB is an ES module (ESM) package and requires `"type": "module"` in your `package.json` file. Attempting to use it in a CommonJS environment without this configuration will result in errors.
  Fix: Add `"type": "module"` to your `package.json` file. If your project uses CommonJS, consider transpiling or switching to an ESM-compatible setup.
• gotcha TwinDB only accepts JSON-compatible values. If you attempt to store non-JSON serializable data (e.g., functions, `undefined`, circular objects), those values will be automatically coerced to `null` silently.
  Fix: Always ensure that the data you are attempting to `set` or `push` into TwinDB is serializable to JSON (strings, numbers, booleans, arrays, objects, `null`).
• gotcha Prior to version 1.1.0, methods like `sum`, `sub`, and `push` might have behaved inconsistently or thrown errors if the target path did not exist. As of 1.1.0, these methods will now initialize the path with the provided value if it does not already exist.
  Fix: Upgrade to `twin-db >=1.1.0` to benefit from the improved behavior where `sum`, `sub`, and `push` will automatically initialize non-existent paths. If using older versions, ensure paths are initialized before calling these methods.

Install

• npm install twin-db npm
• yarn add twin-db yarn
• pnpm add twin-db pnpm

Imports

• TwinDB
  wrong:

  const TwinDB = require('twin-db');

  correct:

  import TwinDB from 'twin-db';

  TwinDB is an ES module only; requires `"type": "module"` in `package.json`. TypeScript types are included and recommended for usage.

Quickstart

This quickstart demonstrates how to initialize a TwinDB database, set and retrieve values using object paths, perform atomic updates like sum and push, and delete entries. It also includes cleanup for a runnable example.

import TwinDB from 'twin-db';
import { readFileSync, unlinkSync } from 'fs';

// Initialize a database named 'mydata'
const database = new TwinDB('mydata');

// Ensure the database file is clean for demonstration
try { unlinkSync('mydata.json'); } catch (e) { /* ignore if not exists */ }

console.log('Database initialized.');

// Set initial values, demonstrating pathing
database.set('user.name', 'Alice');
database.set('user.age', 30);
database.set('items', ['apple', 'banana']);
database.set('metrics.views', 100);

console.log('Initial data:\n', JSON.parse(readFileSync('mydata.json', 'utf8')));

// Get values
const userName = database.get('user.name');
console.log(`\nUser name: ${userName}`); // Alice

// Update values using various methods
database.set('user.age', 31); // Now age is 31
database.sum('metrics.views', 50); // views is 150
database.push('items', 'orange', 'grape'); // Add more items

console.log('\nData after updates:\n', JSON.parse(readFileSync('mydata.json', 'utf8')));

// Delete a value
database.delete('user.age'); // Age is gone

console.log('\nData after deletion:\n', JSON.parse(readFileSync('mydata.json', 'utf8')));

// Clean up the database file
try { unlinkSync('mydata.json'); } catch (e) { /* ignore if not exists */ }
console.log('\nDatabase file cleaned up.');