resplite 1.1.12 → 1.2.2

package/README.md

@@ -87,7 +87,7 @@ OK
 
 ### Standalone server script (fixed port)
 
-Run this as a persistent background process (`node server.js`). RESPLite will listen on port 6380 and stay up until the process is killed.
+Run this as a persistent background process (`node server.js`). RESPLite will listen on port 6380 and stay up until the process receives SIGINT (Ctrl+C) or SIGTERM; then it closes the server and exits cleanly. If you kill the process (e.g. SIGKILL or force quit), all client connections are closed as well — with the default configuration the server runs in the same process, so when the process exits the TCP server and its connections are torn down.
 
 ```javascript
 // server.js
@@ -95,6 +95,7 @@ import { createRESPlite } from 'resplite/embed';
 
 const srv = await createRESPlite({ port: 6380, db: './data.db' });
 console.log(`RESPLite listening on ${srv.host}:${srv.port}`);
+
 ```
 
 Then connect from any other script or process:
@@ -142,211 +143,40 @@ await client.quit();
 await srv.close();
 ```
 
-### Strings, TTL, and key operations
-
-```javascript
-// SET with expiration
-await client.set('session:abc', JSON.stringify({ user: 'alice' }));
-await client.expire('session:abc', 3600);      // expire in 1 hour
-console.log(await client.ttl('session:abc'));  // → 3600 (approx)
-
-// Atomic counters
-await client.set('visits', '0');
-await client.incr('visits');
-await client.incrBy('visits', 10);
-console.log(await client.get('visits'));       // → "11"
-
-// Multi-key operations
-await client.mSet(['k1', 'v1', 'k2', 'v2']);
-const values = await client.mGet(['k1', 'k2', 'missing']);
-console.log(values);  // → ["v1", "v2", null]
+### Observability (event hooks)
 
-// Key existence and deletion
-console.log(await client.exists('k1'));        // → 1
-await client.del('k1');
-console.log(await client.exists('k1'));        // → 0
-```
-
-### Hashes
+When embedding RESPLite you can pass optional hooks to log unknown commands, command errors, or socket errors (e.g. for `warn`/`error` in your logger). The client still receives the same RESP responses; hooks are for observability only.
 
 ```javascript
