resplite 1.4.20 → 1.5.0

package/package.json

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

package/src/commands/hexpire.js

@@ -0,0 +1,54 @@
+/**
+ * HEXPIRE key seconds [NX | XX | GT | LT] FIELDS numfields field [field ...]
+ * Redis 7.4 per-field TTL. Returns array of integers (-2/0/1/2) per field.
+ */
+
+const CONDITIONS = new Set(['NX', 'XX', 'GT', 'LT']);
+
+function parseFieldsTail(args, startIdx) {
+  if (args.length <= startIdx) return { error: 'ERR syntax error' };
+  const token = (Buffer.isBuffer(args[startIdx]) ? args[startIdx].toString('utf8') : String(args[startIdx])).toUpperCase();
+  if (token !== 'FIELDS') return { error: 'ERR syntax error' };
+  const numStr = args[startIdx + 1];
+  if (numStr == null) return { error: 'ERR syntax error' };
+  const n = parseInt(Buffer.isBuffer(numStr) ? numStr.toString('utf8') : String(numStr), 10);
+  if (!Number.isInteger(n) || n < 1) {
+    return { error: 'ERR numfields should be greater than 0' };
+  }
+  const fields = args.slice(startIdx + 2);
+  if (fields.length !== n) {
+    return { error: "ERR Parameter `numFields` should be equal to the number of arguments" };
+  }
+  return { fields };
+}
+
+export function handleHexpire(engine, args) {
+  if (!args || args.length < 5) {
+    return { error: "ERR wrong number of arguments for 'HEXPIRE' command" };
+  }
+  const key = args[0];
+  const secondsStr = Buffer.isBuffer(args[1]) ? args[1].toString('utf8') : String(args[1]);
+  const seconds = parseInt(secondsStr, 10);
+  if (!Number.isInteger(seconds)) {
+    return { error: 'ERR value is not an integer or out of range' };
+  }
+
+  let idx = 2;
+  let condition = null;
+  const maybeCond = (Buffer.isBuffer(args[idx]) ? args[idx].toString('utf8') : String(args[idx])).toUpperCase();
+  if (CONDITIONS.has(maybeCond)) {
+    condition = maybeCond;
+    idx += 1;
+  }
+
+  const parsed = parseFieldsTail(args, idx);
+  if (parsed.error) return parsed;
+
+  const expiresAtMs = engine._clock() + seconds * 1000;
+  try {
+    return engine.hexpire(key, expiresAtMs, parsed.fields, { condition });
+  } catch (e) {
+    const msg = e && e.message ? e.message : String(e);
+    return { error: msg.startsWith('ERR ') || msg.startsWith('WRONGTYPE') ? msg : 'ERR ' + msg };
+  }
+}

package/src/commands/hpersist.js

@@ -0,0 +1,36 @@
+/**
+ * HPERSIST key FIELDS numfields field [field ...]
+ * Removes per-field TTL. Returns array: -2 (missing), -1 (no TTL), 1 (cleared).
+ */
+
+function parseFieldsTail(args, startIdx) {
+  if (args.length <= startIdx) return { error: 'ERR syntax error' };
+  const token = (Buffer.isBuffer(args[startIdx]) ? args[startIdx].toString('utf8') : String(args[startIdx])).toUpperCase();
+  if (token !== 'FIELDS') return { error: 'ERR syntax error' };
+  const numStr = args[startIdx + 1];
+  if (numStr == null) return { error: 'ERR syntax error' };
+  const n = parseInt(Buffer.isBuffer(numStr) ? numStr.toString('utf8') : String(numStr), 10);
+  if (!Number.isInteger(n) || n < 1) {
+    return { error: 'ERR numfields should be greater than 0' };
+  }
+  const fields = args.slice(startIdx + 2);
+  if (fields.length !== n) {
+    return { error: "ERR Parameter `numFields` should be equal to the number of arguments" };
+  }
+  return { fields };
+}
+
+export function handleHpersist(engine, args) {
+  if (!args || args.length < 4) {
+    return { error: "ERR wrong number of arguments for 'HPERSIST' command" };
+  }
+  const key = args[0];
+  const parsed = parseFieldsTail(args, 1);
+  if (parsed.error) return parsed;
+  try {
+    return engine.hpersist(key, parsed.fields);
+  } catch (e) {
+    const msg = e && e.message ? e.message : String(e);
+    return { error: msg.startsWith('ERR ') || msg.startsWith('WRONGTYPE') ? msg : 'ERR ' + msg };
+  }
+}

package/src/commands/httl.js

