🗄️ sal7an.db

v2.0.0 — JSON database that doesn't mess around

✨ What's new in v2

| Feature | v1 | v2 | |---|---|---| | Nested keys (user.name) | ❌ | ✅ | | TypeScript types | ❌ | ✅ | | Event system | ❌ | ✅ | | In-memory cache | ❌ | ✅ | | Encryption | ❌ | ✅ | | Timestamps | ❌ | ✅ | | pull, includes, search | ❌ | ✅ | | setMany, getMany, filter, map | ❌ | ✅ | | import / export | ❌ | ✅ | | Auto-backup | ❌ | ✅ | | Default values on get | ❌ | ✅ |

📦 Installation

npm install sal7an.db

🚀 Quick Start

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

db.set('user.name', 'Ahmed');
db.get('user.name'); // "Ahmed"

⚙️ Options

const db = require('sal7an.db')({
  path: 'data/mydb.json',     // custom file path
  cache: true,                 // in-memory cache (faster reads)
  encryption: true,            // XOR encryption
  encryptionKey: 'mySecret',   // encryption key
  timestamps: true,            // track createdAt / updatedAt
  backupInterval: 3600000,     // auto-backup every 1h (ms)
  prettify: true,              // pretty-print JSON
});

📖 API Reference

Core CRUD

db.set(key, value)

Supports dot notation for nested keys.

db.set('user.profile.age', 25);
// database.json:
// {
//   "user": {
//     "profile": {
//       "age": 25
//     }
//   }
// }

db.get(key, defaultValue?)

Returns defaultValue if key doesn't exist.

db.get('user.profile.age');       // 25
db.get('missing.key', 'nope');    // "nope"

db.has(key)

db.has('user.profile.age');  // true
db.has('ghost');             // false

db.delete(key)

Returns true if deleted, false if not found.

db.delete('user.profile.age');
// database.json:
// {
//   "user": {
//     "profile": {}
//   }
// }

Number Operations

db.add(key, value)

db.set('coins', 100);
db.add('coins', 50);
// { "coins": 150 }

db.subtract(key, value)

db.subtract('coins', 30);
// { "coins": 120 }

db.math(key, operator, value)

Operators: + - * / % **

db.set('score', 3);
db.math('score', '**', 3);
// { "score": 27 }

Array Operations

db.push(key, ...values)

Supports pushing multiple values at once.

db.push('fruits', 'apple', 'mango', 'banana');
// { "fruits": ["apple", "mango", "banana"] }

db.pull(key, value)

Remove a value from an array.

db.pull('fruits', 'mango');
// { "fruits": ["apple", "banana"] }

db.includes(key, value)

db.includes('fruits', 'apple');  // true
db.includes('fruits', 'mango');  // false

Bulk Operations

db.setMany(entries)

db.setMany({ name: 'Ahmed', coins: 500, level: 3 });
// { "name": "Ahmed", "coins": 500, "level": 3 }

db.getMany(keys[])

db.getMany(['name', 'coins']);
// { name: "Ahmed", coins: 500 }

db.deleteMany(keys[])

db.deleteMany(['temp1', 'temp2']);

db.all()

Returns array of { key, value } entries (top-level).

db.all();
// [
//   { key: "name", value: "Ahmed" },
//   { key: "coins", value: 500 }
// ]

db.fetchAll()

Returns the raw database object.

db.fetchAll();
// { "name": "Ahmed", "coins": 500 }

db.search(query)

Filter by string, RegExp, or function.

db.set('user_1', 'Ahmed');
db.set('user_2', 'Salem');
db.search('user_');
// [
//   { key: "user_1", value: "Ahmed" },
//   { key: "user_2", value: "Salem" }
// ]

db.search(/^user/);
db.search((key, value) => typeof value === 'number' && value > 100);

db.filter(fn)

db.filter((key, value) => typeof value === 'number');
// Returns only numeric entries

db.forEach(fn)

db.forEach((key, value) => console.log(key, value));

Backup & Import/Export

db.backup(fileName)

db.backup('mybackup_2025');
// Creates: mybackup_2025.json

db.import(source, merge?)

db.import('old_backup.json');          // replace
db.import('old_backup.json', true);    // merge
db.import({ extra: 'data' }, true);    // from object

db.export()

const snapshot = db.export();
// Returns plain JS object

db.reset()

db.reset();
// database.json => {}

Stats & Info

db.info()

db.info();
// {
//   path: "database.json",
//   size: 5,
//   fileSize: "1.2 KB",
//   cacheEnabled: true,
//   encryption: false,
//   timestamps: false
// }

db.size()

db.size(); // number of top-level keys

db.getMeta(key)

Requires timestamps: true in options.

db.getMeta('coins');
// { createdAt: "2025-01-01T00:00:00.000Z", updatedAt: "2025-06-01T00:00:00.000Z" }

Event System

db.on('set',    (key, value) => console.log(`Set: ${key}`));
db.on('delete', (key)        => console.log(`Deleted: ${key}`));
db.on('push',   (key, vals)  => console.log(`Pushed to: ${key}`));
db.on('backup', (file)       => console.log(`Backup: ${file}`));
db.on('reset',  ()           => console.log('Database reset'));

📬 Contact

Discord: @5.i4

📄 License

MIT