Pro.db

Common errors

• ReferenceError: require is not defined in ES module scope

  cause Attempting to use `require()` in an ECMAScript Module (ESM) context (e.g., in a file where `type: module` is set in `package.json` or imported via `import`). pro.db is primarily a CommonJS package.
  fix Change your project or file to use CommonJS (`const db = require('pro.db');`) or transpile your ESM code to CJS before running. Alternatively, if your Node.js version supports it, you might be able to use dynamic import `import('pro.db').then(db => { /* use db */ });`.

• TypeError: db.set is not a function

  cause This usually indicates that `db` did not correctly resolve to the `pro.db` module's exported object. This can happen if you tried `import db from 'pro.db'` in a CJS-only context without proper TypeScript/Babel setup, or if the module itself was malformed.
  fix Ensure you are using `const db = require('pro.db');` for Node.js CommonJS environments. If using TypeScript, check your `tsconfig.json` for `esModuleInterop` and `allowSyntheticDefaultImports` or provide a custom module declaration.

• EACCES: permission denied, open 'database.json'

  cause The Node.js process does not have sufficient read/write permissions for the directory where `pro.db` attempts to create or access its database file (typically `database.json` in the current working directory).
  fix Ensure the user running the Node.js application has read and write permissions to the directory where the database file is stored. You may need to change directory permissions (e.g., `chmod 777 your-data-directory`) or run the application with elevated privileges (use with caution).

Warnings

• gotcha pro.db performs file I/O operations synchronously. In long-running or high-traffic Node.js applications, extensive synchronous disk access can block the event loop, leading to performance degradation or unresponsiveness.
  Fix: For performance-critical applications, consider a database solution with asynchronous I/O or use pro.db for minimal, infrequent writes. Wrap calls in a worker thread if blocking I/O is unavoidable for heavy usage patterns.
• breaking The `db.reset()` function permanently deletes all data from the database. There is no confirmation prompt or undo mechanism built into the function itself.
  Fix: Implement robust confirmation logic in your application code before invoking `db.reset()`. Ensure backups are performed regularly using `db.backup()`.
• gotcha The package is primarily built for CommonJS (CJS) environments. Directly using ESM `import` statements without proper transpilation or Node.js module resolution configuration (`"type": "module"` with `"exports"` field) can lead to runtime errors.
  Fix: For Node.js projects, use `const db = require('pro.db');`. If you must use ESM, ensure your project is configured with `"type": "module"` in `package.json` and investigate specific interoperability solutions or use a bundler.
• gotcha Error handling for file system operations (e.g., permission issues, disk full) is not explicitly demonstrated in the quickstart and may require manual `try...catch` blocks around `pro.db` calls if you need to gracefully handle such failures.
  Fix: Wrap `pro.db` operations in `try...catch` blocks to handle potential file system errors gracefully. For example, catching `EACCES` for permission denied errors.

Install

• npm install pro.db npm
• yarn add pro.db yarn
• pnpm add pro.db pnpm

Imports

• db
  wrong:

  import db from 'pro.db';

  correct:

  const db = require('pro.db');

  The package is primarily designed for CommonJS. Direct ESM import might lead to 'require is not defined' errors if not transpiled or used with specific module loaders.
• db (individual functions)
  wrong:

  const db = require('pro.db').db;

  correct:

  const { set, get } = require('pro.db');

  While the main export is an object with methods, destructuring is possible for convenience, though less common than importing the whole object.
• Pro.db in TypeScript
  wrong:

  import * as db from 'pro.db';

  correct:

  import db from 'pro.db';

  If using TypeScript, you might need a custom `d.ts` declaration for CommonJS modules (e.g., `declare module 'pro.db' { const db: any; export = db; }`) or enable `esModuleInterop` and `allowSyntheticDefaultImports` in `tsconfig.json` to use `import db from 'pro.db';`.

Quickstart

This example demonstrates common CRUD operations (set, get, add, push, delete) with pro.db, including checking key existence, fetching all data, and creating a backup file, highlighting its synchronous nature and file-based storage.

const db = require('pro.db');
const path = require('path');
const fs = require('fs');

const dbFilePath = path.join(__dirname, 'database.json');
// Ensure the database file exists or is created before operations
if (!fs.existsSync(dbFilePath)) {
  fs.writeFileSync(dbFilePath, '{}', 'utf8');
}

// Set a value
db.set('user:123:name', 'Alice');
db.set('user:123:age', 30);
db.set('products', [{ id: 1, name: 'Laptop' }, { id: 2, name: 'Mouse' }]);

console.log('User name:', db.get('user:123:name'));
console.log('Products:', db.get('products'));

// Add to a numeric key
db.add('user:123:age', 5);
console.log('New age:', db.get('user:123:age'));

// Push to an array key
db.push('products', { id: 3, name: 'Keyboard' });
console.log('Updated products:', db.get('products'));

// Check if a key exists
console.log('Has user:123:name?', db.has('user:123:name'));

// Delete a key
db.delete('user:123:name');
console.log('User name after delete:', db.get('user:123:name'));

// Fetch all data
console.log('All data:', db.fetchAll());

// Example of backup (create a dummy backup file)
db.backup('my_backup_file');
console.log('Backup initiated (check your file system for my_backup_file.json)');

// Caution: db.reset() will delete all data.
// Uncomment to clear the database:
// db.reset();
// console.log('Database reset. All data removed.');