resplite 1.4.2 → 1.4.4

package/README.md

@@ -517,16 +517,27 @@ redis-cli -p 6380 PING
 | `RESPLITE_DB` | `./data.db` | SQLite database file |
 | `RESPLITE_PRAGMA_TEMPLATE` | `default` | SQLite PRAGMA preset (see below) |
 
-### PRAGMA templates
+### PRAGMA (convention over configuration)
+
+A **template** is applied by default (`default`); you usually don't pass anything. Only pass **overrides** when you need to change specific pragmas.
 
 | Template | Description | Key settings |
-|---|---|---|
+|----------|-------------|--------------|
 | `default` | Balanced durability and speed (recommended) | WAL, synchronous=NORMAL, 20 MB cache |
 | `performance` | Maximum throughput, reduced crash safety | WAL, synchronous=OFF, 64 MB cache, 512 MB mmap, exclusive locking |
 | `safety` | Crash-safe writes at the cost of speed | WAL, synchronous=FULL, 20 MB cache |
 | `minimal` | Only WAL + foreign keys | WAL, foreign_keys=ON |
 | `none` | No pragmas applied, pure SQLite defaults | - |
 
+Override specific pragmas only when needed. Overrides are applied after the template. Example — 1 GB cache:
+
+```javascript
+const srv = await createRESPlite({
+  db: './data.db',
+  pragma: { cache_size: -1024 * 1024 },  // negative = KiB, so 1 GiB
+});
+```
+
 ## Benchmark (Redis vs RESPLite)
 
 A typical comparison is **Redis (for example, in Docker)** on one side and **RESPLite locally** on the other. In that setup, RESPLite often shows **better latency** because it avoids Docker networking and runs in the same process or host. The benchmark below uses RESPLite with the **default** PRAGMA template only.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "resplite",
-  "version": "1.4.2",
+  "version": "1.4.4",
   "description": "A RESP2 server with practical Redis compatibility, backed by SQLite",
   "type": "module",
   "main": "src/index.js",

package/src/embed.js

@@ -33,7 +33,8 @@ export { handleConnection, createEngine, openDb };
  * @param {string} [options.db=':memory:']        SQLite file path, or ':memory:' for in-memory.
  * @param {string} [options.host='127.0.0.1']     Host to listen on.
  * @param {number} [options.port=0]               Port to listen on (0 = OS-assigned).
- * @param {string} [options.pragmaTemplate='default'] PRAGMA preset (default|performance|safety|minimal|none).
+ * @param {string} [options.pragmaTemplate='default'] PRAGMA preset (default|performance|safety|minimal|none). Convention: this template is applied by default; no config needed.
+ * @param {Record<string, string|number>} [options.pragma] Override specific pragmas only when needed (e.g. { synchronous: 'FULL' }). Applied after the template.
  * @param {RESPliteHooks} [options.hooks]         Optional event hooks for observability (onUnknownCommand, onCommandError, onSocketError).
  * @param {boolean} [options.gracefulShutdown=true] If true, register SIGTERM/SIGINT to call close(). Set false if you handle shutdown yourself to avoid double handlers.
  * @returns {Promise<{ port: number, host: string, close: () => Promise<void> }>}
