deepbase-sqlite 3.4.12 → 3.6.0

package/README.md

@@ -27,7 +27,8 @@ import SqliteDriver from 'deepbase-sqlite';
 
 const db = new DeepBase(new SqliteDriver({
   path: './data',
-  name: 'mydb'
+  name: 'mydb',
+  pragma: 'balanced' // default — omit for same result
 }));
 
 await db.connect();
@@ -42,6 +43,7 @@ const alice = await db.get('users', 'alice');
 new SqliteDriver({
   path: './data',              // Directory to store database files
   name: 'default',            // Database filename (without .db)
+  pragma: 'balanced',         // Performance profile: 'none' | 'safe' | 'balanced' | 'fast'
   nidAlphabet: 'ABC...',      // Alphabet for ID generation
   nidLength: 10               // Length of generated IDs
 })
@@ -75,6 +77,8 @@ Efficiently stores nested objects using a key-value schema:
 - Values are stored as JSON
 - Fast lookups for both exact keys and partial paths
 
+Each row also stores a monotonic `seq` so reads that rebuild objects use `ORDER BY seq, key`. That matches JavaScript insertion order for sibling keys and keeps `shift()` / `pop()` (via `DeepBase.keys()`) aligned with `JsonDriver`. Existing databases pick up `seq` via `ALTER TABLE` on connect (legacy rows default to `0`, then tie-break by `key`).
+
 ### ACID Compliance
 
 SQLite provides:
@@ -84,15 +88,56 @@ SQLite provides:
 - **Isolation**: Concurrent operations don't interfere
 - **Durability**: Committed data persists even after crashes
 
+## Pragma Modes
+
+`SqliteDriver` ships with four configurable performance profiles via the `pragma` option:
+
+| Mode | `synchronous` | `cache_size` | `mmap_size` | `WITHOUT ROWID` | Use case |
+|------|--------------|-------------|-------------|-----------------|----------|
+| **none** | — | — | — | No | Backward-compatible with databases created by older versions |
+| **safe** | FULL | 2 MB | off | Yes | Durability first, WAL + full fsync |
+| **balanced** *(default)* | NORMAL | 8 MB | 256 MB | Yes | Best mix of speed and safety for most apps |
+| **fast** | OFF | 16 MB | 256 MB | Yes | Maximum throughput — data may be lost on OS crash |
+
+All WAL modes use `journal_mode=WAL`, `temp_store=MEMORY`, and `busy_timeout=5000ms`.
+
+```javascript
+// Backward-compatible (no PRAGMAs, no WITHOUT ROWID)
+new SqliteDriver({ name: 'mydb', pragma: 'none' })
+
+// Maximum durability
+new SqliteDriver({ name: 'mydb', pragma: 'safe' })
+
+// Recommended (default)
+new SqliteDriver({ name: 'mydb', pragma: 'balanced' })
+
+// Maximum throughput
+new SqliteDriver({ name: 'mydb', pragma: 'fast' })
+```
+
+`SqliteFastDriver` is kept as a named alias for backward compatibility:
+
+```javascript
+import { SqliteFastDriver } from 'deepbase-sqlite';
+// SqliteFastDriver === SqliteDriver (same class, same options)
+```
+
 ## Database Structure
 
 Data is stored in a simple key-value table:
 
 ```sql
+-- pragma: 'none' (legacy-compatible)
 CREATE TABLE deepbase (
   key TEXT PRIMARY KEY,
   value TEXT NOT NULL
 )
+
+-- pragma: 'safe' | 'balanced' | 'fast' (optimized)
+CREATE TABLE deepbase (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+) WITHOUT ROWID
 ```
 
 Example data:
@@ -167,6 +212,27 @@ data/
 | Reliability | 💪 Very High | ⚠️ File corruption risk |
 | Debugging | 🔧 SQL tools | 👁️ Easy to inspect |
 