-await client.hSet('user:1', { name: 'Martin', age: '42', city: 'BCN' });
-
-console.log(await client.hGet('user:1', 'name'));     // → "Martin"
-
-const user = await client.hGetAll('user:1');
-console.log(user);  // → { name: "Martin", age: "42", city: "BCN" }
-
-await client.hIncrBy('user:1', 'age', 1);
-console.log(await client.hGet('user:1', 'age'));      // → "43"
-
-console.log(await client.hExists('user:1', 'email')); // → false
-```
-
-### Sets
-
-```javascript
-await client.sAdd('tags', ['node', 'sqlite', 'redis']);
-console.log(await client.sMembers('tags'));           // → ["node", "sqlite", "redis"]
-console.log(await client.sIsMember('tags', 'node'));  // → true
-console.log(await client.sCard('tags'));              // → 3
-
-await client.sRem('tags', 'redis');
-console.log(await client.sCard('tags'));              // → 2
-```
-
-### Lists
-
-```javascript
-await client.lPush('queue', ['c', 'b', 'a']);      // push left: a, b, c
-await client.rPush('queue', ['d', 'e']);           // push right: d, e
-
-console.log(await client.lLen('queue'));           // → 5
-console.log(await client.lRange('queue', 0, -1));  // → ["a", "b", "c", "d", "e"]
-console.log(await client.lIndex('queue', 0));      // → "a"
-
-console.log(await client.lPop('queue'));           // → "a"
-console.log(await client.rPop('queue'));           // → "e"
-```
-
-### Blocking list commands (BLPOP / BRPOP)
-
-`BLPOP` and `BRPOP` block until an element is available or a timeout (seconds) is reached. Use them for simple queues or coordination between producers and consumers.
-
-```javascript
-// Consumer: block up to 10 seconds for an element from "tasks" or "fallback"
-const result = await client.blPop(['tasks', 'fallback'], 10);
-// result is { key: 'tasks', element: 'item1' } or null on timeout
-
-// Producer (e.g. another client or process)
-await client.rPush('tasks', 'item1');
-```
-
-- **Timeout**: `0` = block indefinitely; `> 0` = block up to that many seconds.
-- **Return**: `{ key, element }` on success, or `null` on timeout.
-- **Multi-key**: Keys are checked in order; the first key that has an element wins. One push wakes at most one blocked client (FIFO per key).
-
-### Sorted sets
-
-```javascript
-await client.zAdd('leaderboard', [
-  { score: 100, value: 'alice' },
-  { score: 250, value: 'bob' },
-  { score: 175, value: 'carol' },
-]);
-
-console.log(await client.zCard('leaderboard'));                // → 3
-console.log(await client.zScore('leaderboard', 'bob'));        // → 250
-console.log(await client.zRange('leaderboard', 0, -1));        // → ["alice", "carol", "bob"]
-console.log(await client.zRangeByScore('leaderboard', 100, 200)); // → ["alice", "carol"]
-```
-
-### Full-text search (RediSearch-like)
-
-```javascript
-// Create an index
-await client.sendCommand(['FT.CREATE', 'articles', 'SCHEMA', 'payload', 'TEXT']);
-
-// Add documents
-await client.sendCommand([
-  'FT.ADD', 'articles', 'doc:1', '1', 'REPLACE', 'FIELDS',
-  'payload', 'Introduction to SQLite full-text search'
-]);
-await client.sendCommand([
-  'FT.ADD', 'articles', 'doc:2', '1', 'REPLACE', 'FIELDS',
-  'payload', 'Building a Redis-compatible server in Node.js'
-]);
-
-// Search
-const results = await client.sendCommand([
-  'FT.SEARCH', 'articles', 'SQLite', 'NOCONTENT', 'LIMIT', '0', '10'
-]);
-console.log(results);  // → [1, "doc:1"]  (count + matching doc IDs)
-
-// Autocomplete suggestions
-await client.sendCommand(['FT.SUGADD', 'articles', 'sqlite full-text', '10']);
-await client.sendCommand(['FT.SUGADD', 'articles', 'sqlite indexing', '5']);
-const suggestions = await client.sendCommand(['FT.SUGGET', 'articles', 'sqlite']);
-console.log(suggestions);  // → ["sqlite full-text", "sqlite indexing"]
-```
-
-### Introspection and admin
-
-```javascript
-// Scan keys (cursor-based)
-const scanResult = await client.scan(0);
-console.log(scanResult);  // → { cursor: 0, keys: [...] }
-
-// Key type
-console.log(await client.type('user:1'));  // → "hash"
-
-// Admin commands (via sendCommand)
-const sqliteInfo = await client.sendCommand(['SQLITE.INFO']);
-const cacheInfo  = await client.sendCommand(['CACHE.INFO']);
-const memInfo    = await client.sendCommand(['MEMORY.INFO']);
-```
-
-### Data persists across restarts
-
-```javascript
-import { createClient } from 'redis';
-import { createRESPlite } from 'resplite/embed';
-
-const DB_PATH = './persistent.db';
-
-// --- First session: write data ---
-const srv1 = await createRESPlite({ db: DB_PATH });
-const c1 = createClient({ socket: { port: srv1.port, host: '127.0.0.1' } });
-await c1.connect();
-await c1.set('persistent_key', 'survives restart');
-await c1.hSet('user:1', { name: 'Alice' });
-await c1.quit();
-await srv1.close();
-
-// --- Second session: data is still there ---
-const srv2 = await createRESPlite({ db: DB_PATH });
-const c2 = createClient({ socket: { port: srv2.port, host: '127.0.0.1' } });
-await c2.connect();
-console.log(await c2.get('persistent_key'));     // → "survives restart"
-console.log(await c2.hGet('user:1', 'name'));    // → "Alice"
-await c2.quit();
-await srv2.close();
+import pino from 'pino';
+const log = pino(); // or your logger
+
+const srv = await createRESPlite({
+  port: 6380,
+  db: './data.db',
+  hooks: {
+    onUnknownCommand({ command, argsCount, clientAddress }) {
+      log.warn({ command, argsCount, clientAddress }, 'RESPLite: unsupported command');
+    },
+    onCommandError({ command, error, clientAddress }) {
+      log.warn({ command, error, clientAddress }, 'RESPLite: command error');
+    },
+    onSocketError({ error, clientAddress }) {
+      log.error({ err: error, clientAddress }, 'RESPLite: connection error');
+    },
+  },
+});
 ```
 
-## Compatibility matrix
-
-RESPLite implements **47 core Redis commands** (~19% of the ~246 commands in Redis 7). The uncovered 81% is mostly entire subsystems that are out of scope by design: pub/sub (~10 commands), Streams (~20), cluster/replication (~30), Lua scripting (~5), server admin (~40), and extended variants of data-structure commands. For typical single-node application workloads — strings, hashes, sets, lists, sorted sets, key TTLs — coverage is close to the commands developers reach for daily.
-
-### Supported (v1)
-
-| Category | Commands |
-|---|---|
-| **Connection** | PING, ECHO, QUIT |
-| **Strings** | GET, SET, MGET, MSET, DEL, EXISTS, INCR, DECR, INCRBY, DECRBY |
-| **TTL** | EXPIRE, PEXPIRE, TTL, PTTL, PERSIST |
-| **Hashes** | HSET, HGET, HMGET, HGETALL, HDEL, HEXISTS, HINCRBY |
-| **Sets** | SADD, SREM, SMEMBERS, SISMEMBER, SCARD |
-| **Lists** | LPUSH, RPUSH, LLEN, LRANGE, LINDEX, LPOP, RPOP, BLPOP, BRPOP |
-| **Sorted sets** | ZADD, ZREM, ZCARD, ZSCORE, ZRANGE, ZRANGEBYSCORE |
-| **Search (FT.\*)** | FT.CREATE, FT.INFO, FT.ADD, FT.DEL, FT.SEARCH, FT.SUGADD, FT.SUGGET, FT.SUGDEL |
-| **Introspection** | TYPE, SCAN, KEYS, MONITOR |
-| **Admin** | SQLITE.INFO, CACHE.INFO, MEMORY.INFO |
-| **Tooling** | Redis import CLI (see Migration from Redis) |
-
-### Not supported (v1)
-
-- Pub/Sub (SUBSCRIBE, PUBLISH, etc.)
-- Streams (XADD, XRANGE, etc.)
-- Lua (EVAL, EVALSHA)
-- Transactions (MULTI, EXEC, WATCH)
-- BRPOPLPUSH, BLMOVE (blocking list moves)
-- SELECT (multiple logical DBs)
-
-Unsupported commands return: `ERR command not supported yet`.
+| Hook | When it is called |
+|------|--------------------|
+| `onUnknownCommand` | Client sent a command not implemented by RESPLite (e.g. `SUBSCRIBE`, `PUBLISH`). |
+| `onCommandError` | A command failed (wrong type, invalid args, or handler threw). |
+| `onSocketError` | The connection socket emitted an error (e.g. `ECONNRESET`). |
 
 ## Migration from Redis
 
-RESPLite is a good fit for migrating **non-replicated Redis** instances that have **grown large** (e.g. tens of GB) and where RESPLite’s latency is acceptable. The SPEC_F flow (dirty-key tracker, bulk import, cutover) is designed for that scenario with minimal downtime.
+RESPLite is a good fit for migrating **non-replicated Redis** instances that have **grown large** (e.g. tens of GB) and where RESPLite's latency is acceptable. The SPEC_F flow (dirty-key tracker, bulk import, cutover) is designed for that scenario with minimal downtime.
 
 Migration supports two modes:
 
@@ -420,10 +250,10 @@ notify-keyspace-events KEA
    npx resplite-dirty-tracker start --run-id run_001 --from redis://10.0.0.10:6379 --to ./resplite.db --config-command MYCONFIG
    ```
 
