Registry / database / file-system-db

file-system-db

JSON →
library2.1.0jsnpmunverified

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.

npm install file-system-db
INSTALL
IMPORT
SIG · FILE-SYSTEM-DB
F
file-system-db
databasejavascriptv2.1.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

FSDB
import { FSDB } from 'file-system-db';
import FSDB from 'file-system-db';
ESM import for the main FSDB class, typically used in TypeScript or modern Node.js environments.
FSDB
const { FSDB } = require('file-system-db');
const FSDB = require('file-system-db');
CommonJS require for the main FSDB class, as shown in the package's documentation for Node.js.
FSDBOptions
import type { FSDBOptions } from 'file-system-db';
Type import for configuration options, useful for explicit type checking in TypeScript projects.

Initializes a file-system database, sets and retrieves key-value data with dot notation, updates, deletes, and creates a backup, then cleans up.

import { FSDB } from 'file-system-db'; import * as path from 'path'; import * as fs from 'fs'; // Define a temporary database path for demonstration const dbPath = path.join(process.cwd(), 'temp_fsdb_test.json'); // Ensure the database file doesn't exist from previous runs for a clean start if (fs.existsSync(dbPath)) { fs.unlinkSync(dbPath); } // 1. Initialize a database instance // You can specify a custom path and compaction setting. // Here, we use a temporary file and disable compaction for human readability during test. const db = new FSDB(dbPath, false); console.log(`Database initialized at: ${dbPath}`); // 2. Set values using keys and dot notation db.set('user.id', '12345'); db.set('user.name', 'Alice'); db.set('products', [{ id: 1, name: 'Laptop' }, { id: 2, name: 'Mouse' }]); console.log('Data set for user and products.'); // 3. Retrieve values const userId = db.get('user.id'); const products = db.get('products'); console.log(`Retrieved user ID: ${userId}`); console.log('Retrieved products:', products); // 4. Update a value db.set('user.name', 'Alice Smith'); console.log(`Updated user name: ${db.get('user.name')}`); // 5. Delete a value db.delete('user.id'); console.log(`User ID after deletion: ${db.get('user.id')}`); // Expected: undefined // 6. Backup the database db.backup(path.join(process.cwd(), 'temp_fsdb_backup.json')); console.log('Database backup created.'); // Clean up the temporary database files after the example if (fs.existsSync(dbPath)) { fs.unlinkSync(dbPath); } const backupPath = path.join(process.cwd(), 'temp_fsdb_backup.json'); if (fs.existsSync(backupPath)) { fs.unlinkSync(backupPath); } console.log(`Cleaned up temporary database files.`);
Debug
Known issues
breakingMigrating 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.
fix
Refer to the v2 migration guide at https://github.com/WillTDA/File-System-DB/pull/6 to understand the necessary code adjustments.
affects: >=2.0.0
gotchaThis 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.
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.
affects: >=1.0.0
gotchaAll 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.
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.
affects: >=1.0.0
gotchaThe 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.
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.
affects: >=1.0.0
Errors
Common errors & fixes
Error: ENOENT: no such file or directory, open './invalid/path/db.json'
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.
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.
SyntaxError: Unexpected token ... in JSON at position ...
The underlying JSON database file has been corrupted or manually edited with invalid JSON syntax, preventing the library from parsing it.
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.
TypeError: db.set is not a function
The `db` variable was not correctly initialized as an instance of `FSDB`, or `require`/`import` did not correctly expose the `FSDB` class.
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');`).
Upgrade
Version history
2.1.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
5 hits · last 30 days
node
4
Amazon
1
Resources
file-system-db — npm install file-system-db · libregistry