File System DB

Common errors

• Error: ENOENT: no such file or directory, open './invalid/path/db.json'

  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.
  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 ...

  cause 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

  cause 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');`).

Warnings

• breaking 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.
  Fix: Refer to the v2 migration guide at https://github.com/WillTDA/File-System-DB/pull/6 to understand the necessary code adjustments.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install file-system-db npm
• yarn add file-system-db yarn
• pnpm add file-system-db pnpm

Imports

• FSDB
  wrong:

  import FSDB from 'file-system-db';

  correct:

  import { FSDB } from 'file-system-db';

  ESM import for the main FSDB class, typically used in TypeScript or modern Node.js environments.
• FSDB
  wrong:

  const FSDB = require('file-system-db');

  correct:

  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.

Quickstart

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.`);