-3. **Bulk import** – SCAN and copy all keys; progress is checkpointed and resumable:
+3. **Bulk import** – SCAN and copy all keys; progress is checkpointed and resumable (resume is default; re-run the same command to continue after a stop):
    ```bash
    npx resplite-import bulk --run-id run_001 --from redis://10.0.0.10:6379 --to ./resplite.db \
-     --scan-count 1000 --max-rps 2000 --batch-keys 200 --batch-bytes 64MB --resume
+     --scan-count 1000 --max-rps 2000 --batch-keys 200 --batch-bytes 64MB
    ```
 
 4. **Monitor** – Check run and dirty-key counts:
@@ -448,7 +278,7 @@ notify-keyspace-events KEA
 
 Then start RespLite with the migrated DB: `RESPLITE_DB=./resplite.db npm start`.
 
-### Programmatic migration API
+### Programmatic migration API (JavaScript)
 
 As an alternative to the CLI, the full migration flow is available as a JavaScript API via `resplite/migration`. Useful for embedding the migration inside your own scripts or automation pipelines.
 
@@ -485,9 +315,8 @@ const ks = await m.enableKeyspaceNotifications();
 // → { ok: true, previous: '', applied: 'KEA' }
 // If CONFIG is renamed and configCommand was not set, ok=false and error explains how to fix it.
 