@@ -0,0 +1,36 @@
+/**
+ * HTTL key FIELDS numfields field [field ...]
+ * Returns array of seconds per field: -2 (missing), -1 (no TTL), else remaining seconds.
+ */
+
+function parseFieldsTail(args, startIdx) {
+  if (args.length <= startIdx) return { error: 'ERR syntax error' };
+  const token = (Buffer.isBuffer(args[startIdx]) ? args[startIdx].toString('utf8') : String(args[startIdx])).toUpperCase();
+  if (token !== 'FIELDS') return { error: 'ERR syntax error' };
+  const numStr = args[startIdx + 1];
+  if (numStr == null) return { error: 'ERR syntax error' };
+  const n = parseInt(Buffer.isBuffer(numStr) ? numStr.toString('utf8') : String(numStr), 10);
+  if (!Number.isInteger(n) || n < 1) {
+    return { error: 'ERR numfields should be greater than 0' };
+  }
+  const fields = args.slice(startIdx + 2);
+  if (fields.length !== n) {
+    return { error: "ERR Parameter `numFields` should be equal to the number of arguments" };
+  }
+  return { fields };
+}
+
+export function handleHttl(engine, args) {
+  if (!args || args.length < 4) {
+    return { error: "ERR wrong number of arguments for 'HTTL' command" };
+  }
+  const key = args[0];
+  const parsed = parseFieldsTail(args, 1);
+  if (parsed.error) return parsed;
+  try {
+    return engine.httl(key, parsed.fields);
+  } catch (e) {
+    const msg = e && e.message ? e.message : String(e);
+    return { error: msg.startsWith('ERR ') || msg.startsWith('WRONGTYPE') ? msg : 'ERR ' + msg };
+  }
+}

package/src/commands/registry.js

@@ -36,6 +36,9 @@ import * as hdel from './hdel.js';
 import * as hlen from './hlen.js';
 import * as hexists from './hexists.js';
 import * as hincrby from './hincrby.js';
+import * as hexpireCmd from './hexpire.js';
+import * as httlCmd from './httl.js';
+import * as hpersistCmd from './hpersist.js';
 import * as sadd from './sadd.js';
 import * as srem from './srem.js';
 import * as smembers from './smembers.js';
