spectre.db 1.0.0

package/LICENSE

@@ -0,0 +1,165 @@
+SPECTRE.DB SOURCE AVAILABLE LICENSE
+Version 1.0 — 2026
+
+Copyright (c) 2026 ScarysMonsters (https://github.com/ScarysMonsters)
+All rights reserved on the original work.
+
+================================================================================
+DEFINITIONS
+================================================================================
+
+"Software" refers to the spectre.db source code, documentation, examples,
+configuration files, and any associated materials published in this repository.
+
+"Author" refers to ScarysMonsters, the sole original creator and legal owner
+of the Software.
+
+"You" refers to any individual or legal entity exercising permissions granted
+by this License.
+
+"Derivative Work" means any work that is based on, incorporates, modifies,
+translates, or is otherwise derived from the Software or any substantial part
+of it, regardless of the form in which it is distributed.
+
+"Commercial Use" means any use of the Software or a Derivative Work that is
+primarily intended for or directed toward commercial advantage or monetary
+compensation, including but not limited to selling, licensing, or providing
+the Software as a service.
+
+================================================================================
+GRANT OF RIGHTS
+================================================================================
+
+Subject to the conditions and limitations set forth in this License, the Author
+grants You a worldwide, royalty-free, non-exclusive, non-transferable license to:
+
+  1. Use the Software for personal, educational, or non-commercial purposes.
+
+  2. Copy and redistribute the Software in source or compiled form, provided
+     that You comply with the conditions in this License.
+
+  3. Modify the Software and create Derivative Works, provided that You comply
+     with the conditions in this License.
+
+  4. Integrate the Software or Derivative Works into your own projects,
+     including Discord bots, automation tools, and other applications, provided
+     that such integration complies with the conditions in this License.
+
+================================================================================
+CONDITIONS
+================================================================================
+
+Any exercise of the rights granted above must satisfy all of the following
+conditions:
+
+  1. ATTRIBUTION REQUIRED
+     All copies, redistributions, or Derivative Works — whether in source or
+     binary form — must retain, in a clearly visible location:
+
+       a. The original copyright notice:
+          "Copyright (c) 2025 ScarysMonsters — spectre.db"
+
+       b. A reference to this License and a link to the original repository:
+          https://github.com/ScarysMonsters/spectre.db
+
+       c. A clear indication of any modifications made to the original Software,
+          with a description of what was changed and when.
+
+     Attribution must not suggest that the Author endorses You or your use of
+     the Software.
+
+  2. NO OWNERSHIP CLAIM
+     You may not represent, claim, imply, or otherwise assert — publicly or
+     privately — that You are the original author, creator, or owner of the
+     Software or any substantial portion of it. This prohibition applies
+     regardless of the extent of your modifications.
+
+     Publishing a Derivative Work under a different name does not transfer,
+     diminish, or otherwise affect the Author's intellectual property rights
+     over the original Software.
+
+  3. LICENSE PRESERVATION
+     All copies, redistributions, and Derivative Works must include a copy of
+     this License in full, without modification.
+
+  4. NO MISREPRESENTATION OF ORIGIN
+     You may not remove, obscure, alter, or replace any copyright notices,
+     license headers, authorship statements, or attribution markers present in
+     the original Software.
+
+  5. COMMERCIAL USE REQUIRES PRIOR WRITTEN CONSENT
+     Any Commercial Use of the Software or any Derivative Work requires the
+     Author's explicit, prior written authorization. To request commercial
+     authorization, contact the Author through the official repository.
+
+     Unauthorized Commercial Use constitutes a material breach of this License
+     and an infringement of the Author's intellectual property rights.
+
+================================================================================
+INTELLECTUAL PROPERTY AND ENFORCEMENT
+================================================================================
+
+The Software, including its architecture, design, logic, and original
+expression, is the exclusive intellectual property of ScarysMonsters.
+
+The Author reserves all rights not expressly granted in this License, including
+but not limited to:
+
+  — The right to revoke this License for any individual or entity found in
+    breach of its conditions, effective immediately upon written notice.
+
+  — The right to issue takedown requests, DMCA notices, or equivalent
+    intellectual property enforcement actions against any person, organization,
+    platform, or registry (including but not limited to npm, GitHub, GitLab,
+    PyPI, or any package registry) distributing the Software or a Derivative
+    Work in violation of this License.
+
+  — The right to pursue civil remedies, including injunctive relief and
+    damages, under applicable copyright and intellectual property laws, in any
+    jurisdiction where such violations occur.
+
+  — The right to request the removal or delisting of any project, package,
+    repository, or publication that infringes upon the Author's rights under
+    this License or applicable law, through administrative, legal, or platform
+    enforcement mechanisms.
+
+The Author's failure to enforce any provision of this License at any time shall
+not be construed as a waiver of the Author's rights to enforce such provision
+at a later time or in other circumstances.
+
+================================================================================
+DISCLAIMER OF WARRANTIES
+================================================================================
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
+
+IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+================================================================================
+TERMINATION
+================================================================================
+
+This License and the rights granted hereunder will terminate automatically and
+immediately upon any breach by You of the conditions set forth in this License.
+
+Upon termination, You must cease all use, distribution, and possession of the
+Software and all Derivative Works, and destroy all copies in your control.
+
+Termination of this License does not limit the Author's right to pursue
+additional remedies for damages or injunctive relief arising from the breach.
+
+================================================================================
+CONTACT
+================================================================================
+
+For questions regarding this License, commercial use authorization, or to
+report a violation:
+
+  GitHub:     https://github.com/ScarysMonsters
+  Repository: https://github.com/ScarysMonsters/spectre.db
+  Issues:     https://github.com/ScarysMonsters/spectre.db/issues

package/README.md

@@ -0,0 +1,253 @@
+> [!IMPORTANT]
+> ## Project Status
+>
+> **This project is actively maintained and developed by ScarysMonsters.**
+
+> [!NOTE]
+> **spectre.db is a zero-dependency, production-grade file-based JSON database for Node.js bots and small applications.**
+> **Built on a WAL (Write-Ahead Log) architecture with atomic writes, LRU cache, real transactions, and optional AES-256 encryption.**
+
+## About
+
+<strong>Welcome to `spectre.db`, a Node.js module that provides a lightweight, persistent key-value database engineered for Discord bots and backend services.</strong>
+
+- spectre.db is a [Node.js](https://nodejs.org) module with **zero external dependencies** — powered entirely by Node.js built-ins.
+- Uses a **WAL + snapshot** architecture so your data is never at risk from an unclean shutdown.
+
+<div align="center">
+  <p>
+    <a href="https://www.npmjs.com/package/spectre.db"><img src="https://img.shields.io/npm/v/spectre.db.svg" alt="npm version" /></a>
+    <a href="https://www.npmjs.com/package/spectre.db"><img src="https://img.shields.io/npm/dt/spectre.db.svg" alt="npm downloads" /></a>
+    <a href="https://github.com/ScarysMonsters/spectre.db"><img src="https://img.shields.io/github/stars/ScarysMonsters/spectre.db?style=flat" alt="GitHub stars" /></a>
+    <a href="https://github.com/ScarysMonsters/spectre.db/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/spectre.db.svg" alt="license" /></a>
+  </p>
+</div>
+
+### <strong>[Example Code](https://github.com/ScarysMonsters/spectre.db/tree/main/examples)</strong>
+
+---
+
+## Features
+
+- [x] Zero external dependencies (pure Node.js built-ins)
+- [x] WAL-based persistence — never rewrites the full file on every change
+- [x] Atomic writes — crash-safe temp file + rename pattern
+- [x] Backup rotation — configurable generations (`.1.bak`, `.2.bak`, ...)
+- [x] O(1) LRU cache with prefix-index invalidation
+- [x] Real transactions — function-based with automatic rollback on error
+- [x] Legacy array transaction API — fully backward compatible
+- [x] AES-256-GCM encryption — auto-applied to sensitive keys (`token`, `password`, `secret`, ...)
+- [x] Table abstraction — scoped key namespacing
+- [x] Dot-notation keys — `users.123.coins` works out of the box
+- [x] Prototype pollution prevention by design
+- [x] Events: `change`, `save`, `rollback`, `restore`, `clear`
+- [ ] TypeScript types (planned)
+
+---
+
+## Installation
+
+> [!NOTE]
+> **Node.js 18.0.0 or newer is required**
+
+```sh-session
+npm install spectre.db@latest
+```
+
+---
+
+## Quick Start
+
+```js
+const { Database } = require('spectre.db');
+
+const db = new Database('./data/mydb', {
+  cache:    true,
+  autoSave: 5000,
+  backup:   true,
+});
+
+db.ready.then(() => {
+  db.set('users.1.name', 'Alice');
+  console.log(db.get('users.1.name')); // 'Alice'
+});
+```
+
+---
+
+## Discord Bot Example
+
+```js
+const { Client, GatewayIntentBits } = require('discord.js');
+const { Database } = require('spectre.db');
+
+const client = new Client({ intents: [GatewayIntentBits.Guilds] });
+
+const db = new Database('./src/data/database', {
+  cache:    true,
+  autoSave: 5000,
+  backup:   true,
+});
+
+client.db = db;
+
+db.ready.then(() => client.login(process.env.TOKEN));
+
+client.once('ready', () => {
+  console.log(`${client.user.tag} is ready!`);
+});
+
+process.on('SIGINT', async () => {
+  await client.db.close();
+  process.exit(0);
+});
+```
+
+---
+
+## API Reference
+
+### Constructor
+
+```js
+new Database(path, options?)
+```
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `cache` | boolean | `true` | Enable LRU cache |
+| `maxCacheSize` | number | `1000` | Max cached entries |
+| `cacheTTL` | number | `0` | TTL in ms (0 = forever) |
+| `autoSave` | number | `5000` | Compaction interval in ms |
+| `backup` | boolean | `true` | Enable backup rotation |
+| `backupCount` | number | `3` | Number of backup generations |
+| `compress` | boolean | `false` | Gzip snapshot compression |
+| `encryptionKey` | string/Buffer | `null` | AES-256-GCM key for sensitive values |
+| `warmKeys` | string[] | `[]` | Keys to pre-load into cache on startup |
+
+---
+
+### Core Methods
+
+```js
+db.get('users.1.name')              // → value or null
+db.set('users.1.name', 'Alice')     // → value
+db.delete('users.1.name')           // → true / false
+db.has('users.1.name')              // → true / false
+db.add('users.1.coins', 100)        // → new value
+db.sub('users.1.coins', 50)         // → new value
+db.push('users.1.roles', 'admin')   // → new array length
+db.pull('users.1.roles', 'member')  // → true / false
+```
+
+### Query Methods
+
+```js
+db.all()                                              // → [{ ID, data }]
+db.startsWith('users.')                               // → [{ ID, data }]
+db.filter((data, id) => id.endsWith('.coins'))        // → [{ ID, data }]
+db.find((data, id)   => id === 'users.1.name')        // → { ID, data } | null
+db.paginate('users.', page, limit, sortBy, sortDesc)  // → { data, pagination }
+```
+
+### Transactions
+
+```js
+// Function-based (recommended)
+await db.transaction(async (tx) => {
+  const coins = tx.get('users.1.coins') ?? 0;
+  tx.set('users.1.coins', coins - 50);
+  tx.set('users.2.coins', (tx.get('users.2.coins') ?? 0) + 50);
+});
+
+// Array-based (legacy — fully supported)
+await db.transaction([
+  { type: 'set',    key: 'config.debug',  value: true },
+  { type: 'add',    key: 'stats.logins',  value: 1    },
+  { type: 'delete', key: 'cache.tmp'                  },
+]);
+```
+
+### Tables
+
+```js
+const users = db.table('users');
+
+users.set('1.name', 'Alice')   // stored as "users.1.name"
+users.get('1.name')            // 'Alice'
+users.count()                  // number of entries
+await users.clear()            // removes all users.*
+
+await users.transaction(async (tx) => {
+  tx.add('1.coins', 100);
+});
+```
+
+### Persistence & Lifecycle
+
+```js
+await db.save()    // force compaction now
+await db.close()   // flush + compact + release (always call on shutdown)
+db.getStats()      // { entries, cacheSize, fileSize, walOps, ... }
+```
+
+---
+
+## How it works
+
+### Files on disk
+
+```
+data/
+├── mydb.snapshot         ← compacted JSON state
+├── mydb.wal              ← append-only operation log
+├── mydb.snapshot.1.bak   ← most recent backup
+├── mydb.snapshot.2.bak
+└── mydb.snapshot.3.bak
+```
+
+### Write flow
+
+```
+db.set('x', 1)
+  └─ updates in-memory store immediately (synchronous)
+  └─ WAL append queued (async, non-blocking)
+
+Every compactInterval:
+  └─ if walOps >= compactThreshold:
+       └─ serialize → unique temp file → atomic rename → truncate WAL
+```
+
+### Startup flow
+
+```
+new Database(path)
+  └─ load .snapshot
+  └─ replay .wal on top of snapshot
+  └─ open WAL for appending
+  └─ db.ready resolves
+```
+
+---
+
+## Contributing
+
+- Before creating an issue, please ensure that it hasn't already been reported/suggested.
+- See [the contribution guide](https://github.com/ScarysMonsters/spectre.db/blob/main/.github/CONTRIBUTING.md) if you'd like to submit a PR.
+
+## Need help?
+
+GitHub Issues: [Here](https://github.com/ScarysMonsters/spectre.db/issues)
+
+---
+
+## Other project(s)
+
+- 🤖 [***ScarysMonsters***](https://github.com/ScarysMonsters) <br/>
+  More tools and bots.
+
+---
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=ScarysMonsters/spectre.db&type=Date)](https://star-history.com/#ScarysMonsters/spectre.db&Date)

package/examples/advanced.js

@@ -0,0 +1,85 @@
+'use strict';
+
+const { Database } = require('spectre.db');
+
+async function encryptionExample() {
+  console.log('--- Encryption ---');
+
+  const db = new Database('./data/secure', {
+    encryptionKey: 'my-super-secret-passphrase',
+  });
+
+  await db.ready;
+
+  db.set('user.token',    'discord-bot-token-abc123');
+  db.set('user.password', 'hunter2');
+  db.set('user.name',     'Alice');
+
+  console.log('token  (decrypted via get):', db.get('user.token'));
+  console.log('name   (plaintext):', db.get('user.name'));
+
+  await db.close();
+  console.log('');
+}
+
+async function tableExample() {
+  console.log('--- Tables ---');
+
+  const db = new Database('./data/tables');
+  await db.ready;
+
+  const guilds = db.table('guilds');
+  const users  = db.table('users');
+
+  guilds.set('123.prefix', '!');
+  guilds.set('123.lang',   'en');
+  guilds.set('456.prefix', '?');
+
+  users.set('99.xp',    0);
+  users.set('99.level', 1);
+
+  await guilds.transaction(async (tx) => {
+    tx.set('123.prefix', '$');
+    tx.set('123.modRole', 'moderator');
+  });
+
+  console.log('guild prefix:', guilds.get('123.prefix'));
+  console.log('guild count:', guilds.count());
+  console.log('user xp:', users.get('99.xp'));
+
+  await db.close();
+  console.log('');
+}
+
+async function compactionExample() {
+  console.log('--- Compaction ---');
+
+  const db = new Database('./data/compact', {
+    compactThreshold: 5,
+    compactInterval:  1000,
+  });
+
+  await db.ready;
+
+  db.on('save', (stats) => {
+    console.log('compacted — walOps reset, fileSize:', stats.fileSize, 'bytes');
+  });
+
+  for (let i = 0; i < 10; i++) {
+    db.set(`counter.${i}`, i * 10);
+  }
+
+  await db.save();
+
+  console.log('stats after manual save:', db.getStats());
+  await db.close();
+  console.log('');
+}
+
+async function main() {
+  await encryptionExample();
+  await tableExample();
+  await compactionExample();
+}
+
+main().catch(console.error);

package/examples/basic.js

@@ -0,0 +1,76 @@
+'use strict';
+
+const { Database } = require('spectre.db');
+
+async function main() {
+  const db = new Database('./data/mydb', {
+    cache:    true,
+    autoSave: 5000,
+    backup:   true,
+  });
+
+  await db.ready;
+
+  db.set('users.1.name',  'Alice');
+  db.set('users.1.coins', 0);
+  db.set('users.1.roles', ['member']);
+
+  console.log(db.get('users.1.name'));
+  console.log(db.has('users.1.coins'));
+
+  db.add('users.1.coins', 150);
+  db.sub('users.1.coins', 50);
+  console.log('coins:', db.get('users.1.coins'));
+
+  db.push('users.1.roles', 'admin');
+  console.log('roles:', db.get('users.1.roles'));
+
+  db.pull('users.1.roles', 'member');
+  console.log('roles after pull:', db.get('users.1.roles'));
+
+  db.set('users.2.name',  'Bob');
+  db.set('users.2.coins', 500);
+
+  const all = db.all();
+  console.log('all entries:', all.length);
+
+  const rich = db.filter((data, id) => id.endsWith('.coins') && data > 100);
+  console.log('rich users:', rich);
+
+  const { data, pagination } = db.paginate('users.', 1, 10, 'data', true);
+  console.log('page:', data.length, 'total:', pagination.total);
+
+  await db.transaction(async (tx) => {
+    tx.set('users.3.name',  'Charlie');
+    tx.set('users.3.coins', tx.get('users.1.coins') + 10);
+  });
+  console.log('tx result:', db.get('users.3.name'), db.get('users.3.coins'));
+
+  try {
+    await db.transaction(async (tx) => {
+      tx.set('users.4.name', 'Dave');
+      throw new Error('Something went wrong');
+    });
+  } catch {
+    console.log('rollback ok — users.4 exists:', db.has('users.4.name'));
+  }
+
+  const users = db.table('users');
+  console.log('table count:', users.count());
+  console.log('table get 1.name:', users.get('1.name'));
+
+  await db.transaction([
+    { type: 'set',    key: 'config.debug',   value: true },
+    { type: 'set',    key: 'config.version', value: 2    },
+    { type: 'delete', key: 'users.3.name'               },
+  ]);
+  console.log('legacy tx config.debug:', db.get('config.debug'));
+  console.log('legacy tx users.3.name (deleted):', db.get('users.3.name'));
+
+  console.log('stats:', db.getStats());
+
+  await db.close();
+  console.log('closed.');
+}
+
+main().catch(console.error);

package/examples/discord-bot.js

@@ -0,0 +1,103 @@
+'use strict';
+
+const { Client, GatewayIntentBits } = require('discord.js');
+const { Database } = require('spectre.db');
+
+const client = new Client({
+  intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages, GatewayIntentBits.MessageContent],
+});
+
+const db = new Database('./src/data/database', {
+  cache:    true,
+  autoSave: 5000,
+  backup:   true,
+});
+
+client.db = db;
+
+db.ready.then(() => {
+  console.log('[DB] Ready');
+  client.login(process.env.TOKEN);
+});
+
+client.once('ready', () => {
+  console.log(`[Bot] Logged in as ${client.user.tag}`);
+});
+
+client.on('messageCreate', async (message) => {
+  if (message.author.bot) return;
+
+  const prefix = '!';
+  if (!message.content.startsWith(prefix)) return;
+
+  const args    = message.content.slice(prefix.length).trim().split(/\s+/);
+  const command = args.shift().toLowerCase();
+
+  if (command === 'coins') {
+    const userId = message.author.id;
+    const coins  = client.db.get(`users.${userId}.coins`) ?? 0;
+    return message.reply(`You have **${coins}** coins.`);
+  }
+
+  if (command === 'daily') {
+    const userId  = message.author.id;
+    const lastKey = `users.${userId}.lastDaily`;
+    const last    = client.db.get(lastKey) ?? 0;
+    const now     = Date.now();
+    const cooldown = 24 * 60 * 60 * 1000;
+
+    if (now - last < cooldown) {
+      const remaining = Math.ceil((cooldown - (now - last)) / 3600000);
+      return message.reply(`Come back in ${remaining}h for your daily coins.`);
+    }
+
+    await client.db.transaction(async (tx) => {
+      const current = tx.get(`users.${userId}.coins`) ?? 0;
+      tx.set(`users.${userId}.coins`,     current + 100);
+      tx.set(`users.${userId}.lastDaily`, now);
+    });
+
+    return message.reply('You claimed your **100** daily coins!');
+  }
+
+  if (command === 'give') {
+    const target = message.mentions.users.first();
+    const amount = parseInt(args[1], 10);
+
+    if (!target || isNaN(amount) || amount <= 0) {
+      return message.reply('Usage: `!give @user <amount>`');
+    }
+
+    const senderId = message.author.id;
+    const balance  = client.db.get(`users.${senderId}.coins`) ?? 0;
+
+    if (balance < amount) {
+      return message.reply(`You only have **${balance}** coins.`);
+    }
+
+    await client.db.transaction(async (tx) => {
+      const senderCoins   = tx.get(`users.${senderId}.coins`)  ?? 0;
+      const receiverCoins = tx.get(`users.${target.id}.coins`) ?? 0;
+      tx.set(`users.${senderId}.coins`,   senderCoins   - amount);
+      tx.set(`users.${target.id}.coins`,  receiverCoins + amount);
+    });
+
+    return message.reply(`Sent **${amount}** coins to ${target.username}.`);
+  }
+
+  if (command === 'leaderboard') {
+    const { data } = client.db.paginate('users.', 1, 10, 'data', true);
+    const filtered = data.filter(({ ID }) => ID.endsWith('.coins'));
+    const lines    = filtered.map(({ ID, data: coins }, i) => {
+      const uid = ID.split('.')[1];
+      return `${i + 1}. <@${uid}> — ${coins} coins`;
+    });
+    return message.reply(lines.length ? lines.join('\n') : 'No data yet.');
+  }
+});
+
+process.on('SIGINT', async () => {
+  console.log('[Bot] Shutting down...');
+  await client.db.close();
+  process.exit(0);
+});