Registry / database / twin-db

twin-db

JSON →
library1.1.2jsnpmunverified

TwinDB is a lightweight, local, file-based database designed for Node.js applications, currently at version 1.1.2. It stores data in JSON files, making it suitable for small-scale applications, configuration management, or local development environments where a full-fledged database system is overkill. Its key differentiator lies in its straightforward API for manipulating JSON structures directly through object paths, offering methods like `set`, `get`, `delete`, `sum`, `sub`, `concat`, `push`, and `pull`. While it doesn't offer advanced features like transactions or complex querying found in relational or NoSQL databases, it excels in providing a simple, persistent data store. The project appears to have an ad-hoc release cadence, with recent updates indicating active maintenance, focusing on utility and ease of use. It specifically requires an ES module environment.

npm install twin-db
INSTALL
IMPORT
SIG · TWIN-DB
T
twin-db
databasejavascriptv1.1.2
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.

TwinDB
✓ import TwinDB from 'twin-db';
✗ const TwinDB = require('twin-db');
TwinDB is an ES module only; requires `"type": "module"` in `package.json`. TypeScript types are included and recommended for usage.

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.');
Debug
Known issues
breakingTwinDB 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.
affects: >=1.0.0
gotchaTwinDB 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`).
affects: >=1.0.0
gotchaPrior 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.
affects: <1.1.0
Errors
Common errors & fixes
ReferenceError: require is not defined in ES module scope
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.
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')
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.
Upgrade
Version history
1.1.2latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
22 hits · last 30 days
node
18
OpenAI (training)
1
Resources
twin-db — npm install twin-db · libregistry