@@ -122,6 +125,9 @@ const HANDLERS = new Map([
   ['HLEN', (e, a) => hlen.handleHlen(e, a)],
   ['HEXISTS', (e, a) => hexists.handleHexists(e, a)],
   ['HINCRBY', (e, a) => hincrby.handleHincrby(e, a)],
+  ['HEXPIRE', (e, a) => hexpireCmd.handleHexpire(e, a)],
+  ['HTTL', (e, a) => httlCmd.handleHttl(e, a)],
+  ['HPERSIST', (e, a) => hpersistCmd.handleHpersist(e, a)],
   ['SADD', (e, a) => sadd.handleSadd(e, a)],
   ['SREM', (e, a) => srem.handleSrem(e, a)],
   ['SMEMBERS', (e, a) => smembers.handleSmembers(e, a)],

package/src/engine/engine.js

@@ -16,15 +16,14 @@ import { asKey, asValue } from '../util/buffers.js';
 
 export function createEngine(opts = {}) {
   const { db, cache } = opts;
+  const clock = opts.clock ?? (() => Date.now());
   const keys = createKeysStorage(db);
   const strings = createStringsStorage(db, keys);
-  const hashes = createHashesStorage(db, keys);
+  const hashes = createHashesStorage(db, keys, { clock });
   const sets = createSetsStorage(db, keys);
   const lists = createListsStorage(db, keys);
   const zsets = createZsetsStorage(db, keys);
 
-  const clock = opts.clock ?? (() => Date.now());
-
   function _incrBy(key, delta) {
     const k = asKey(key);
     const meta = getKeyMeta(key);
@@ -254,6 +253,44 @@ export function createEngine(opts = {}) {
       return hashes.incr(k, asKey(field), amt);
     },
 
+    /**
+     * HEXPIRE: apply absolute expiresAtMs to each hash field with optional NX/XX/GT/LT.
+     * Returns an array of integers per spec: -2 (missing), 0 (cond), 1 (set), 2 (deleted).
+     */
+    hexpire(key, expiresAtMs, fields, { condition = null } = {}) {
+      const k = asKey(key);
+      const meta = getKeyMeta(key);
+      if (!meta) return fields.map(() => -2);
+      expectHash(meta);
+      return fields.map((f) => hashes.setFieldExpire(k, asKey(f), expiresAtMs, { condition }));
+    },
+
+    /**
+     * HTTL: seconds remaining per field. -2 missing, -1 no TTL, else seconds.
+     */
+    httl(key, fields) {
+      const k = asKey(key);
+      const meta = getKeyMeta(key);
+      if (!meta) return fields.map(() => -2);
+      expectHash(meta);
+      return fields.map((f) => {
+        const ms = hashes.getFieldTtl(k, asKey(f));
+        if (ms < 0) return ms;
+        return Math.floor(ms / 1000);
+      });
+    },
+
+    /**
+     * HPERSIST: clear field TTL. -2 missing, -1 no TTL, 1 cleared.
+     */
+    hpersist(key, fields) {
+      const k = asKey(key);
+      const meta = getKeyMeta(key);
+      if (!meta) return fields.map(() => -2);
+      expectHash(meta);
+      return fields.map((f) => hashes.persistField(k, asKey(f)));
+    },
+
     sadd(key, ...members) {
       const k = asKey(key);
       getKeyMeta(key);

package/src/engine/expiration.js

@@ -1,5 +1,6 @@
 /**
  * Active expiration: background sweeper that deletes expired keys in batches.
+ * Also prunes expired hash fields (redis_hash_field_ttl) and drops now-empty hashes.
  */
 
 /**
@@ -18,11 +19,38 @@ export function createExpirationSweeper(opts) {
   const deleteExpiredStmt = db.prepare(
     'DELETE FROM redis_keys WHERE key IN (SELECT key FROM redis_keys WHERE expires_at IS NOT NULL AND expires_at <= ? LIMIT ?)'
   );
+  const selectExpiredFieldsStmt = db.prepare(
+    'SELECT key, field FROM redis_hash_field_ttl WHERE expires_at <= ? LIMIT ?'
+  );
+  const deleteHashFieldStmt = db.prepare('DELETE FROM redis_hashes WHERE key = ? AND field = ?');
+  const deleteFieldTtlStmt = db.prepare('DELETE FROM redis_hash_field_ttl WHERE key = ? AND field = ?');
+  const countHashStmt = db.prepare('SELECT COUNT(*) AS n FROM redis_hashes WHERE key = ?');
+  const updateHashCountStmt = db.prepare('UPDATE redis_keys SET hash_count = ? WHERE key = ?');
+  const deleteKeyStmt = db.prepare('DELETE FROM redis_keys WHERE key = ?');
+
+  const sweepFieldsTxn = db.transaction((pairs) => {
+    const affected = new Map();
+    for (const pair of pairs) {
+      deleteHashFieldStmt.run(pair.key, pair.field);
+      deleteFieldTtlStmt.run(pair.key, pair.field);
+      const seenKey = pair.key.toString('base64');
+      if (!affected.has(seenKey)) affected.set(seenKey, pair.key);
+    }
+    for (const key of affected.values()) {
+      const row = countHashStmt.get(key);
+      const n = row ? row.n : 0;
+      if (n === 0) deleteKeyStmt.run(key);
+      else updateHashCountStmt.run(n, key);
+    }
+  });
+
   let intervalId = null;
 
   function sweep() {
     const now = clock();
     deleteExpiredStmt.run(now, maxKeysPerSweep);
+    const pairs = selectExpiredFieldsStmt.all(now, maxKeysPerSweep);
+    if (pairs.length > 0) sweepFieldsTxn(pairs);
   }
 
   return {

package/src/storage/sqlite/hashes.js

@@ -1,6 +1,8 @@
 /**
  * Hash storage: redis_hashes + coordination with redis_keys.
  * Empty hash removes the key (Section 8.6).
+ * Per-field TTL is tracked in redis_hash_field_ttl (epoch milliseconds);
+ * HSET/HINCRBY clear a field's TTL, lazy-expiration prunes stale fields.
  */
 
 import { KEY_TYPES } from './schema.js';
@@ -9,28 +11,84 @@ import { runInTransaction } from './tx.js';
 /**
  * @param {import('better-sqlite3').Database} db
  * @param {ReturnType<import('./keys.js').createKeysStorage>} keys
+ * @param {{ clock?: () => number }} [options]
  */
-export function createHashesStorage(db, keys) {
+export function createHashesStorage(db, keys, options = {}) {
+  const clock = options.clock ?? (() => Date.now());
+
   const getStmt = db.prepare('SELECT value FROM redis_hashes WHERE key = ? AND field = ?');
   const getAllStmt = db.prepare('SELECT field, value FROM redis_hashes WHERE key = ?').raw(true);
+  const getAllLiveStmt = db
+    .prepare(
+      `SELECT h.field, h.value
+         FROM redis_hashes h
+         LEFT JOIN redis_hash_field_ttl t ON t.key = h.key AND t.field = h.field
+        WHERE h.key = ? AND (t.expires_at IS NULL OR t.expires_at > ?)`
+    )
+    .raw(true);
   const insertStmt = db.prepare('INSERT OR REPLACE INTO redis_hashes (key, field, value) VALUES (?, ?, ?)');
   const deleteStmt = db.prepare('DELETE FROM redis_hashes WHERE key = ? AND field = ?');
   const deleteAllStmt = db.prepare('DELETE FROM redis_hashes WHERE key = ?');
   const countStmt = db.prepare('SELECT COUNT(*) AS n FROM redis_hashes WHERE key = ?');
+  const countLiveStmt = db.prepare(
+    `SELECT COUNT(*) AS n
+       FROM redis_hashes h
+       LEFT JOIN redis_hash_field_ttl t ON t.key = h.key AND t.field = h.field
+      WHERE h.key = ? AND (t.expires_at IS NULL OR t.expires_at > ?)`
+  );
+  const hasAnyTtlStmt = db.prepare('SELECT 1 FROM redis_hash_field_ttl WHERE key = ? LIMIT 1').pluck();
+
+  const getFieldTtlStmt = db.prepare(
+    'SELECT expires_at AS expiresAt FROM redis_hash_field_ttl WHERE key = ? AND field = ?'
+  );
+  const upsertFieldTtlStmt = db.prepare(
+    'INSERT OR REPLACE INTO redis_hash_field_ttl (key, field, expires_at) VALUES (?, ?, ?)'
+  );
+  const deleteFieldTtlStmt = db.prepare('DELETE FROM redis_hash_field_ttl WHERE key = ? AND field = ?');
+
+  /**
+   * If the field has an expired TTL row, delete the field + TTL row, adjust count
+   * (and drop the whole key when empty). Returns true if the field was purged.
+   */
+  function expireFieldIfDue(key, field, now) {
+    const ttl = getFieldTtlStmt.get(key, field);
+    if (!ttl || ttl.expiresAt > now) return false;
+    const existed = getStmt.get(key, field) != null;
+    deleteFieldTtlStmt.run(key, field);
+    if (!existed) return true;
+    deleteStmt.run(key, field);
+    const meta = keys.get(key);
+    if (!meta) return true;
+    const before = meta.hashCount != null ? meta.hashCount : (countStmt.get(key) || { n: 0 }).n + 1;
+    const remaining = Math.max(0, before - 1);
+    if (remaining === 0) {
+      deleteAllStmt.run(key);
+      keys.delete(key);
+    } else {
+      keys.setHashCount(key, remaining, { touchUpdatedAt: false });
+    }
+    return true;
+  }
 
   return {
     get(key, field) {
+      runInTransaction(db, () => {
+        expireFieldIfDue(key, field, clock());
+      });
       const row = getStmt.get(key, field);
       return row ? row.value : null;
     },
 
     getAll(key) {
-      return getAllStmt.all(key).flat();
+      const now = clock();
+      const hasTtl = hasAnyTtlStmt.get(key);
+      if (!hasTtl) return getAllStmt.all(key).flat();
+      return getAllLiveStmt.all(key, now).flat();
     },
 
     set(key, field, value, options = {}) {
       runInTransaction(db, () => {
-        const now = options.updatedAt ?? Date.now();
+        const now = options.updatedAt ?? clock();
         const meta = keys.get(key);
         let knownCount = 0;
         if (meta) {
@@ -50,6 +108,7 @@ export function createHashesStorage(db, keys) {
         }
         const existed = getStmt.get(key, field) != null;
         insertStmt.run(key, field, value);
+        deleteFieldTtlStmt.run(key, field);
         if (!existed) {
           if (meta) keys.incrHashCount(key, 1, { touchUpdatedAt: false });
           else keys.setHashCount(key, 1, { touchUpdatedAt: false });
@@ -62,7 +121,7 @@ export function createHashesStorage(db, keys) {
 
     setMultiple(key, pairs, options = {}) {
       runInTransaction(db, () => {
-        const now = options.updatedAt ?? Date.now();
+        const now = options.updatedAt ?? clock();
         const meta = keys.get(key);
         let knownCount = 0;
         if (meta) {
@@ -84,6 +143,7 @@ export function createHashesStorage(db, keys) {
         for (let i = 0; i < pairs.length; i += 2) {
           const existed = getStmt.get(key, pairs[i]) != null;
           insertStmt.run(key, pairs[i], pairs[i + 1]);
+          deleteFieldTtlStmt.run(key, pairs[i]);
           if (!existed) added++;
         }
         if (added > 0) {
@@ -103,6 +163,7 @@ export function createHashesStorage(db, keys) {
         let n = 0;
         for (const field of fields) {
           const r = deleteStmt.run(key, field);
+          deleteFieldTtlStmt.run(key, field);
           n += r.changes;
         }
         const remaining = before != null ? Math.max(0, before - n) : ((countStmt.get(key) || {}).n ?? 0);
@@ -118,21 +179,26 @@ export function createHashesStorage(db, keys) {
 
     count(key) {
       const meta = keys.get(key);
-      if (meta && meta.type === KEY_TYPES.HASH && meta.hashCount != null) {
-        return meta.hashCount;
+      if (!meta || meta.type !== KEY_TYPES.HASH) {
+        const row = countStmt.get(key);
+        return row ? row.n : 0;
+      }
+      const hasTtl = hasAnyTtlStmt.get(key);
+      if (hasTtl) {
+        const row = countLiveStmt.get(key, clock());
+        return row ? row.n : 0;
       }
+      if (meta.hashCount != null) return meta.hashCount;
       const row = countStmt.get(key);
       const n = row ? row.n : 0;
-      if (meta && meta.type === KEY_TYPES.HASH && meta.hashCount == null) {
-        // One-time hydration for databases created before hash_count existed.
-        keys.setHashCount(key, n, { touchUpdatedAt: false });
-      }
+      // One-time hydration for databases created before hash_count existed.
+      keys.setHashCount(key, n, { touchUpdatedAt: false });
       return n;
     },
 
     incr(key, field, delta, options = {}) {
       return runInTransaction(db, () => {
-        const now = options.updatedAt ?? Date.now();
+        const now = options.updatedAt ?? clock();
         const meta = keys.get(key);
         if (meta && meta.type !== KEY_TYPES.HASH) {
           throw new Error('WRONGTYPE Operation against a key holding the wrong kind of value');
@@ -147,11 +213,13 @@ export function createHashesStorage(db, keys) {
             keys.setHashCount(key, hydrated, { touchUpdatedAt: false });
           }
         }
+        expireFieldIfDue(key, field, now);
         const cur = getStmt.get(key, field);
         const num = cur == null ? 0 : parseInt(cur.value.toString('utf8'), 10);
         if (Number.isNaN(num)) throw new Error('ERR hash value is not an integer');
         const next = num + delta;
         insertStmt.run(key, field, Buffer.from(String(next), 'utf8'));
+        deleteFieldTtlStmt.run(key, field);
         if (cur == null) {
           if (meta) keys.incrHashCount(key, 1, { touchUpdatedAt: false });
           else keys.setHashCount(key, 1, { touchUpdatedAt: false });
@@ -160,6 +228,81 @@ export function createHashesStorage(db, keys) {
       });
     },
 
+    /**
+     * Per-field expiration set. Returns -2/0/1/2 per HEXPIRE spec.
+     * `condition` is null or one of 'NX','XX','GT','LT'.
+     */
+    setFieldExpire(key, field, expiresAtMs, { condition = null } = {}) {
+      return runInTransaction(db, () => {
+        const now = clock();
+        expireFieldIfDue(key, field, now);
+        const exists = getStmt.get(key, field) != null;
+        if (!exists) return -2;
+        const current = getFieldTtlStmt.get(key, field);
+        const currentMs = current ? current.expiresAt : null;
+        if (condition === 'NX' && currentMs != null) return 0;
+        if (condition === 'XX' && currentMs == null) return 0;
+        if (condition === 'GT') {
+          if (currentMs == null) return 0;
+          if (!(expiresAtMs > currentMs)) return 0;
+        }
+        if (condition === 'LT') {
+          if (currentMs != null && !(expiresAtMs < currentMs)) return 0;
+        }
+        if (expiresAtMs <= now) {
+          deleteStmt.run(key, field);
+          deleteFieldTtlStmt.run(key, field);
+          const meta = keys.get(key);
+          if (meta) {
+            const before = meta.hashCount != null ? meta.hashCount : (countStmt.get(key) || { n: 0 }).n + 1;
+            const remaining = Math.max(0, before - 1);
+            if (remaining === 0) {
+              deleteAllStmt.run(key);
+              keys.delete(key);
+            } else {
+              keys.setHashCount(key, remaining, { touchUpdatedAt: false });
+            }
+          }
+          return 2;
+        }
+        upsertFieldTtlStmt.run(key, field, expiresAtMs);
+        return 1;
+      });
+    },
+
+    /**
+     * Returns remaining ms (>= 0), -1 if field has no TTL, -2 if field missing.
+     */
+    getFieldTtl(key, field) {
+      const now = clock();
+      let removed = false;
+      runInTransaction(db, () => {
+        removed = expireFieldIfDue(key, field, now);
+      });
+      if (removed) return -2;
+      const exists = getStmt.get(key, field) != null;
+      if (!exists) return -2;
+      const row = getFieldTtlStmt.get(key, field);
+      if (!row) return -1;
+      return Math.max(0, row.expiresAt - now);
+    },
+
+    /**
+     * Clears a field's TTL. Returns 1 if cleared, -1 if no TTL, -2 if field missing.
+     */
+    persistField(key, field) {
+      return runInTransaction(db, () => {
+        const now = clock();
+        expireFieldIfDue(key, field, now);
+        const exists = getStmt.get(key, field) != null;
+        if (!exists) return -2;
+        const row = getFieldTtlStmt.get(key, field);
+        if (!row) return -1;
+        deleteFieldTtlStmt.run(key, field);
+        return 1;
+      });
+    },
+
     /** Copy all field/value rows from oldKey to newKey. Caller ensures newKey exists in redis_keys. */
     copyKey(oldKey, newKey) {
       const rows = getAllStmt.all(oldKey);

package/src/storage/sqlite/schema.js

@@ -66,6 +66,17 @@ CREATE TABLE IF NOT EXISTS redis_zsets (
 CREATE INDEX IF NOT EXISTS redis_zsets_key_score_member_idx
   ON redis_zsets(key, score, member);
 
+CREATE TABLE IF NOT EXISTS redis_hash_field_ttl (
+  key BLOB NOT NULL,
+  field BLOB NOT NULL,
+  expires_at INTEGER NOT NULL,
+  PRIMARY KEY (key, field),
+  FOREIGN KEY(key) REFERENCES redis_keys(key) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS redis_hash_field_ttl_expires_at_idx
+  ON redis_hash_field_ttl(expires_at);
+
 CREATE TABLE IF NOT EXISTS search_indices (
   name TEXT PRIMARY KEY,
   schema_json TEXT NOT NULL,

package/test/integration/hashes.test.js

@@ -65,6 +65,88 @@ describe('Hashes integration', () => {
     assert.equal(tryParseValue(reply, 0).value, 3);
   });
 
+  it('HEXPIRE + HTTL + HPERSIST round-trip (node-redis style argv)', async () => {
+    await sendCommand(port, argv('HSET', 'LobbyStream', '6GQZW:FBAX7', '1'));
+    // Mirror the exact argv seen in the node-redis client log.
+    const hexpireReply = await sendCommand(
+      port,
+      argv('HEXPIRE', 'LobbyStream', '90', 'FIELDS', '1', '6GQZW:FBAX7')
+    );
+    const hexpireVal = tryParseValue(hexpireReply, 0).value;
+    assert.ok(Array.isArray(hexpireVal));
+    assert.equal(hexpireVal.length, 1);
+    assert.equal(Number(hexpireVal[0]), 1);
+
+    const httlReply = await sendCommand(
+      port,
+      argv('HTTL', 'LobbyStream', 'FIELDS', '1', '6GQZW:FBAX7')
+    );
+    const httlVal = tryParseValue(httlReply, 0).value;
+    assert.ok(Array.isArray(httlVal));
+    assert.equal(httlVal.length, 1);
+    const secs = Number(httlVal[0]);
+    assert.ok(secs > 0 && secs <= 90, `expected 0 < ttl <= 90, got ${secs}`);
+
+    const hpersistReply = await sendCommand(
+      port,
+      argv('HPERSIST', 'LobbyStream', 'FIELDS', '1', '6GQZW:FBAX7')
+    );
+    const hpersistVal = tryParseValue(hpersistReply, 0).value;
+    assert.equal(Number(hpersistVal[0]), 1);
+
+    const httlReply2 = await sendCommand(
+      port,
+      argv('HTTL', 'LobbyStream', 'FIELDS', '1', '6GQZW:FBAX7')
+    );
+    const ttl2 = Number(tryParseValue(httlReply2, 0).value[0]);
+    assert.equal(ttl2, -1);
+  });
+
+  it('HEXPIRE returns -2 for missing key/field', async () => {
+    const missingKey = await sendCommand(
+      port,
+      argv('HEXPIRE', 'hexp:nokey', '5', 'FIELDS', '1', 'f1')
+    );
+    assert.equal(Number(tryParseValue(missingKey, 0).value[0]), -2);
+
+    await sendCommand(port, argv('HSET', 'hexp:k', 'f1', 'v1'));
+    const missingField = await sendCommand(
+      port,
+      argv('HEXPIRE', 'hexp:k', '5', 'FIELDS', '1', 'nope')
+    );
+    assert.equal(Number(tryParseValue(missingField, 0).value[0]), -2);
+  });
+
+  it('HEXPIRE with 0 seconds deletes the field (returns 2)', async () => {
+    await sendCommand(port, argv('HSET', 'hexp:zero', 'f1', 'v1', 'f2', 'v2'));
+    const reply = await sendCommand(
+      port,
+      argv('HEXPIRE', 'hexp:zero', '0', 'FIELDS', '1', 'f1')
+    );
+    assert.equal(Number(tryParseValue(reply, 0).value[0]), 2);
+    const getReply = await sendCommand(port, argv('HGET', 'hexp:zero', 'f1'));
+    assert.ok(getReply.toString('utf8').startsWith('$-1'));
+  });
+
+  it('HEXPIRE NX condition fails on existing TTL', async () => {
+    await sendCommand(port, argv('HSET', 'hexp:nx', 'f1', 'v1'));
+    await sendCommand(port, argv('HEXPIRE', 'hexp:nx', '10', 'FIELDS', '1', 'f1'));
+    const reply = await sendCommand(
+      port,
+      argv('HEXPIRE', 'hexp:nx', '20', 'NX', 'FIELDS', '1', 'f1')
+    );
+    assert.equal(Number(tryParseValue(reply, 0).value[0]), 0);
+  });
+
+  it('HEXPIRE FIELDS count mismatch is a syntax error', async () => {
+    await sendCommand(port, argv('HSET', 'hexp:bad', 'f1', 'v1'));
+    const reply = await sendCommand(
+      port,
+      argv('HEXPIRE', 'hexp:bad', '10', 'FIELDS', '2', 'f1')
+    );
+    assert.ok(reply.toString('utf8').startsWith('-'), 'expected error reply');
+  });
+
   it('legacy hash rows with null hash_count hydrate on first HLEN', async () => {
     const s1 = await createTestServer();
     await sendCommand(s1.port, argv('HSET', 'legacy:h', 'f1', 'v1', 'f2', 'v2'));

package/test/unit/engine-hashes.test.js

@@ -56,3 +56,165 @@ describe('Engine hashes', () => {
     assert.throws(() => engine.hlen('hlen:str'), /WRONGTYPE/);
   });
 });
+
+describe('Engine hash field TTL', () => {
+  function makeEngine(nowMs) {
+    const dbPath = tmpDbPath();
+    const db = openDb(dbPath);
+    let t = nowMs;
+    const clock = () => t;
+    const engine = createEngine({ db, clock });
+    return {
+      engine,
+      advance(ms) { t += ms; },
+      clock: () => t,
+    };
+  }
+
+  it('HEXPIRE sets TTL; HTTL reports seconds', () => {
+    const { engine } = makeEngine(1_000_000);
+    engine.hset('h', 'f1', 'v1');
+    const res = engine.hexpire('h', engine._clock() + 60_000, [Buffer.from('f1')]);
+    assert.deepEqual(res, [1]);
+    assert.deepEqual(engine.httl('h', [Buffer.from('f1')]), [60]);
+  });
+
+  it('HTTL returns -1 for field without TTL, -2 for missing field/key', () => {
+    const { engine } = makeEngine(1_000_000);
+    engine.hset('h', 'f1', 'v1');
+    assert.deepEqual(engine.httl('h', [Buffer.from('f1')]), [-1]);
+    assert.deepEqual(engine.httl('h', [Buffer.from('missing')]), [-2]);
+    assert.deepEqual(engine.httl('nokey', [Buffer.from('f1')]), [-2]);
+  });
+
+  it('HEXPIRE with non-existent field returns -2', () => {
+    const { engine } = makeEngine(1_000_000);
+    engine.hset('h', 'f1', 'v1');
+    const res = engine.hexpire('h', engine._clock() + 1000, [Buffer.from('nope')]);
+    assert.deepEqual(res, [-2]);
+  });
+
+  it('HEXPIRE with expiresAt in the past deletes the field (returns 2)', () => {
+    const { engine } = makeEngine(1_000_000);
+    engine.hset('h', 'f1', 'v1', 'f2', 'v2');
+    const res = engine.hexpire('h', engine._clock() - 1, [Buffer.from('f1')]);
+    assert.deepEqual(res, [2]);
+    assert.equal(engine.hget('h', 'f1'), null);
+    assert.equal(engine.hlen('h'), 1);
+  });
+
+  it('HEXPIRE NX/XX condition semantics', () => {
+    const { engine } = makeEngine(1_000_000);
+    engine.hset('h', 'f1', 'v1');
+    assert.deepEqual(
+      engine.hexpire('h', engine._clock() + 1000, [Buffer.from('f1')], { condition: 'XX' }),
+      [0]
+    );
+    assert.deepEqual(
+      engine.hexpire('h', engine._clock() + 1000, [Buffer.from('f1')], { condition: 'NX' }),
+      [1]
+    );
+    assert.deepEqual(
+      engine.hexpire('h', engine._clock() + 2000, [Buffer.from('f1')], { condition: 'NX' }),
+      [0]
+    );
+    assert.deepEqual(
+      engine.hexpire('h', engine._clock() + 2000, [Buffer.from('f1')], { condition: 'XX' }),
+      [1]
+    );
+  });
+
+  it('HEXPIRE GT/LT condition semantics', () => {
+    const { engine } = makeEngine(1_000_000);
+    engine.hset('h', 'f1', 'v1');
+    assert.deepEqual(
+      engine.hexpire('h', engine._clock() + 1000, [Buffer.from('f1')], { condition: 'GT' }),
+      [0]
+    );
+    assert.deepEqual(
+      engine.hexpire('h', engine._clock() + 1000, [Buffer.from('f1')], { condition: 'LT' }),
+      [1]
+    );
+    assert.deepEqual(
+      engine.hexpire('h', engine._clock() + 500, [Buffer.from('f1')], { condition: 'GT' }),
+      [0]
+    );
+    assert.deepEqual(
+      engine.hexpire('h', engine._clock() + 2000, [Buffer.from('f1')], { condition: 'GT' }),
+      [1]
+    );
+  });
+
+  it('lazy expiration: HGET returns null after TTL; HLEN reflects live count', () => {
+    const { engine, advance } = makeEngine(1_000_000);
+    engine.hset('h', 'f1', 'v1', 'f2', 'v2');
+    engine.hexpire('h', engine._clock() + 1000, [Buffer.from('f1')]);
+    assert.equal(engine.hget('h', 'f1').toString(), 'v1');
+    assert.equal(engine.hlen('h'), 2);
+    advance(2000);
+    assert.equal(engine.hget('h', 'f1'), null);
+    assert.equal(engine.hlen('h'), 1);
+    const all = engine.hgetall('h');
+    assert.equal(all.length, 2);
+    assert.equal(all[0].toString(), 'f2');
+  });
+
+  it('empty hash after lazy expiration removes the key', () => {
+    const { engine, advance } = makeEngine(1_000_000);
+    engine.hset('h', 'f1', 'v1');
+    engine.hexpire('h', engine._clock() + 1000, [Buffer.from('f1')]);
+    advance(2000);
+    engine.hget('h', 'f1');
+    assert.equal(engine.type('h'), 'none');
+  });
+
+  it('HSET clears a field TTL', () => {
+    const { engine } = makeEngine(1_000_000);
+    engine.hset('h', 'f1', 'v1');
+    engine.hexpire('h', engine._clock() + 5000, [Buffer.from('f1')]);
+    assert.deepEqual(engine.httl('h', [Buffer.from('f1')]), [5]);
+    engine.hset('h', 'f1', 'v2');
+    assert.deepEqual(engine.httl('h', [Buffer.from('f1')]), [-1]);
+  });
+
+  it('HINCRBY clears a field TTL', () => {
+    const { engine } = makeEngine(1_000_000);
+    engine.hset('h', 'n', '1');
+    engine.hexpire('h', engine._clock() + 5000, [Buffer.from('n')]);
+    engine.hincrby('h', 'n', 2);
+    assert.deepEqual(engine.httl('h', [Buffer.from('n')]), [-1]);
+  });
+
+  it('HDEL removes field TTL row too (no leak)', () => {
+    const { engine } = makeEngine(1_000_000);
+    engine.hset('h', 'f1', 'v1', 'f2', 'v2');
+    engine.hexpire('h', engine._clock() + 5000, [Buffer.from('f1')]);
+    engine.hdel('h', ['f1']);
+    assert.deepEqual(engine.httl('h', [Buffer.from('f1')]), [-2]);
+  });
+
+  it('HPERSIST clears field TTL', () => {
+    const { engine } = makeEngine(1_000_000);
+    engine.hset('h', 'f1', 'v1');
+    engine.hexpire('h', engine._clock() + 5000, [Buffer.from('f1')]);
+    assert.deepEqual(engine.hpersist('h', [Buffer.from('f1')]), [1]);
+    assert.deepEqual(engine.httl('h', [Buffer.from('f1')]), [-1]);
+    assert.deepEqual(engine.hpersist('h', [Buffer.from('f1')]), [-1]);
+    assert.deepEqual(engine.hpersist('h', [Buffer.from('nope')]), [-2]);
+  });
+
+  it('HEXPIRE on missing hash key returns -2 for each field', () => {
+    const { engine } = makeEngine(1_000_000);
+    const res = engine.hexpire('nokey', engine._clock() + 1000, [Buffer.from('a'), Buffer.from('b')]);
+    assert.deepEqual(res, [-2, -2]);
+  });
+
+  it('HEXPIRE against a wrong-type key raises WRONGTYPE', () => {
+    const { engine } = makeEngine(1_000_000);
+    engine.set('str', 'v');
+    assert.throws(
+      () => engine.hexpire('str', engine._clock() + 1000, [Buffer.from('x')]),
+      /WRONGTYPE/
+    );
+  });
+});

package/test/unit/expiration.test.js

@@ -1,6 +1,7 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
 import { createEngine } from '../../src/engine/engine.js';
+import { createExpirationSweeper } from '../../src/engine/expiration.js';
 import { openDb } from '../../src/storage/sqlite/db.js';
 import { tmpDbPath } from '../helpers/tmp.js';
 import { fixedClock } from '../helpers/clock.js';
@@ -43,3 +44,45 @@ describe('Expiration', () => {
     assert.equal(engine.ttl('p'), -1);
   });
 });
+
+describe('Hash field expiration sweeper', () => {
+  it('sweeps expired hash fields and removes now-empty hash keys', () => {
+    const dbPath = tmpDbPath();
+    const db = openDb(dbPath);
+    let t = 1_000_000;
+    const clock = () => t;
+    const engine = createEngine({ db, clock });
+    const sweeper = createExpirationSweeper({ db, clock, sweepIntervalMs: 30 });
+
+    engine.hset('h1', 'f1', 'v1', 'f2', 'v2');
+    engine.hset('h2', 'only', 'gone');
+    engine.hexpire('h1', t + 500, [Buffer.from('f1')]);
+    engine.hexpire('h2', t + 500, [Buffer.from('only')]);
+
+    t += 1000;
+
+    // Drive a single sweep via start()/stop() bookends plus a manual flush.
+    // Sweeper's sweep() is internal; expose it by creating one tick's worth of behavior.
+    const row = db.prepare('SELECT COUNT(*) AS n FROM redis_hash_field_ttl WHERE expires_at <= ?').get(t);
+    assert.equal(row.n, 2);
+
+    // Drain by advancing: reuse setInterval semantics indirectly by stepping logic.
+    // Emulate a tick by starting the sweeper with a very short interval and waiting briefly.
+    sweeper.start();
+    return new Promise((resolve) => {
+      setTimeout(() => {
+        try {
+          sweeper.stop();
+          const ttlRows = db.prepare('SELECT COUNT(*) AS n FROM redis_hash_field_ttl').get();
+          assert.equal(ttlRows.n, 0, 'TTL rows should be swept');
+          assert.equal(engine.hget('h1', 'f1'), null);
+          assert.equal(engine.hlen('h1'), 1);
+          assert.equal(engine.type('h2'), 'none');
+          resolve();
+        } catch (e) {
+          resolve(Promise.reject(e));
+        }
+      }, 120);
+    });
+  });
+});