-// Step 1 — Bulk import (checkpointed, resumable)
+// Step 1 — Bulk import (checkpointed, resumable). Same script to start or continue.
 await m.bulk({
-  resume: false,                            // true to resume a previous run
   onProgress: (r) => console.log(
     `scanned=${r.scanned_keys} migrated=${r.migrated_keys} errors=${r.error_keys}`
   ),
@@ -508,6 +337,9 @@ console.log(`verified ${result.sampled} keys — mismatches: ${result.mismatches
 await m.close();
 ```
 
+**Resume automático (por defecto)**  
+`resume` viene en `true` por defecto. Da igual si es la primera vez o una reanudación: el mismo script sirve para empezar y para continuar. La primera ejecución arranca desde cursor 0; si el proceso se corta (Ctrl+C, crash, etc.), al volver a ejecutar el script continúa desde el último checkpoint. No hace falta pasar `resume: false` la primera vez ni cambiar nada para reanudar.
+
 The dirty-key tracker (to capture writes during bulk) still runs as a separate process via `npx resplite-dirty-tracker`. The API above handles everything else in a single script.
 
 #### Renamed CONFIG command
@@ -548,6 +380,208 @@ import {
 } from 'resplite/migration';
 ```
 
+### Strings, TTL, and key operations
+
+```javascript
+// SET with expiration
+await client.set('session:abc', JSON.stringify({ user: 'alice' }));
+await client.expire('session:abc', 3600);      // expire in 1 hour
+console.log(await client.ttl('session:abc'));  // → 3600 (approx)
+
+// Atomic counters
+await client.set('visits', '0');
+await client.incr('visits');
+await client.incrBy('visits', 10);
+console.log(await client.get('visits'));       // → "11"
+
+// Multi-key operations
+await client.mSet(['k1', 'v1', 'k2', 'v2']);
+const values = await client.mGet(['k1', 'k2', 'missing']);
+console.log(values);  // → ["v1", "v2", null]
+
+// Key existence and deletion
+console.log(await client.exists('k1'));        // → 1
+await client.del('k1');
+console.log(await client.exists('k1'));        // → 0
+```
+
+### Hashes
+
+```javascript
+await client.hSet('user:1', { name: 'Martin', age: '42', city: 'BCN' });
+
+console.log(await client.hGet('user:1', 'name'));     // → "Martin"
+
+const user = await client.hGetAll('user:1');
+console.log(user);  // → { name: "Martin", age: "42", city: "BCN" }
+
+await client.hIncrBy('user:1', 'age', 1);
+console.log(await client.hGet('user:1', 'age'));      // → "43"
+
+console.log(await client.hExists('user:1', 'email')); // → false
+```
+
+### Sets
+
+```javascript
+await client.sAdd('tags', ['node', 'sqlite', 'redis']);
+console.log(await client.sMembers('tags'));           // → ["node", "sqlite", "redis"]
+console.log(await client.sIsMember('tags', 'node'));  // → true
+console.log(await client.sCard('tags'));              // → 3
+
+await client.sRem('tags', 'redis');
+console.log(await client.sCard('tags'));              // → 2
+```
+
+### Lists
+
+```javascript
+await client.lPush('queue', ['c', 'b', 'a']);      // push left: a, b, c
+await client.rPush('queue', ['d', 'e']);           // push right: d, e
+
+console.log(await client.lLen('queue'));           // → 5
+console.log(await client.lRange('queue', 0, -1));  // → ["a", "b", "c", "d", "e"]
+console.log(await client.lIndex('queue', 0));      // → "a"
+
+console.log(await client.lPop('queue'));           // → "a"
+console.log(await client.rPop('queue'));           // → "e"
+```
+
+### Blocking list commands (BLPOP / BRPOP)
+
+`BLPOP` and `BRPOP` block until an element is available or a timeout (seconds) is reached. Use them for simple queues or coordination between producers and consumers.
+
+```javascript
+// Consumer: block up to 10 seconds for an element from "tasks" or "fallback"
+const result = await client.blPop(['tasks', 'fallback'], 10);
+// result is { key: 'tasks', element: 'item1' } or null on timeout
+
+// Producer (e.g. another client or process)
+await client.rPush('tasks', 'item1');
+```
+
+- **Timeout**: `0` = block indefinitely; `> 0` = block up to that many seconds.
+- **Return**: `{ key, element }` on success, or `null` on timeout.
+- **Multi-key**: Keys are checked in order; the first key that has an element wins. One push wakes at most one blocked client (FIFO per key).
+
+### Sorted sets
+
+```javascript
+await client.zAdd('leaderboard', [
+  { score: 100, value: 'alice' },
+  { score: 250, value: 'bob' },
+  { score: 175, value: 'carol' },
+]);
+
+console.log(await client.zCard('leaderboard'));                // → 3
+console.log(await client.zScore('leaderboard', 'bob'));        // → 250
+console.log(await client.zRange('leaderboard', 0, -1));        // → ["alice", "carol", "bob"]
+console.log(await client.zRangeByScore('leaderboard', 100, 200)); // → ["alice", "carol"]
+```
+
+### Full-text search (RediSearch-like)
+
+```javascript
+// Create an index
+await client.sendCommand(['FT.CREATE', 'articles', 'SCHEMA', 'payload', 'TEXT']);
+
+// Add documents
+await client.sendCommand([
+  'FT.ADD', 'articles', 'doc:1', '1', 'REPLACE', 'FIELDS',
+  'payload', 'Introduction to SQLite full-text search'
+]);
+await client.sendCommand([
+  'FT.ADD', 'articles', 'doc:2', '1', 'REPLACE', 'FIELDS',
+  'payload', 'Building a Redis-compatible server in Node.js'
+]);
+
+// Search
+const results = await client.sendCommand([
+  'FT.SEARCH', 'articles', 'SQLite', 'NOCONTENT', 'LIMIT', '0', '10'
+]);
+console.log(results);  // → [1, "doc:1"]  (count + matching doc IDs)
+
+// Autocomplete suggestions
+await client.sendCommand(['FT.SUGADD', 'articles', 'sqlite full-text', '10']);
+await client.sendCommand(['FT.SUGADD', 'articles', 'sqlite indexing', '5']);
+const suggestions = await client.sendCommand(['FT.SUGGET', 'articles', 'sqlite']);
+console.log(suggestions);  // → ["sqlite full-text", "sqlite indexing"]
+```
+
+### Introspection and admin
+
+```javascript
+// Scan keys (cursor-based)
+const scanResult = await client.scan(0);
+console.log(scanResult);  // → { cursor: 0, keys: [...] }
+
+// Key type
+console.log(await client.type('user:1'));  // → "hash"
+
+// Admin commands (via sendCommand)
+const sqliteInfo = await client.sendCommand(['SQLITE.INFO']);
+const cacheInfo  = await client.sendCommand(['CACHE.INFO']);
+const memInfo    = await client.sendCommand(['MEMORY.INFO']);
+```
+
+### Data persists across restarts
+
+```javascript
+import { createClient } from 'redis';
+import { createRESPlite } from 'resplite/embed';
+
+const DB_PATH = './persistent.db';
+
+// --- First session: write data ---
+const srv1 = await createRESPlite({ db: DB_PATH });
+const c1 = createClient({ socket: { port: srv1.port, host: '127.0.0.1' } });
+await c1.connect();
+await c1.set('persistent_key', 'survives restart');
+await c1.hSet('user:1', { name: 'Alice' });
+await c1.quit();
+await srv1.close();
+
+// --- Second session: data is still there ---
+const srv2 = await createRESPlite({ db: DB_PATH });
+const c2 = createClient({ socket: { port: srv2.port, host: '127.0.0.1' } });
+await c2.connect();
+console.log(await c2.get('persistent_key'));     // → "survives restart"
+console.log(await c2.hGet('user:1', 'name'));    // → "Alice"
+await c2.quit();
+await srv2.close();
+```
+
+## Compatibility matrix
+
+RESPLite implements **47 core Redis commands** (~19% of the ~246 commands in Redis 7). The uncovered 81% is mostly entire subsystems that are out of scope by design: pub/sub (~10 commands), Streams (~20), cluster/replication (~30), Lua scripting (~5), server admin (~40), and extended variants of data-structure commands. For typical single-node application workloads — strings, hashes, sets, lists, sorted sets, key TTLs — coverage is close to the commands developers reach for daily.
+
+### Supported (v1)
+
+| Category | Commands |
+|---|---|
+| **Connection** | PING, ECHO, QUIT |
+| **Strings** | GET, SET, MGET, MSET, DEL, EXISTS, INCR, DECR, INCRBY, DECRBY |
+| **TTL** | EXPIRE, PEXPIRE, TTL, PTTL, PERSIST |
+| **Hashes** | HSET, HGET, HMGET, HGETALL, HDEL, HEXISTS, HINCRBY |
+| **Sets** | SADD, SREM, SMEMBERS, SISMEMBER, SCARD |
+| **Lists** | LPUSH, RPUSH, LLEN, LRANGE, LINDEX, LPOP, RPOP, BLPOP, BRPOP |
+| **Sorted sets** | ZADD, ZREM, ZCARD, ZSCORE, ZRANGE, ZRANGEBYSCORE |
+| **Search (FT.\*)** | FT.CREATE, FT.INFO, FT.ADD, FT.DEL, FT.SEARCH, FT.SUGADD, FT.SUGGET, FT.SUGDEL |
+| **Introspection** | TYPE, SCAN, KEYS, MONITOR |
+| **Admin** | SQLITE.INFO, CACHE.INFO, MEMORY.INFO |
+| **Tooling** | Redis import CLI (see Migration from Redis) |
+
+### Not supported (v1)
+
+- Pub/Sub (SUBSCRIBE, PUBLISH, etc.)
+- Streams (XADD, XRANGE, etc.)
+- Lua (EVAL, EVALSHA)
+- Transactions (MULTI, EXEC, WATCH)
+- BRPOPLPUSH, BLMOVE (blocking list moves)
+- SELECT (multiple logical DBs)
+
+Unsupported commands return: `ERR command not supported yet`.
+
 ## Scripts
 
 | Script | Description |

package/package.json

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

package/src/cli/resplite-import.js

@@ -47,6 +47,8 @@ function parseArgs(argv = process.argv.slice(2)) {
       }
     } else if (arg === '--resume') {
       args.resume = true;
+    } else if (arg === '--no-resume') {
+      args.resume = false;
     } else if (arg === '--pragma-template' && argv[i + 1]) {
       args.pragmaTemplate = argv[++i];
     } else if (arg === '--sample' && argv[i + 1]) {
@@ -120,7 +122,7 @@ async function cmdBulk(args) {
       max_rps: args.maxRps || 0,
       batch_keys: args.batchKeys || 200,
       batch_bytes: args.batchBytes || 64 * 1024 * 1024,
-      resume: !!args.resume,
+      resume: args.resume !== false, // default true: start from 0 or continue from checkpoint
       onProgress: (r) => {
         console.log(`  scanned=${r.scanned_keys} migrated=${r.migrated_keys} skipped=${r.skipped_keys} errors=${r.error_keys} cursor=${r.scan_cursor}`);
       },
@@ -210,7 +212,7 @@ async function main() {
     console.error('  --max-rps N          (bulk, apply-dirty)');
     console.error('  --batch-keys N       (default 200)');
     console.error('  --batch-bytes N[MB|KB|GB] (default 64MB)');
-    console.error('  --resume             (bulk: resume from checkpoint)');
+    console.error('  --resume / --no-resume  (bulk: default resume=on; use --no-resume to always start from 0)');
     console.error('  --sample 0.5%        (verify, default 0.5%)');
     process.exit(1);
   }

package/src/commands/registry.js

@@ -135,7 +135,7 @@ const HANDLERS = new Map([
  * Dispatch command. Full argv: [commandNameBuf, ...argBuffers].
  * @param {object} engine
  * @param {Buffer[]} argv - first element is command name, rest are arguments
- * @param {object} [context] - optional connection context (connectionId, writeResponse) for blocking commands
+ * @param {object} [context] - optional connection context (connectionId, clientAddress, writeResponse, onUnknownCommand, onCommandError)
  * @returns {{ result: unknown } | { error: string } | { quit: true } | { block: object }}
  */
 export function dispatch(engine, argv, context) {
@@ -146,17 +146,38 @@ export function dispatch(engine, argv, context) {
   const args = argv.slice(1);
   const handler = HANDLERS.get(cmd);
   if (!handler) {
+    context?.onUnknownCommand?.({
+      command: cmd,
+      argsCount: args.length,
+      clientAddress: context.clientAddress ?? '',
+      connectionId: context.connectionId ?? 0,
+    });
     return { error: unsupported() };
   }
   try {
     const result = handler(engine, args, context);
     if (result && result.quit) return result;
-    if (result && result.error) return result;
+    if (result && result.error) {
+      context?.onCommandError?.({
+        command: cmd,
+        error: result.error,
+        clientAddress: context.clientAddress ?? '',
+        connectionId: context.connectionId ?? 0,
+      });
+      return result;
+    }
     if (result && result.block) return result;
     return { result };
   } catch (err) {
     const msg = err && err.message ? err.message : String(err);
-    return { error: msg.startsWith('ERR ') ? msg : 'ERR ' + msg };
+    const errorMsg = msg.startsWith('ERR ') ? msg : 'ERR ' + msg;
+    context?.onCommandError?.({
+      command: cmd,
+      error: errorMsg,
+      clientAddress: context.clientAddress ?? '',
+      connectionId: context.connectionId ?? 0,
+    });
+    return { error: errorMsg };
   }
 }
 

package/src/embed.js

@@ -16,6 +16,16 @@ import { openDb } from './storage/sqlite/db.js';
 
 export { handleConnection, createEngine, openDb };
 
+/**
+ * Optional event hooks for observability (e.g. logging unknown commands or errors).
+ * All hooks are optional. Called with plain objects; do not mutate.
+ *
+ * @typedef {object} RESPliteHooks
+ * @property {(payload: { command: string, argsCount: number, clientAddress: string, connectionId: number }) => void} [onUnknownCommand] Invoked when the client sends a command not implemented by RESPLite.
+ * @property {(payload: { command: string, error: string, clientAddress: string, connectionId: number }) => void} [onCommandError] Invoked when a command handler throws or returns an error (e.g. WRONGTYPE, invalid args).
+ * @property {(payload: { error: Error, clientAddress: string, connectionId: number }) => void} [onSocketError] Invoked when a connection socket emits an error (e.g. ECONNRESET).
+ */
+
 /**
  * Start an embedded RESPLite server.
  *
@@ -24,6 +34,8 @@ export { handleConnection, createEngine, openDb };
  * @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 {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> }>}
  */
 export async function createRESPlite({
@@ -31,6 +43,8 @@ export async function createRESPlite({
   host = '127.0.0.1',
   port = 0,
   pragmaTemplate = 'default',
+  hooks = {},
+  gracefulShutdown = true,
 } = {}) {
   const db = openDb(dbPath, { pragmaTemplate });
   const engine = createEngine({ db });
@@ -39,7 +53,7 @@ export async function createRESPlite({
   const server = net.createServer((socket) => {
     connections.add(socket);
     socket.once('close', () => connections.delete(socket));
-    handleConnection(socket, engine);
+    handleConnection(socket, engine, hooks);
   });
   await new Promise((resolve) => server.listen(port, host, resolve));
 
@@ -59,6 +73,14 @@ export async function createRESPlite({
     return closePromise;
   };
 
+  if (gracefulShutdown) {
+    const onSignal = () => {
+      close().then(() => process.exit(0));
+    };
+    process.on('SIGTERM', onSignal);
+    process.on('SIGINT', onSignal);
+  }
+
   return {
     port: server.address().port,
     host,

package/src/index.js

@@ -1,5 +1,9 @@
 /**
  * RESPLite entry point. Start TCP server with SQLite backend.
+ *
+ * Can be run as CLI (node src/index.js) or used programmatically:
+ *   import { startServer } from './src/index.js';
+ *   startServer({ port: 6380, gracefulShutdown: false });
  */
 
 import { createServer } from './server/tcp-server.js';
@@ -15,23 +19,57 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const DEFAULT_DB_PATH = path.join(process.cwd(), 'data.db');
 const DEFAULT_PORT = 6379;
 
-const dbPath = process.env.RESPLITE_DB || DEFAULT_DB_PATH;
-const port = parseInt(process.env.RESPLITE_PORT || String(DEFAULT_PORT), 10);
-const pragmaTemplate = process.env.RESPLITE_PRAGMA_TEMPLATE || 'default';
-
-const db = openDb(dbPath, { pragmaTemplate });
-const cache = createCache({ enabled: true });
-const engine = createEngine({ db, cache });
-const sweeper = createExpirationSweeper({
-  db,
-  clock: () => Date.now(),
-  sweepIntervalMs: 1000,
-  maxKeysPerSweep: 500,
-});
-sweeper.start();
-
-const server = createServer({ engine, port });
-
-server.listen(port, () => {
-  console.log(`RESPLite listening on port ${port}, db: ${dbPath}`);
-});
+/**
+ * @param {object} [options]
+ * @param {number} [options.port]
+ * @param {string} [options.dbPath]
+ * @param {string} [options.pragmaTemplate]
+ * @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 = {}) {
+  const dbPath = options.dbPath ?? process.env.RESPLITE_DB ?? DEFAULT_DB_PATH;
+  const port = options.port ?? parseInt(process.env.RESPLITE_PORT || String(DEFAULT_PORT), 10);
+  const pragmaTemplate = options.pragmaTemplate ?? process.env.RESPLITE_PRAGMA_TEMPLATE ?? 'default';
+  const gracefulShutdown = options.gracefulShutdown !== false;
+
+  const db = openDb(dbPath, { pragmaTemplate });
+  const cache = createCache({ enabled: true });
+  const engine = createEngine({ db, cache });
+  const sweeper = createExpirationSweeper({
+    db,
+    clock: () => Date.now(),
+    sweepIntervalMs: 1000,
+    maxKeysPerSweep: 500,
+  });
+  sweeper.start();
+
+  const connections = new Set();
+  const server = createServer({ engine, port, connections });
+
+  if (gracefulShutdown) {
+    let shuttingDown = false;
+    function shutdown() {
+      if (shuttingDown) return;
+      shuttingDown = true;
+      sweeper.stop();
+      for (const socket of connections) socket.destroy();
+      connections.clear();
+      server.close(() => {
+        db.close();
+        process.exit(0);
+      });
+    }
+    process.on('SIGTERM', shutdown);
+    process.on('SIGINT', shutdown);
+  }
+
+  server.listen(port, () => {
+    console.log(`RESPLite listening on port ${port}, db: ${dbPath}`);
+  });
+}
+
+const isCli = process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url));
+if (isCli) {
+  const noGraceful = process.argv.includes('--no-graceful-shutdown');
+  startServer({ gracefulShutdown: !noGraceful });
+}

package/src/migration/bulk.js

@@ -48,7 +48,7 @@ function sleep(ms) {
  * @param {number} [options.batch_keys=200]
  * @param {number} [options.batch_bytes=64*1024*1024] - 64MB
  * @param {number} [options.checkpoint_interval_sec=30]
- * @param {boolean} [options.resume=false]
+ * @param {boolean} [options.resume=true] - true: start from 0 or continue from checkpoint; false: always start from 0
  * @param {function(run): void} [options.onProgress] - called after checkpoint with run row
  */
 export async function runBulkImport(redisClient, dbPath, runId, options = {}) {
@@ -60,7 +60,7 @@ export async function runBulkImport(redisClient, dbPath, runId, options = {}) {
     batch_keys = 200,
     batch_bytes = 64 * 1024 * 1024,
     checkpoint_interval_sec = 30,
-    resume = false,
+    resume = true,
     onProgress,
   } = options;
 

package/src/migration/index.js

@@ -113,11 +113,11 @@ export function createMigration({
 
     /**
      * Step 1 — Bulk import: SCAN all keys from Redis into the destination DB.
-     * Supports resume (checkpoint-based) and optional progress callback.
+     * Resume is on by default: first run starts from 0, later runs continue from checkpoint.
      *
-     * @param {{ resume?: boolean, onProgress?: (run: object) => void }} [opts]
+     * @param {{ resume?: boolean, onProgress?: (run: object) => void }} [opts] - resume (default true): start or continue automatically
      */
-    async bulk({ resume = false, onProgress } = {}) {
+    async bulk({ resume = true, onProgress } = {}) {
       const id = requireRunId();
       const client = await getClient();
       return runBulkImport(client, to, id, {

package/src/server/connection.js

@@ -12,17 +12,22 @@ let nextConnectionId = 0;
 /**
  * @param {import('net').Socket} socket
  * @param {object} engine
+ * @param {object} [hooks] Optional: onUnknownCommand, onCommandError, onSocketError
  */
-export function handleConnection(socket, engine) {
+export function handleConnection(socket, engine, hooks = {}) {
   const reader = new RESPReader();
   const connectionId = ++nextConnectionId;
+  const clientAddress = `${socket.remoteAddress ?? 'unknown'}:${socket.remotePort ?? 0}`;
   const context = {
     connectionId,
+    clientAddress,
     monitorMode: false,
-    clientAddress: `${socket.remoteAddress ?? 'unknown'}:${socket.remotePort ?? 0}`,
     writeResponse(buf) {
       if (socket.writable) socket.write(buf);
     },
+    onUnknownCommand: hooks.onUnknownCommand,
+    onCommandError: hooks.onCommandError,
+    onSocketError: hooks.onSocketError,
   };
 
   function writeResult(out) {
@@ -94,5 +99,7 @@ export function handleConnection(socket, engine) {
     unregisterMonitorClient(connectionId);
   });
 
-  socket.on('error', () => {});
+  socket.on('error', (err) => {
+    context.onSocketError?.({ error: err, clientAddress: context.clientAddress, connectionId: context.connectionId });
+  });
 }

package/src/server/tcp-server.js

@@ -10,10 +10,15 @@ import { handleConnection } from './connection.js';
  * @param {object} options.engine
  * @param {number} [options.port=6379]
  * @param {string} [options.host='0.0.0.0']
+ * @param {Set<import('node:net').Socket>} [options.connections] If provided, each accepted socket is added here (for graceful shutdown).
  * @returns {import('node:net').Server}
  */
-export function createServer({ engine, port = 6379, host = '0.0.0.0' }) {
+export function createServer({ engine, port = 6379, host = '0.0.0.0', connections = null }) {
   const server = net.createServer((socket) => {
+    if (connections) {
+      connections.add(socket);
+      socket.once('close', () => connections.delete(socket));
+    }
     handleConnection(socket, engine);
   });
   return server;

package/test/integration/embed.test.js

@@ -88,4 +88,69 @@ describe('createRESPlite', () => {
     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);
+    try {
+      await client.sendCommand(['SUBSCRIBE', 'ch']);
+      assert.fail('expected error');
+    } catch (e) {
+      assert.ok(e.message.includes('not supported'), e.message);
+    }
+    await client.quit();
+    await srv.close();
+  });
+
+  it('onUnknownCommand hook is called for unsupported commands', async () => {
+    const unknownCalls = [];
+    const srv = await createRESPlite({
+      hooks: {
+        onUnknownCommand(payload) {
+          unknownCalls.push(payload);
+        },
+      },
+    });
+    const client = await redisClient(srv.port);
+    try {
+      await client.sendCommand(['SUBSCRIBE', 'ch']);
+    } catch (_) {}
+    try {
+      await client.sendCommand(['PUBLISH', 'ch', 'x']);
+    } catch (_) {}
+    await client.quit();
+    await srv.close();
+    const commands = unknownCalls.map((c) => c.command);
+    assert.ok(commands.includes('SUBSCRIBE'), 'expected SUBSCRIBE in ' + commands.join(', '));
+    assert.ok(commands.includes('PUBLISH'), 'expected PUBLISH in ' + commands.join(', '));
+    const sub = unknownCalls.find((c) => c.command === 'SUBSCRIBE');
+    const pub = unknownCalls.find((c) => c.command === 'PUBLISH');
+    assert.equal(sub.argsCount, 1);
+    assert.equal(pub.argsCount, 2);
+    assert.equal(typeof sub.connectionId, 'number');
+    assert.ok(sub.clientAddress.length > 0);
+  });
+
+  it('onCommandError hook is called when command returns or throws error', async () => {
+    const errorCalls = [];
+    const srv = await createRESPlite({
+      hooks: {
+        onCommandError(payload) {
+          errorCalls.push(payload);
+        },
+      },
+    });
+    const client = await redisClient(srv.port);
+    await client.set('k', 'str');
+    try {
+      await client.hGet('k', 'f');
+    } catch (_) {}
+    await client.quit();
+    await srv.close();
+    assert.equal(errorCalls.length, 1);
+    assert.equal(errorCalls[0].command, 'HGET');
+    assert.ok(errorCalls[0].error.includes('WRONGTYPE'));
+    assert.equal(typeof errorCalls[0].connectionId, 'number');
+    assert.ok(errorCalls[0].clientAddress.length > 0);
+  });
 });