+## Benchmark — pragma modes
+
+Median of 3 runs, 1 000 iterations per operation. `balanced` vs `none`:
+
+```
+Operation                  none    safe    balanced    fast   Bal vs None
+─────────────────────────────────────────────────────────────────────────
+Sequential Write          4,525  17,296     84,701  98,238      +1772%
+Sequential Read          20,705  22,871     23,405  23,040        +13%
+Update                    2,689  10,666     17,764  18,857       +561%
+Increment                 4,291  14,129     25,734  26,364       +500%
+Delete                    3,806  12,010     20,884  21,074       +449%
+Batch Write               3,813  17,763     87,209  83,045      +2187%
+Concurrent Write          4,449  22,196     72,613 102,458      +1532%
+Deep Write (5-lvl)        4,311  26,740     53,957  91,312      +1152%
+Obj Expansion             1,997     365     34,633  47,318      +1634%
+Session Lifecycle           572   2,465      3,700   3,792       +546%
+```
+
+Disk usage is **29 % smaller** after compaction compared to `none`. All correctness checks pass on every mode.
+
 ## Best Practices
 
 ### Use Transactions for Bulk Operations

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepbase-sqlite",
-  "version": "3.4.12",
+  "version": "3.6.0",
   "description": "⚡ DeepBase SQLite - SQLite database driver",
   "type": "module",
   "main": "src/index.cjs",