@@ -43,10 +44,11 @@ export async function createRESPlite({
   host = '127.0.0.1',
   port = 0,
   pragmaTemplate = 'default',
+  pragma,
   hooks = {},
   gracefulShutdown = true,
 } = {}) {
-  const db = openDb(dbPath, { pragmaTemplate });
+  const db = openDb(dbPath, { pragmaTemplate, pragma });
   const engine = createEngine({ db });
   const connections = new Set();
 

package/src/index.js

@@ -24,6 +24,7 @@ const DEFAULT_PORT = 6379;
  * @param {number} [options.port]
  * @param {string} [options.dbPath]
  * @param {string} [options.pragmaTemplate]
+ * @param {Record<string, string|number>} [options.pragma] Override specific pragmas when needed (e.g. { synchronous: 'FULL' }). Convention: template is applied by default.
  * @param {boolean} [options.gracefulShutdown=true] If true, register SIGTERM/SIGINT to close server and DB. Set false if you handle shutdown yourself.
  */
 export function startServer(options = {}) {
@@ -32,7 +33,7 @@ export function startServer(options = {}) {
   const pragmaTemplate = options.pragmaTemplate ?? process.env.RESPLITE_PRAGMA_TEMPLATE ?? 'default';
   const gracefulShutdown = options.gracefulShutdown !== false;
 
-  const db = openDb(dbPath, { pragmaTemplate });
+  const db = openDb(dbPath, { pragmaTemplate, pragma: options.pragma });
   const cache = createCache({ enabled: true });
   const engine = createEngine({ db, cache });
   const sweeper = createExpirationSweeper({

package/src/storage/sqlite/db.js

@@ -12,7 +12,7 @@ import { applyMigrationSchema } from './migration-schema.js';
 
 /**
  * @param {string} dbPath - Database file path (or ':memory:')
- * @param {object} [options] - Options: pragmaTemplate (default|performance|safety|minimal), plus any better-sqlite3 options
+ * @param {object} [options] - Options: pragmaTemplate (default|performance|safety|minimal), pragma (custom key-value overrides), plus any better-sqlite3 options
  * @returns {import('better-sqlite3').Database}
  */
 export function openDb(dbPath, options = {}) {
@@ -20,9 +20,9 @@ export function openDb(dbPath, options = {}) {
     const dir = path.dirname(dbPath);
     if (dir) fs.mkdirSync(dir, { recursive: true });
   }
-  const { pragmaTemplate = 'default', ...dbOptions } = options;
+  const { pragmaTemplate = 'default', pragma: customPragma, ...dbOptions } = options;
   const db = new Database(dbPath, dbOptions);
-  applyPragmas(db, pragmaTemplate);
+  applyPragmas(db, pragmaTemplate, customPragma);
   applySchema(db);
   applyMigrationSchema(db);
   return db;

package/src/storage/sqlite/pragmas.js

@@ -69,13 +69,29 @@ export function getPragmasForTemplate(name) {
 }
 
 /**
- * Apply pragmas from a named template to an open database.
+ * Apply custom pragma key-value object to an open database.
+ * @param {import('better-sqlite3').Database} db
+ * @param {Record<string, string|number>} obj - e.g. { journal_mode: 'WAL', cache_size: -64000 }
+ */
+function applyPragmaObject(db, obj) {
+  for (const [key, val] of Object.entries(obj)) {
+    if (val === undefined) continue;
+    db.exec(`PRAGMA ${key}=${val};`);
+  }
+}
+
+/**
+ * Apply pragmas from a named template and optional overrides to an open database.
  * @param {import('better-sqlite3').Database} db
  * @param {string} [templateName='default'] - One of: default, performance, safety, minimal, none
+ * @param {Record<string, string|number>} [customPragma] - Optional overrides, e.g. { synchronous: 'FULL', cache_size: -10000 }
  */
-export function applyPragmas(db, templateName = 'default') {
+export function applyPragmas(db, templateName = 'default', customPragma = undefined) {
   const pragmas = getPragmasForTemplate(templateName);
   for (const sql of pragmas) {
     db.exec(sql);
   }
+  if (customPragma && typeof customPragma === 'object' && Object.keys(customPragma).length > 0) {
+    applyPragmaObject(db, customPragma);
+  }
 }

package/test/integration/embed.test.js

@@ -89,6 +89,17 @@ describe('createRESPlite', () => {
     await srv.close();
   });
 
+  it('accepts pragma overrides (convention: template first, overrides only when needed)', async () => {
+    const srv = await createRESPlite({
+      pragma: { synchronous: 'FULL', cache_size: -10_000 },
+    });
+    const client = await redisClient(srv.port);
+    await client.set('k', 'v');
+    assert.equal(await client.get('k'), 'v');
+    await client.quit();
+    await srv.close();
+  });
+
   it('unsupported command still returns ERR command not supported yet to client', async () => {
     const srv = await createRESPlite();
     const client = await redisClient(srv.port);

package/test/unit/pragmas.test.js

@@ -72,4 +72,28 @@ describe('Pragma templates', () => {
       db.close();
     }
   });
+
+  it('openDb with pragma overrides applies them after the template', () => {
+    const path = tmpDbPath();
+    const db = openDb(path, { pragmaTemplate: 'default', pragma: { synchronous: 'FULL' } });
+    try {
+      const row = db.prepare('PRAGMA synchronous').get();
+      assert.equal(row.synchronous, 2); // FULL = 2
+    } finally {
+      db.close();
+    }
+  });
+
+  it('openDb with pragma cache_size override (e.g. 1 GiB)', () => {
+    const path = tmpDbPath();
+    const oneGibKib = 1024 * 1024;
+    const db = openDb(path, { pragmaTemplate: 'default', pragma: { cache_size: -oneGibKib } });
+    try {
+      const row = db.prepare('PRAGMA cache_size').get();
+      // SQLite returns cache size in KiB when it was set negative
+      assert.equal(Math.abs(row.cache_size), oneGibKib);
+    } finally {
+      db.close();
+    }
+  });
 });

package/docs/generated/migration-apply-dirty-concurrency-progress.md

@@ -1,7 +0,0 @@
----
-id: 90dhbsvf0f
-type: implementation
-title: Apply dirty migration concurrency and progress
-created: '2026-03-12 14:55:12'
----
-Improved src/migration/apply-dirty.js to support concurrent dirty-key apply via options.concurrency (chunked Promise.all worker model) while preserving max_rps throttling. Added richer onProgress payload fields: dirty_keys_processed, dirty_pending, dirty_keys_per_second, dirty_eta_seconds, and related counters. Exposed new options through createMigration().applyDirty: concurrency and progressIntervalMs. Updated README migration cutover snippet with high-throughput applyDirty example and progress logging. Added unit test test/unit/migration-apply-dirty.test.js validating concurrency and progress payload. Verified with node --test test/unit/migration-apply-dirty.test.js and npm run test:unit (all passing).

package/docs/generated/migration-bulk-concurrency.md

@@ -1,7 +0,0 @@
----
-id: tucj9i5nh5
-type: implementation
-title: Bulk migration concurrency added
-created: '2026-03-11 11:09:20'
----
-Added configurable concurrency to runBulkImport and createMigration.bulk with default 1. Implemented chunked parallel import with shared global max_rps limiter. Added unit tests proving default sequential behavior and concurrent behavior with cap.

package/docs/generated/migration-bulk-eta-onprogress.md

@@ -1,7 +0,0 @@
----
-id: 105jsp012x
-type: implementation
-title: Bulk onProgress ETA support
-created: '2026-03-11 11:10:48'
----
-Added ETA/progress metrics to bulk migration onProgress payload. New optional options: estimated_total_keys in runBulkImport, estimatedTotalKeys in createMigration/bulk(). onProgress payload now includes elapsed_seconds, keys_per_second, estimated_total_keys, remaining_keys_estimate, eta_seconds, progress_pct. README migration example updated to print ETA/rate. Added unit test validating ETA fields and final 100%/eta=0 behavior.