{"id":16556,"library":"twin-db","title":"TwinDB Local Database","description":"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.","status":"active","version":"1.1.2","language":"javascript","source_language":"en","source_url":"https://github.com/toddy007/twin-db","tags":["javascript","db","database","local","localdb","localdatabase","twin","typescript"],"install":[{"cmd":"npm install twin-db","lang":"bash","label":"npm"},{"cmd":"yarn add twin-db","lang":"bash","label":"yarn"},{"cmd":"pnpm add twin-db","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"TwinDB is an ES module only; requires `\"type\": \"module\"` in `package.json`. TypeScript types are included and recommended for usage.","wrong":"const TwinDB = require('twin-db');","symbol":"TwinDB","correct":"import TwinDB from 'twin-db';"}],"quickstart":{"code":"import TwinDB from 'twin-db';\nimport { readFileSync, unlinkSync } from 'fs';\n\n// Initialize a database named 'mydata'\nconst database = new TwinDB('mydata');\n\n// Ensure the database file is clean for demonstration\ntry { unlinkSync('mydata.json'); } catch (e) { /* ignore if not exists */ }\n\nconsole.log('Database initialized.');\n\n// Set initial values, demonstrating pathing\ndatabase.set('user.name', 'Alice');\ndatabase.set('user.age', 30);\ndatabase.set('items', ['apple', 'banana']);\ndatabase.set('metrics.views', 100);\n\nconsole.log('Initial data:\\n', JSON.parse(readFileSync('mydata.json', 'utf8')));\n\n// Get values\nconst userName = database.get('user.name');\nconsole.log(`\\nUser name: ${userName}`); // Alice\n\n// Update values using various methods\ndatabase.set('user.age', 31); // Now age is 31\ndatabase.sum('metrics.views', 50); // views is 150\ndatabase.push('items', 'orange', 'grape'); // Add more items\n\nconsole.log('\\nData after updates:\\n', JSON.parse(readFileSync('mydata.json', 'utf8')));\n\n// Delete a value\ndatabase.delete('user.age'); // Age is gone\n\nconsole.log('\\nData after deletion:\\n', JSON.parse(readFileSync('mydata.json', 'utf8')));\n\n// Clean up the database file\ntry { unlinkSync('mydata.json'); } catch (e) { /* ignore if not exists */ }\nconsole.log('\\nDatabase file cleaned up.');","lang":"typescript","description":"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."},"warnings":[{"fix":"Add `\"type\": \"module\"` to your `package.json` file. If your project uses CommonJS, consider transpiling or switching to an ESM-compatible setup.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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`).","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Change `const TwinDB = require('twin-db');` to `import TwinDB from 'twin-db';`. Also, ensure your `package.json` file includes `\"type\": \"module\"`.","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.","error":"ReferenceError: require is not defined in ES module scope"},{"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`).","cause":"You attempted to store a non-JSON serializable value (e.g., a JavaScript function, `undefined`, or a class instance) at the specified path.","error":"Value at path 'user.settings' is null after set operation."},{"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.","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.","error":"TypeError: Cannot read properties of undefined (reading 'sum')"}],"ecosystem":"npm"}