@@ -17,7 +17,7 @@
     "better-sqlite3": "^11.8.1"
   },
   "peerDependencies": {
-    "deepbase": "^3.4.12"
+    "deepbase": "^3.6.0"
   },
   "scripts": {
     "test": "mocha test/test.js"

package/src/SqliteDriver.js

@@ -3,54 +3,135 @@ import Database from 'better-sqlite3';
 import fs from 'fs';
 import * as pathModule from 'path';
 
+const PRAGMA = {
+  none: null,
+  safe: {
+    journal_mode: 'WAL',
+    synchronous: 'FULL',
+    temp_store: 'MEMORY',
+    cache_size: -2000,
+    busy_timeout: 5000,
+    mmap_size: 0,
+  },
+  balanced: {
+    journal_mode: 'WAL',
+    synchronous: 'NORMAL',
+    temp_store: 'MEMORY',
+    cache_size: -8000,
+    busy_timeout: 5000,
+    mmap_size: 268435456,
+  },
+  fast: {
+    journal_mode: 'WAL',
+    synchronous: 'OFF',
+    temp_store: 'MEMORY',
+    cache_size: -16000,
+    busy_timeout: 5000,
+    mmap_size: 268435456,
+  },
+};
+
 export class SqliteDriver extends DeepBaseDriver {
   static _instances = {};
-  
-  constructor({name, path, ...opts} = {}) {
+
+  constructor({ name, path, pragma, ...opts } = {}) {
     super(opts);
-    
-    this.name = name || "default";
+
+    this.name = name || 'default';
     this.path = path || new URL('../../../db', import.meta.url).pathname;
-    
+    this.pragma = pragma || 'balanced';
+
     this.path = pathModule.resolve(this.path);
     this.fileName = pathModule.join(this.path, `${this.name}.db`);
-    
-    // Singleton pattern per file
+
     if (SqliteDriver._instances[this.fileName]) {
       return SqliteDriver._instances[this.fileName];
     }
-    
+
     this.db = null;
     SqliteDriver._instances[this.fileName] = this;
   }
-  
-  async connect() {
+
+  _connectSync() {
     if (this._connected) return;
-    
+
     if (!fs.existsSync(this.path)) {
       fs.mkdirSync(this.path, { recursive: true });
     }
-    
+
     this.db = new Database(this.fileName);
-    
-    // Create table if it doesn't exist
+
+    const cfg = PRAGMA[this.pragma];
+    if (cfg) {
+      this.db.pragma(`journal_mode = ${cfg.journal_mode}`);
+      this.db.pragma(`synchronous = ${cfg.synchronous}`);
+      this.db.pragma(`temp_store = ${cfg.temp_store}`);
+      this.db.pragma(`cache_size = ${cfg.cache_size}`);
+      this.db.pragma(`busy_timeout = ${cfg.busy_timeout}`);
+      this.db.pragma(`mmap_size = ${cfg.mmap_size}`);
+    }
+
+    const withoutRowid = cfg ? ' WITHOUT ROWID' : '';
     this.db.exec(`
       CREATE TABLE IF NOT EXISTS deepbase (
         key TEXT PRIMARY KEY,
-        value TEXT NOT NULL
-      )
+        value TEXT NOT NULL,
+        seq INTEGER NOT NULL DEFAULT 0
+      )${withoutRowid}
     `);
-    
-    // Prepare statements for better performance
+
+    const tableCols = this.db.prepare('PRAGMA table_info(deepbase)').all();
+    if (!tableCols.some((c) => c.name === 'seq')) {
+      this.db.exec('ALTER TABLE deepbase ADD COLUMN seq INTEGER NOT NULL DEFAULT 0');
+    }
+
     this.getStmt = this.db.prepare('SELECT value FROM deepbase WHERE key = ?');
-    this.setStmt = this.db.prepare('INSERT OR REPLACE INTO deepbase (key, value) VALUES (?, ?)');
+    this.setStmt = this.db.prepare(`
+      INSERT INTO deepbase (key, value, seq)
+      VALUES (?, ?, (SELECT IFNULL(MAX(seq), 0) + 1 FROM deepbase))
+      ON CONFLICT(key) DO UPDATE SET value = excluded.value
+    `);
     this.delStmt = this.db.prepare('DELETE FROM deepbase WHERE key = ?');
-    this.getAllStmt = this.db.prepare('SELECT key, value FROM deepbase');
-    this.getKeysLikeStmt = this.db.prepare('SELECT key, value FROM deepbase WHERE key LIKE ? ESCAPE \'!\'');
-    
+    this.getAllStmt = this.db.prepare('SELECT key, value FROM deepbase ORDER BY seq, key');
+    this.getKeysLikeStmt = this.db.prepare(
+      "SELECT key, value FROM deepbase WHERE key LIKE ? ESCAPE '!' ORDER BY seq, key",
+    );
+    this.delChildrenStmt = this.db.prepare("DELETE FROM deepbase WHERE key LIKE ? ESCAPE '!'");
+    this.hasChildrenStmt = this.db.prepare("SELECT 1 FROM deepbase WHERE key LIKE ? ESCAPE '!' LIMIT 1");
+
+    this._setTxn = this.db.transaction((key, jsonValue, keys) => {
+      this._expandParentObjects(keys);
+      this.setStmt.run(key, jsonValue);
+    });
+
+    this._delTxn = this.db.transaction((key, likePattern) => {
+      this.delStmt.run(key);
+      this.delChildrenStmt.run(likePattern);
+    });
+
+    this._updTxn = this.db.transaction((keys, func) => {
+      const currentValue = this._getSync(keys);
+      const newValue = func(currentValue);
+      const key = this._pathToKey(keys);
+      this._expandParentObjects(keys);
+      this.setStmt.run(key, JSON.stringify(newValue));
+      return keys;
+    });
+
+    this._setRootTxn = this.db.transaction((entries) => {
+      this.db.exec('DELETE FROM deepbase');
+      for (const [key, value] of entries) {
+        this.setStmt.run(key, JSON.stringify(value));
+      }
+    });
+
     this._connected = true;
   }
-  
+
+  async connect() {
+    this._connectSync();
+  }
+
   async disconnect() {
     if (this.db) {
       this.db.close();
@@ -58,178 +139,124 @@ export class SqliteDriver extends DeepBaseDriver {
     }
     this._connected = false;
   }
-  
+
   async get(...args) {
     return this._getSync(args);
   }
-  
+
+  getSync(...args) {
+    this._connectSync();
+    return this._getSync(args);
+  }
+
   _getSync(args) {
     if (args.length === 0) {
-      // Get root object
       return this._getRootObject();
     }
-    
+
     const key = this._pathToKey(args);
     const row = this.getStmt.get(key);
-    
-    // Check if there are child keys (nested properties)
-    const children = this.getKeysLikeStmt.all(this._likePrefix(key));
-    
-    // If there are children, build object from them
-    if (children.length > 0) {
-      return this._buildObjectFromChildren(key);
-    }
-    
-    // If direct key exists and no children, return it
+    const likePattern = this._likePrefix(key);
+
     if (row) {
+      if (this.hasChildrenStmt.get(likePattern)) {
+        return this._buildObjectFromChildren(key, likePattern);
+      }
       return JSON.parse(row.value);
     }
-    
-    // Check if we need to look into a parent object
-    // For example: if we're looking for 'users.abc.name' but only 'users.abc' exists as a JSON object
-    const parentPath = this._findParentWithValue(args);
-    if (parentPath) {
-      const parentKey = this._pathToKey(parentPath);
-      const parentRow = this.getStmt.get(parentKey);
-      if (parentRow) {
-        const parentValue = JSON.parse(parentRow.value);
-        const relativePath = args.slice(parentPath.length);
-        return this._getFromObject(parentValue, relativePath);
-      }
+
+    if (this.hasChildrenStmt.get(likePattern)) {
+      return this._buildObjectFromChildren(key, likePattern);
     }
-    
-    return null;
+
+    return this._getFromParent(args);
   }
-  
+
   async set(...args) {
     if (args.length === 0) {
       throw new Error('set() requires at least one argument');
     }
-    
+
     if (args.length === 1) {
-      // Setting root object
       await this._setRootObject(args[0]);
       return [];
     }
-    
+
     return this._setSync(args);
   }
-  
+
   _setSync(args) {
     const keys = args.slice(0, -1);
     const value = args[args.length - 1];
     const key = this._pathToKey(keys);
-    
-    // Use transaction to make expansion and set atomic
-    const transaction = this.db.transaction(() => {
-      // Check if any parent path exists as an object that needs to be expanded
-      this._expandParentObjects(keys);
-      
-      this.setStmt.run(key, JSON.stringify(value));
-    });
-    
-    transaction();
+    this._setTxn(key, JSON.stringify(value), keys);
     return keys;
   }
-  
+
   async del(...keys) {
     if (keys.length === 0) {
-      // Delete everything
       this.db.exec('DELETE FROM deepbase');
       return;
     }
-    
+
     const key = this._pathToKey(keys);
-    
-    // Use transaction to make deletion atomic
-    const transaction = this.db.transaction(() => {
-      // Delete the key itself
-      this.delStmt.run(key);
-      
-      // Delete all children
-      this.db.prepare('DELETE FROM deepbase WHERE key LIKE ? ESCAPE \'!\'').run(this._likePrefix(key));
-    });
-    
-    transaction();
+    this._delTxn(key, this._likePrefix(key));
   }
-  
+
   async inc(...args) {
     const i = args.pop();
     return this.upd(...args, n => n + i);
   }
-  
+
   async dec(...args) {
     const i = args.pop();
     return this.upd(...args, n => n - i);
   }
-  
+
   async add(...keys) {
     const value = keys.pop();
     const id = this.nanoid();
     await this.set(...[...keys, id], value);
     return [...keys, id];
   }
-  
+
   async upd(...args) {
     const func = args.pop();
     const keys = args;
-    
-    // Use transaction to make get+set atomic
-    const transaction = this.db.transaction(() => {
-      const currentValue = this._getSync(keys);
-      const newValue = func(currentValue);
-      this._setSync([...keys, newValue]);
-      return keys;
-    });
-    
-    return transaction();
+    return this._updTxn(keys, func);
   }
-  
+
   _getRootObject() {
     const rows = this.getAllStmt.all();
     const result = {};
-    
     for (const row of rows) {
       const path = this._keyToPath(row.key);
       const value = JSON.parse(row.value);
       this._setNestedValue(result, path, value);
     }
-    
     return result;
   }
-  
+
   async _setRootObject(obj) {
-    // Clear existing data
-    this.db.exec('DELETE FROM deepbase');
-    
-    // Flatten and insert
     const entries = this._flattenObject(obj);
-    const insertMany = this.db.transaction((entries) => {
-      for (const [key, value] of entries) {
-        this.setStmt.run(key, JSON.stringify(value));
-      }
-    });
-    
-    insertMany(entries);
+    this._setRootTxn(entries);
   }
-  
-  _buildObjectFromChildren(parentKey) {
-    const rows = this.getKeysLikeStmt.all(parentKey ? this._likePrefix(parentKey) : '%');
+
+  _buildObjectFromChildren(parentKey, likePattern) {
+    const rows = this.getKeysLikeStmt.all(likePattern || (parentKey ? this._likePrefix(parentKey) : '%'));
     const result = {};
-    
+    const parentPathLen = parentKey ? this._keyToPath(parentKey).length : 0;
+
     for (const row of rows) {
       const fullPath = this._keyToPath(row.key);
-      const relativePath = parentKey 
-        ? fullPath.slice(this._keyToPath(parentKey).length)
-        : fullPath;
-      
+      const relativePath = fullPath.slice(parentPathLen);
       const value = JSON.parse(row.value);
       this._setNestedValue(result, relativePath, value);
     }
-    
+
     return result;
   }
-  
+
   _escapeLikePattern(str) {
     return str.replace(/[!%_]/g, '!$&');
   }
@@ -240,85 +267,76 @@ export class SqliteDriver extends DeepBaseDriver {
 
   _setNestedValue(obj, path, value) {
     if (path.length === 0) return;
-    
+
     if (path.length === 1) {
       obj[path[0]] = value;
       return;
     }
-    
+
     const key = path[0];
-    if (!obj.hasOwnProperty(key) || typeof obj[key] !== "object") {
+    if (!obj.hasOwnProperty(key) || typeof obj[key] !== 'object') {
       obj[key] = {};
     }
-    
+
     this._setNestedValue(obj[key], path.slice(1), value);
   }
-  
+
   _flattenObject(obj, prefix = '') {
     const entries = [];
-    
+
     for (const [key, value] of Object.entries(obj)) {
       const escapedKey = this._escapeDots(String(key));
       const fullKey = prefix ? `${prefix}.${escapedKey}` : escapedKey;
-      
+
       if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
         entries.push(...this._flattenObject(value, fullKey));
       } else {
         entries.push([fullKey, value]);
       }
     }
-    
+
     return entries;
   }
-  
-  _findParentWithValue(path) {
-    // Try to find a parent path that has a stored value
-    // For example: if looking for ['users', 'abc', 'name']
-    // and 'users.abc' exists as a stored JSON object, return ['users', 'abc']
+
+  _getFromParent(path) {
     for (let i = path.length - 1; i > 0; i--) {
       const parentPath = path.slice(0, i);
       const parentKey = this._pathToKey(parentPath);
       const row = this.getStmt.get(parentKey);
       if (row) {
-        const value = JSON.parse(row.value);
-        // Only return if it's an object (not a primitive)
-        if (value !== null && typeof value === 'object') {
-          return parentPath;
+        const parentValue = JSON.parse(row.value);
+        if (parentValue !== null && typeof parentValue === 'object') {
+          return this._getFromObject(parentValue, path.slice(i));
         }
       }
     }
     return null;
   }
-  
+
   _getFromObject(obj, path) {
     if (path.length === 0) return obj;
     if (path.length === 1) {
       return obj === null || obj[path[0]] === undefined ? null : obj[path[0]];
     }
-    
+
     const key = path[0];
     if (!obj.hasOwnProperty(key)) return null;
-    
+
     return this._getFromObject(obj[key], path.slice(1));
   }
-  
+
   _expandParentObjects(path) {
-    // Check each parent level (not including the path itself) to see if it exists as an object that needs expanding
-    // For example, if path is ['config', 'theme'], check if 'config' exists as an object
     for (let i = 1; i < path.length; i++) {
       const parentPath = path.slice(0, i);
       const parentKey = this._pathToKey(parentPath);
       const parentRow = this.getStmt.get(parentKey);
-      
+
       if (parentRow) {
         const parentValue = JSON.parse(parentRow.value);
-        
-        // If it's an object (not array or primitive), expand it
+
         if (parentValue !== null && typeof parentValue === 'object' && !Array.isArray(parentValue)) {
-          // Delete the parent key
           this.delStmt.run(parentKey);
-          
-          // Insert all properties as individual keys
+
           const entries = this._flattenObject(parentValue, parentKey);
           for (const [key, value] of entries) {
             this.setStmt.run(key, JSON.stringify(value));
@@ -330,5 +348,3 @@ export class SqliteDriver extends DeepBaseDriver {
 }
 
 export default SqliteDriver;
-
-

package/src/index.d.ts

@@ -3,6 +3,7 @@ import { DeepBaseDriver, DeepBaseDriverOptions } from 'deepbase';
 export interface SqliteDriverOptions extends DeepBaseDriverOptions {
     name?: string;
     path?: string;
+    pragma?: 'none' | 'safe' | 'balanced' | 'fast';
 }
 
 export class SqliteDriver extends DeepBaseDriver {
@@ -11,6 +12,8 @@ export class SqliteDriver extends DeepBaseDriver {
     name: string;
     path: string;
     fileName: string;
+    pragma: string;
 }
 
+export { SqliteDriver as SqliteFastDriver };
 export default SqliteDriver;

package/src/index.js

@@ -1,4 +1,3 @@
 export { SqliteDriver } from './SqliteDriver.js';
+export { SqliteDriver as SqliteFastDriver } from './SqliteDriver.js';
 export { SqliteDriver as default } from './SqliteDriver.js';
-
-