{"id":16621,"library":"file-system-db","title":"File System DB","description":"File System DB (FSDB) is a lightweight, synchronous, file-based JSON database designed for Node.js environments, currently at version 2.1.0. It allows developers to store and retrieve data using a key-value paradigm, supporting dot notation for nested JSON fields. A key differentiator is its simplicity and lack of external dependencies, relying solely on Node.js's built-in File System module. Data is stored directly as human-readable JSON files, making it easy to inspect and manage backups. While highly accessible, its synchronous nature means operations can potentially block the event loop for very large datasets, and its reliance on persistent file storage makes it unsuitable for ephemeral hosting environments like Heroku or Vercel. The library ships with TypeScript types, enhancing developer experience for type-safe applications. New minor versions appear to be released on an as-needed basis.","status":"active","version":"2.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/WillTDA/File-System-DB","tags":["javascript","database","db","file-based","fs","json","local","node","nodejs","typescript"],"install":[{"cmd":"npm install file-system-db","lang":"bash","label":"npm"},{"cmd":"yarn add file-system-db","lang":"bash","label":"yarn"},{"cmd":"pnpm add file-system-db","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM import for the main FSDB class, typically used in TypeScript or modern Node.js environments.","wrong":"import FSDB from 'file-system-db';","symbol":"FSDB","correct":"import { FSDB } from 'file-system-db';"},{"note":"CommonJS require for the main FSDB class, as shown in the package's documentation for Node.js.","wrong":"const FSDB = require('file-system-db');","symbol":"FSDB","correct":"const { FSDB } = require('file-system-db');"},{"note":"Type import for configuration options, useful for explicit type checking in TypeScript projects.","symbol":"FSDBOptions","correct":"import type { FSDBOptions } from 'file-system-db';"}],"quickstart":{"code":"import { FSDB } from 'file-system-db';\nimport * as path from 'path';\nimport * as fs from 'fs';\n\n// Define a temporary database path for demonstration\nconst dbPath = path.join(process.cwd(), 'temp_fsdb_test.json');\n\n// Ensure the database file doesn't exist from previous runs for a clean start\nif (fs.existsSync(dbPath)) {\n  fs.unlinkSync(dbPath);\n}\n\n// 1. Initialize a database instance\n// You can specify a custom path and compaction setting.\n// Here, we use a temporary file and disable compaction for human readability during test.\nconst db = new FSDB(dbPath, false);\nconsole.log(`Database initialized at: ${dbPath}`);\n\n// 2. Set values using keys and dot notation\ndb.set('user.id', '12345');\ndb.set('user.name', 'Alice');\ndb.set('products', [{ id: 1, name: 'Laptop' }, { id: 2, name: 'Mouse' }]);\nconsole.log('Data set for user and products.');\n\n// 3. Retrieve values\nconst userId = db.get('user.id');\nconst products = db.get('products');\n\nconsole.log(`Retrieved user ID: ${userId}`);\nconsole.log('Retrieved products:', products);\n\n// 4. Update a value\ndb.set('user.name', 'Alice Smith');\nconsole.log(`Updated user name: ${db.get('user.name')}`);\n\n// 5. Delete a value\ndb.delete('user.id');\nconsole.log(`User ID after deletion: ${db.get('user.id')}`); // Expected: undefined\n\n// 6. Backup the database\ndb.backup(path.join(process.cwd(), 'temp_fsdb_backup.json'));\nconsole.log('Database backup created.');\n\n// Clean up the temporary database files after the example\nif (fs.existsSync(dbPath)) {\n  fs.unlinkSync(dbPath);\n}\nconst backupPath = path.join(process.cwd(), 'temp_fsdb_backup.json');\nif (fs.existsSync(backupPath)) {\n  fs.unlinkSync(backupPath);\n}\nconsole.log(`Cleaned up temporary database files.`);","lang":"typescript","description":"Initializes a file-system database, sets and retrieves key-value data with dot notation, updates, deletes, and creates a backup, then cleans up."},"warnings":[{"fix":"Refer to the v2 migration guide at https://github.com/WillTDA/File-System-DB/pull/6 to understand the necessary code adjustments.","message":"Migrating from v1 to v2 involves significant changes to the API and internal structure. The package authors recommend reviewing the specific pull request detailing the changes before upgrading.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Use a cloud-based database service (e.g., MongoDB Atlas, PostgreSQL, Firebase) for applications deployed on ephemeral platforms. File System DB is best suited for local development, desktop applications, or dedicated servers with persistent storage.","message":"This package saves data persistently to the local file system. This makes it unsuitable for ephemeral hosting environments like Heroku, Vercel, AWS Lambda, or other serverless functions where file system changes are not preserved across instances or invocations.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For applications requiring high concurrency, large data volumes, or non-blocking I/O, consider an asynchronous database solution. Minimize the frequency of write operations or offload heavy database tasks to worker threads if using FSDB in a performance-critical application.","message":"All database operations in File System DB are synchronous. While the package claims operations are fast, extensive use with very large datasets or frequent writes could potentially block the Node.js event loop, leading to performance bottlenecks and unresponsiveness in high-load scenarios.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Regularly use the `db.backup()` function to create recovery points. Implement robust error handling around database operations. Avoid direct manual editing of the database JSON file while the application is running.","message":"The database relies on a single JSON file. Manual corruption of this file (e.g., malformed JSON syntax) by external processes or unexpected power loss during a write operation can lead to data loss or unreadable database states.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure the directory where the database file or backup file is intended to be created already exists. Use `path.join()` for cross-platform paths and consider `fs.mkdirSync(path.dirname(dbPath), { recursive: true });` if directories need to be created dynamically.","cause":"The specified path for the database file or a backup file does not exist, and the library needs a valid directory to create the file.","error":"Error: ENOENT: no such file or directory, open './invalid/path/db.json'"},{"fix":"Inspect the database JSON file at the specified path for syntax errors. If a backup is available, restore from the last valid backup. Avoid manual editing of the live database file.","cause":"The underlying JSON database file has been corrupted or manually edited with invalid JSON syntax, preventing the library from parsing it.","error":"SyntaxError: Unexpected token ... in JSON at position ..."},{"fix":"Ensure you are correctly initializing the database with `const db = new FSDB();` or `const db = new FSDB('./my-db.json');`. Verify your `import` or `require` statement matches the package's export structure (e.g., `const { FSDB } = require('file-system-db');`).","cause":"The `db` variable was not correctly initialized as an instance of `FSDB`, or `require`/`import` did not correctly expose the `FSDB` class.","error":"TypeError: db.set is not a function"}],"ecosystem":"npm"}