@volter/world-core 3.0.38 → 3.0.39

package/dist/src/redis/engine.js

@@ -66,6 +66,15 @@ export class RedisStatus {
     }
 }
 export const OK = new RedisStatus('OK');
+/** The JSON projection of a RESP reply — what Upstash puts in `{"result": …}`. */
+// Redis integers are signed 64-bit on RESP; JSON clients read them as JSON numbers.
+export class RedisInteger {
+    integer;
+    constructor(integer) {
+        this.integer = integer;
+    }
+}
+const integerReply = (n) => n >= -9007199254740991n && n <= 9007199254740991n ? Number(n) : new RedisInteger(String(n));
 /** A command-level failure. `message` is the vendor's literal error string. Maps to HTTP 400. */
 export class RedisCommandError extends Error {
     constructor(message) {
@@ -125,6 +134,7 @@ export const SERVED_COMMANDS = {
     ZADD: [3, -1], ZINCRBY: [3, 3], ZSCORE: [2, 2], ZCARD: [1, 1], ZCOUNT: [3, 3],
     ZRANK: [2, 3], ZREVRANK: [2, 3], ZREM: [2, -1], ZREMRANGEBYSCORE: [3, 3], ZREMRANGEBYRANK: [3, 3],
     ZRANGE: [3, -1], ZREVRANGE: [3, -1], ZRANGEBYSCORE: [3, -1], ZREVRANGEBYSCORE: [3, -1],
+    LPOS: [2, -1], RPOPLPUSH: [2, 2], ZPOPMIN: [1, 2], XTRIM: [3, -1],
     XADD: [4, -1], XLEN: [1, 1], XRANGE: [3, -1], XREVRANGE: [3, -1], XDEL: [2, -1],
     SCRIPT: [1, -1], EVAL: [2, -1], EVAL_RO: [2, -1], EVALSHA: [2, -1], EVALSHA_RO: [2, -1],
 };
@@ -135,7 +145,7 @@ const WRITE_COMMANDS = new Set([
     'EXPIRE', 'PEXPIRE', 'EXPIREAT', 'PEXPIREAT', 'PERSIST', 'RENAME', 'RENAMENX',
     'FLUSHDB', 'FLUSHALL', 'HSET', 'HSETNX', 'HMSET', 'HDEL', 'HINCRBY', 'HINCRBYFLOAT',
     'SADD', 'SREM', 'SPOP', 'LPUSH', 'RPUSH', 'LPOP', 'RPOP', 'LREM', 'LSET', 'LTRIM',
-    'ZADD', 'ZINCRBY', 'ZREM', 'ZREMRANGEBYSCORE', 'ZREMRANGEBYRANK', 'XADD', 'XDEL',
+    'RPOPLPUSH', 'ZPOPMIN', 'XTRIM', 'ZADD', 'ZINCRBY', 'ZREM', 'ZREMRANGEBYSCORE', 'ZREMRANGEBYRANK', 'XADD', 'XDEL',
     // NB: 'SCRIPT' is deliberately ABSENT — it is classified per SUBCOMMAND below, because
     // `SCRIPT EXISTS` is a pure read and a read-only twin must serve every read (§9 round 1 found
     // it answering 405). Likewise `EVAL_RO`/`EVALSHA_RO` are reads by definition.
@@ -238,7 +248,7 @@ function patchImage(image, changed, removed, scope) {
             name,
             kind: rec.kind,
             v: rec.v,
-            pexpireAt: typeof rec.pexpire_at === 'number' ? rec.pexpire_at : null,
+            pexpireAt: typeof rec.pexpire_at === 'string' || typeof rec.pexpire_at === 'number' ? String(rec.pexpire_at) : null,
             ...(typeof rec.last_id === 'string' && rec.last_id !== '' ? { lastId: rec.last_id } : {}),
             ...(typeof rec._rev === 'number' ? { _rev: rec._rev } : {}),
             ...(rec.meta !== undefined && rec.meta !== null ? { meta: rec.meta } : {}),
@@ -285,7 +295,7 @@ export class KeySpace {
     live(row) {
         if (!row)
             return undefined;
-        return row.pexpireAt !== null && row.pexpireAt < this.nowMs ? undefined : row;
+        return row.pexpireAt !== null && BigInt(row.pexpireAt) < BigInt(this.nowMs) ? undefined : row;
     }
     all() { return [...this.rows.values()].filter((r) => this.live(r) !== undefined); }
     // ── the EVAL script cache ────────────────────────────────────────────────────────────────
@@ -440,14 +450,36 @@ export const asZSet = (row) => {
 export const storeZSet = (pairs) => pairs.map(([m, sc]) => [m, fmtScore(sc)]);
 export const asStream = (row) => { expectType(row, STREAM); expectShape(row, Array.isArray(row?.v)); return row ? row.v.map(([id, f]) => [id, f.map(([field, value]) => [field, value])]) : []; };
 // ── numeric parsing (Redis's exact acceptance rules) ──────────────────────────────────────────
-export function toInt(raw) {
-    if (raw !== raw.trim() || !/^[+-]?\d+$/.test(raw))
-        throw new RedisCommandError(NOT_INT);
-    const n = Number(raw);
-    if (!Number.isSafeInteger(n))
-        throw new RedisCommandError(NOT_INT);
+// source: https://raw.githubusercontent.com/redis/redis/c9d29f6a918c335bc1778d9f68e521c1bbb36a0f/src/util.c "Convert a string into a long long."
+export function integerArgument(raw, message = NOT_INT, unsigned = false) {
+    // source: https://raw.githubusercontent.com/redis/redis/c9d29f6a918c335bc1778d9f68e521c1bbb36a0f/src/util.c "strtoull() is used instead."
+    if (unsigned) {
+        const canonical = /^(0|[1-9]\d*|-[1-9]\d*)$/.test(raw);
+        if (!canonical && !/^[ \t\r\n\v\f]*[+-]?\d+$/.test(raw))
+            throw new RedisCommandError(message);
+        const n = BigInt(raw.trim());
+        if (n > 18446744073709551615n || n < -18446744073709551615n || canonical && n < 0n)
+            throw new RedisCommandError(message);
+        return BigInt.asUintN(64, n);
+    }
+    if (!/^(0|[1-9]\d*|-[1-9]\d*)$/.test(raw))
+        throw new RedisCommandError(message);
+    const n = BigInt(raw);
+    if (n < -9223372036854775808n || n > 9223372036854775807n)
+        throw new RedisCommandError(message);
     return n;
 }
+// Collection positions/counts are bounded by their actual arrays, not by Number.MAX_SAFE_INTEGER.
+export const commandInteger = (raw, message = NOT_INT) => Number(integerArgument(raw, message));
+export const toInt = commandInteger;
+export const unsignedArgument = (raw, message) => integerArgument(raw, message, true);
+// source: https://raw.githubusercontent.com/redis/redis/c9d29f6a918c335bc1778d9f68e521c1bbb36a0f/src/object.c "value is out of range, must be positive"
+export function positiveInteger(raw, message = 'ERR value is out of range, must be positive') {
+    const n = integerArgument(raw, message);
+    if (n < 0)
+        throw new RedisCommandError(message);
+    return Number(n);
+}
 export function toFloat(raw) {
     if (raw !== raw.trim() || raw === '')
         throw new RedisCommandError(NOT_FLOAT);
@@ -532,20 +564,13 @@ export function globMatch(pattern, subject) {
 }
 // ── TTL option parsing, shared by SET and GETEX ────────────────────────────────────────────────
 function ttlFromToken(token, value, nowMs, cmd) {
-    const n = toInt(value);
-    if (token === 'ex') {
-        if (n <= 0)
-            throw new RedisCommandError(`ERR invalid expire time in '${cmd}' command`);
-        return nowMs + n * 1000;
-    }
-    if (token === 'px') {
-        if (n <= 0)
-            throw new RedisCommandError(`ERR invalid expire time in '${cmd}' command`);
-        return nowMs + n;
-    }
-    if (token === 'exat')
-        return n * 1000;
-    return n; // pxat
+    const n = integerArgument(value);
+    const millis = token === 'ex' || token === 'exat' ? n * 1000n : n;
+    const at = token === 'ex' || token === 'px' ? BigInt(Math.trunc(nowMs)) + millis : millis;
+    // source: https://raw.githubusercontent.com/redis/redis/c9d29f6a918c335bc1778d9f68e521c1bbb36a0f/src/t_string.c "Overflow detected."
+    if (n <= 0n || millis > 9223372036854775807n || at > 9223372036854775807n)
+        throw new RedisCommandError(`ERR invalid expire time in '${cmd}' command`);
+    return String(at);
 }
 // ─────────────────────────────────────────────────────────────────────────────────────────────
 // COMMAND DISPATCH — fully synchronous over the snapshot (see the file header for why).
@@ -564,6 +589,107 @@ export function execOne(space, argv) {
         return dialect.exec(space, argv);
     switch (name) {
         // ── connection / server ──────────────────────────────────────────────────────────────────
+        // https://redis.io/docs/latest/commands/rpoplpush/: atomically moves the last element to the destination's head.
+        case 'RPOPLPUSH': {
+            const sourceRow = space.get(a[0]);
+            const source = asList(sourceRow);
+            asList(space.get(a[1]));
+            const value = source.pop();
+            if (value === undefined)
+                return null;
+            // source: https://raw.githubusercontent.com/redis/redis/c9d29f6a918c335bc1778d9f68e521c1bbb36a0f/src/t_list.c "listTypePush(dstobj,value,where);"
+            // A rotation rewrites the existing list, including a singleton, without deleting its key or expiry.
+            if (a[0] === a[1]) {
+                source.unshift(value);
+                space.put({ ...sourceRow, v: source }, 'list.move');
+                return value;
+            }
+            if (source.length)
+                space.put({ ...space.get(a[0]), v: source }, 'list.move');
+            else
+                space.remove(a[0], 'list.move');
+            const dest = space.get(a[1]);
+            const values = asList(dest);
+            values.unshift(value);
+            space.put({ name: a[1], kind: 'list', v: values, pexpireAt: dest?.pexpireAt ?? null }, 'list.move');
+            return value;
+        }
+        // https://redis.io/docs/latest/commands/lpos/: rank, count and maxlen apply to matching positions.
+        case 'LPOS': {
+            const values = asList(space.get(a[0]));
+            let rank = 1, count, max = values.length;
+            // source: https://raw.githubusercontent.com/redis/redis/c9d29f6a918c335bc1778d9f68e521c1bbb36a0f/src/t_list.c "COUNT can't be negative"
+            for (let i = 2; i < a.length; i += 2) {
+                const option = a[i].toUpperCase();
+                if (!['RANK', 'COUNT', 'MAXLEN'].includes(option) || i + 1 >= a.length)
+                    throw new RedisCommandError(SYNTAX);
+                let value;
+                try {
+                    value = commandInteger(a[i + 1]);
+                }
+                catch (error) {
+                    if (option === 'RANK')
+                        throw error;
+                    throw new RedisCommandError(`ERR ${option} can't be negative`);
+                }
+                if (option === 'RANK') {
+                    if (a[i + 1] === '-9223372036854775808')
+                        throw new RedisCommandError('ERR value is out of range, value must between -9223372036854775807 and 9223372036854775807');
+                    if (value === 0)
+                        throw new RedisCommandError("ERR RANK can't be zero: use 1 to start from the first match, 2 from the second ... or use negative to start from the end of the list");
+                    rank = value;
+                }
+                else {
+                    if (value < 0)
+                        throw new RedisCommandError(`ERR ${option} can't be negative`);
+                    if (option === 'COUNT')
+                        count = value;
+                    else
+                        max = value || values.length;
+                }
+            }
+            const matches = Array.from({ length: values.length }, (_, i) => i);
+            if (rank < 0)
+                matches.reverse();
+            const hits = matches.slice(0, max).filter((i) => values[i] === a[1]).slice(Math.abs(rank) - 1);
+            return count === undefined ? hits[0] ?? null : hits.slice(0, count === 0 ? undefined : count);
+        }
+        // https://redis.io/docs/latest/commands/zpopmin/: lowest score first; ties by member.
+        case 'ZPOPMIN': {
+            const row = space.get(a[0]);
+            const pairs = sortZSet(asZSet(row));
+            let count = 1;
+            // source: https://raw.githubusercontent.com/redis/redis/c9d29f6a918c335bc1778d9f68e521c1bbb36a0f/src/object.c "value is out of range, must be positive"
+            try {
+                if (a[1] !== undefined)
+                    count = commandInteger(a[1]);
+            }
+            catch {
+                throw new RedisCommandError('ERR value is out of range, must be positive');
+            }
+            if (count < 0)
+                throw new RedisCommandError('ERR value is out of range, must be positive');
+            const popped = pairs.splice(0, count);
+            if (popped.length) {
+                if (pairs.length)
+                    space.put({ ...row, v: storeZSet(sortZSet(pairs)) }, 'zset.pop');
+                else
+                    space.remove(a[0], 'zset.pop');
+            }
+            return popped.flatMap(([m, score]) => [m, fmtScore(score)]);
+        }
+        // https://redis.io/docs/latest/commands/xtrim/: exact trimming also satisfies the approximate upper bound.
+        case 'XTRIM': {
+            const row = space.get(a[0]);
+            const entries = asStream(row);
+            const spec = trimSpec(a, 1);
+            if (spec.next !== a.length)
+                throw new RedisCommandError(SYNTAX);
+            const kept = trimEntries(entries, spec);
+            if (row && kept.length !== entries.length)
+                space.put({ ...row, v: kept }, 'stream.trim');
+            return entries.length - kept.length;
+        }
         case 'PING': return a.length === 0 ? new RedisStatus('PONG') : a[0];
         case 'ECHO': return a[0];
         case 'DBSIZE': return visibleKeys(space).length;
@@ -585,9 +711,8 @@ export function execOne(space, argv) {
             return keys.length === 0 ? null : keys[0];
         }
         case 'SCAN': {
-            const cursor = toInt(a[0]);
-            if (cursor < 0)
-                throw new RedisCommandError('ERR invalid cursor');
+            // SCAN uses Redis's unsigned cursor parser, unlike signed COUNT.
+            const cursor = Number(unsignedArgument(a[0], 'ERR invalid cursor'));
             let match = null;
             let count = 10;
             let typeFilter = null;
@@ -669,7 +794,7 @@ export function execOne(space, argv) {
         case 'EXPIREAT':
         case 'PEXPIREAT': {
             const row = space.get(a[0]);
-            const n = toInt(a[1]);
+            const n = integerArgument(a[1]);
             // Redis 7.0's options (redis.io/docs/latest/commands/expire/, "Options"): NX sets only a key with no expiry, XX
             // only one with an expiry, GT only a later deadline, LT only an earlier one, a key with no expiry counting as
             // one that never expires; NX with any other, and GT with LT, are refused
@@ -679,26 +804,27 @@ export function execOne(space, argv) {
                 throw new RedisCommandError('ERR NX and XX, GT or LT options at the same time are not compatible');
             if (opts.has('GT') && opts.has('LT'))
                 throw new RedisCommandError('ERR GT and LT options at the same time are not compatible');
+            // source: https://raw.githubusercontent.com/redis/redis/c9d29f6a918c335bc1778d9f68e521c1bbb36a0f/src/expire.c "overflow by either unit conversion or basetime addition."
+            const millis = name === 'EXPIRE' || name === 'EXPIREAT' ? n * 1000n : n;
+            const deadline = name === 'EXPIRE' || name === 'PEXPIRE' ? BigInt(Math.trunc(nowMs)) + millis : millis;
+            if (millis < -9223372036854775808n || millis > 9223372036854775807n || deadline > 9223372036854775807n)
+                throw new RedisCommandError(`ERR invalid expire time in '${name.toLowerCase()}' command`);
             if (!row)
                 return 0;
-            const at = name === 'EXPIRE' ? nowMs + n * 1000
-                : name === 'PEXPIRE' ? nowMs + n
-                    : name === 'EXPIREAT' ? n * 1000
-                        : n;
             if (opts.has('NX') && row.pexpireAt !== null)
                 return 0;
             if (opts.has('XX') && row.pexpireAt === null)
                 return 0;
-            if (opts.has('GT') && (row.pexpireAt === null || at <= row.pexpireAt))
+            if (opts.has('GT') && (row.pexpireAt === null || deadline <= BigInt(row.pexpireAt)))
                 return 0;
-            if (opts.has('LT') && row.pexpireAt !== null && at >= row.pexpireAt)
+            if (opts.has('LT') && row.pexpireAt !== null && deadline >= BigInt(row.pexpireAt))
                 return 0;
             // A deadline already in the past DELETES the key, exactly as Redis does.
-            if (at <= nowMs) {
+            if (deadline <= BigInt(nowMs)) {
                 space.remove(a[0], 'key.expire_now');
                 return 1;
             }
-            space.put({ ...row, pexpireAt: at }, 'key.expire');
+            space.put({ ...row, pexpireAt: String(deadline) }, 'key.expire');
             return 1;
         }
         case 'TTL':
@@ -708,11 +834,11 @@ export function execOne(space, argv) {
                 return -2;
             if (row.pexpireAt === null)
                 return -1;
-            const remainingMs = row.pexpireAt - nowMs;
+            const remainingMs = BigInt(row.pexpireAt) - BigInt(nowMs);
             // Redis computes `(ttl+500)/1000` in integer arithmetic — round HALF-UP, not ceil. With ceil,
             // a key set `EX 10` and read 600ms later still reported 10 where the vendor says 9 (§9 round
             // 1); every earlier verify happened to land on an exact second boundary, where they agree.
-            return name === 'TTL' ? Math.round(remainingMs / 1000) : remainingMs;
+            return integerReply(name === 'TTL' ? (remainingMs + 500n) / 1000n : remainingMs);
         }
         case 'PERSIST': {
             const row = space.get(a[0]);
@@ -721,6 +847,7 @@ export function execOne(space, argv) {
             space.put({ ...row, pexpireAt: null }, 'key.persist');
             return 1;
         }
+        // source: https://redis.io/docs/latest/commands/expire/ "the associated time to live is transferred to the new key name"
         case 'RENAME':
         case 'RENAMENX': {
             const row = space.get(a[0]);
@@ -746,6 +873,7 @@ export function execOne(space, argv) {
                 space.remove(a[0], 'string.getdel');
             return v === undefined ? null : v;
         }
+        // source: https://redis.io/docs/latest/commands/getset/ "Any previous time to live associated with the key is discarded"
         case 'GETSET': {
             const old = asString(space.get(a[0]));
             space.put({ name: a[0], kind: 'string', v: a[1], pexpireAt: null }, 'string.getset');
@@ -824,6 +952,7 @@ export function execOne(space, argv) {
                 return get ? (old ?? null) : null;
             if (xx && !existing)
                 return get ? (old ?? null) : null;
+            // source: https://redis.io/docs/latest/commands/set/ "Retain the time to live associated with the key"
             space.put({ name: key, kind: 'string', v: value, pexpireAt: keepTtl ? (existing?.pexpireAt ?? null) : pexpireAt }, 'string.set');
             return get ? (old ?? null) : OK;
         }
@@ -835,10 +964,8 @@ export function execOne(space, argv) {
         }
         case 'SETEX':
         case 'PSETEX': {
-            const n = toInt(a[1]);
-            if (n <= 0)
-                throw new RedisCommandError(`ERR invalid expire time in '${name.toLowerCase()}' command`);
-            space.put({ name: a[0], kind: 'string', v: a[2], pexpireAt: nowMs + (name === 'SETEX' ? n * 1000 : n) }, 'string.setex');
+            const pexpireAt = ttlFromToken(name === 'SETEX' ? 'ex' : 'px', a[1], nowMs, name.toLowerCase());
+            space.put({ name: a[0], kind: 'string', v: a[2], pexpireAt }, 'string.setex');
             return OK;
         }
         case 'MGET': return a.map((k) => { const r = space.get(k); return r && r.kind === 'string' ? r.v : null; });
@@ -866,17 +993,17 @@ export function execOne(space, argv) {
         case 'DECR':
         case 'INCRBY':
         case 'DECRBY': {
-            const by = name === 'INCR' ? 1 : name === 'DECR' ? -1 : toInt(a[1]) * (name === 'DECRBY' ? -1 : 1);
+            const by = name === 'INCR' ? 1n : name === 'DECR' ? -1n : integerArgument(a[1]) * (name === 'DECRBY' ? -1n : 1n);
             const row = space.get(a[0]);
             const current = asString(row);
-            const next = (current === undefined ? 0 : toInt(current)) + by;
-            if (!Number.isSafeInteger(next))
+            const next = (current === undefined ? 0n : integerArgument(current)) + by;
+            if (next < -9223372036854775808n || next > 9223372036854775807n)
                 throw new RedisCommandError('ERR increment or decrement would overflow');
             // INCR PRESERVES the key's TTL (real Redis semantics). This is exactly what makes
             // @upstash/ratelimit's fixed-window script correct: the PEXPIRE is armed on the first
             // increment and every later INCRBY must leave it alone, or the window would never close.
             space.put({ name: a[0], kind: 'string', v: String(next), pexpireAt: row?.pexpireAt ?? null }, 'string.incr');
-            return next;
+            return integerReply(next);
         }
         case 'INCRBYFLOAT': {
             const row = space.get(a[0]);
@@ -947,9 +1074,10 @@ export function execOne(space, argv) {
             const pairs = asHash(row);
             const idx = pairs.findIndex(([f]) => f === a[1]);
             const current = idx < 0 ? undefined : pairs[idx][1];
-            const base = current === undefined ? 0 : (isFloat ? toFloat(current) : toInt(current));
-            const next = isFloat ? guardFloatResult(base + toFloat(a[2])) : base + toInt(a[2]);
-            if (!isFloat && !Number.isSafeInteger(next))
+            const by = isFloat ? toFloat(a[2]) : integerArgument(a[2]);
+            const base = current === undefined ? (isFloat ? 0 : 0n) : isFloat ? toFloat(current) : integerArgument(current, 'ERR hash value is not an integer');
+            const next = isFloat ? guardFloatResult(base + by) : base + by;
+            if (!isFloat && (next < -9223372036854775808n || next > 9223372036854775807n))
                 throw new RedisCommandError('ERR increment or decrement would overflow');
             const text = isFloat ? fmtScore(next) : String(next);
             if (idx < 0)
@@ -957,7 +1085,7 @@ export function execOne(space, argv) {
             else
                 pairs[idx] = [a[1], text];
             space.put({ name: a[0], kind: 'hash', v: pairs, pexpireAt: row?.pexpireAt ?? null }, 'hash.incrby');
-            return isFloat ? text : next;
+            return isFloat ? text : integerReply(next);
         }
         // ── sets ─────────────────────────────────────────────────────────────────────────────────
         case 'SADD': {
@@ -1031,11 +1159,9 @@ export function execOne(space, argv) {
         }
         case 'LPOP':
         case 'RPOP': {
+            const count = a.length >= 2 ? positiveInteger(a[1]) : null;
             const row = space.get(a[0]);
             const items = asList(row);
-            const count = a.length >= 2 ? toInt(a[1]) : null;
-            if (count !== null && count < 0)
-                throw new RedisCommandError('ERR value is out of range, must be positive');
             if (items.length === 0)
                 return null;
             const n = count === null ? 1 : count;
@@ -1073,9 +1199,9 @@ export function execOne(space, argv) {
         case 'LTRIM': {
             const row = space.get(a[0]);
             const items = asList(row);
+            const [start, stop] = normalizeRange(toInt(a[1]), toInt(a[2]), items.length);
             if (!row)
                 return OK;
-            const [start, stop] = normalizeRange(toInt(a[1]), toInt(a[2]), items.length);
             const kept = start > stop ? [] : items.slice(start, stop + 1);
             if (kept.length === 0)
                 space.remove(a[0], 'list.trim_empty');
@@ -1254,6 +1380,12 @@ export function execOne(space, argv) {
         case 'EVAL_RO':
         case 'EVALSHA':
         case 'EVALSHA_RO': {
+            // source: https://raw.githubusercontent.com/redis/redis/c9d29f6a918c335bc1778d9f68e521c1bbb36a0f/src/eval.c "Get the number of arguments that are keys"
+            const numKeys = toInt(a[1]);
+            if (numKeys < 0)
+                throw new RedisCommandError("ERR Number of keys can't be negative");
+            if (numKeys > a.length - 2)
+                throw new RedisCommandError("ERR Number of keys can't be greater than number of args");
             const bySha = name.startsWith('EVALSHA');
             let script;
             if (bySha) {
@@ -1275,11 +1407,6 @@ export function execOne(space, argv) {
                 if (!space.ctx.readOnly)
                     storeScript(space, script);
             }
-            const numKeys = toInt(a[1]);
-            if (numKeys < 0)
-                throw new RedisCommandError("ERR Number of keys can't be negative");
-            if (numKeys > a.length - 2)
-                throw new RedisCommandError("ERR Number of keys can't be greater than number of args");
             return evalScript(space, script, a.slice(2, 2 + numKeys), a.slice(2 + numKeys), name.endsWith('_RO'));
         }
         default:
@@ -1452,7 +1579,7 @@ export function zrange(space, name, a) {
         if (_rev)
             selected = selected.reverse();
         if (limit)
-            selected = limit.count < 0 ? selected.slice(limit.offset) : selected.slice(limit.offset, limit.offset + limit.count);
+            selected = limit.offset < 0 ? [] : limit.count < 0 ? selected.slice(limit.offset) : selected.slice(limit.offset, limit.offset + limit.count);
     }
     else {
         const ordered = _rev ? [...sorted].reverse() : sorted;
@@ -1463,8 +1590,8 @@ export function zrange(space, name, a) {
 }
 // ── streams ────────────────────────────────────────────────────────────────────────────────────
 export function compareStreamIds(left, right) {
-    const [lms = 0, lseq = 0] = left.split('-').map(Number);
-    const [rms = 0, rseq = 0] = right.split('-').map(Number);
+    const [lms = 0n, lseq = 0n] = left.split('-').map(BigInt);
+    const [rms = 0n, rseq = 0n] = right.split('-').map(BigInt);
     if (lms !== rms)
         return lms < rms ? -1 : 1;
     return lseq === rseq ? 0 : lseq < rseq ? -1 : 1;
@@ -1473,59 +1600,129 @@ export function parseStreamBound(raw, side) {
     if (raw === '-')
         return '0-0';
     if (raw === '+')
-        return `${Number.MAX_SAFE_INTEGER}-${Number.MAX_SAFE_INTEGER}`;
+        return '18446744073709551615-18446744073709551615';
     const bare = raw.startsWith('(') ? raw.slice(1) : raw;
     if (!/^\d+(-\d+)?$/.test(bare))
         throw new RedisCommandError('ERR Invalid stream ID specified as stream command argument');
-    return bare.includes('-') ? bare : `${bare}-${side === 'min' ? 0 : Number.MAX_SAFE_INTEGER}`;
+    return bare.includes('-') ? bare : `${bare}-${side === 'min' ? '0' : '18446744073709551615'}`;
+}
+// source: https://raw.githubusercontent.com/redis/redis/c9d29f6a918c335bc1778d9f68e521c1bbb36a0f/src/util.c "strtoull() is used instead."
+// Stream components are uint64; Redis's fallback also accepts a leading plus or zeroes.
+function streamArgument(raw, wildcard = false) {
+    const at = raw.indexOf('-');
+    const ms = at < 0 ? raw : raw.slice(0, at), seq = at < 0 ? '0' : raw.slice(at + 1);
+    const part = (v) => String(unsignedArgument(v, 'ERR Invalid stream ID specified as stream command argument'));
+    return `${part(ms)}-${wildcard && seq === '*' ? '*' : part(seq)}`;
+}
+// source: https://raw.githubusercontent.com/redis/redis/c9d29f6a918c335bc1778d9f68e521c1bbb36a0f/src/t_stream.c "The LIMIT argument must be >= 0."
+// MAXLEN/MINID use a strict unsigned threshold; LIMIT is allowed only with approximate trimming.
+function trimSpec(a, start) {
+    let i = start;
+    const strategy = a[i++].toUpperCase();
+    if (!['MAXLEN', 'MINID'].includes(strategy))
+        throw new RedisCommandError(SYNTAX);
+    const approximate = a[i] === '~';
+    if (['~', '='].includes(a[i] ?? ''))
+        i++;
+    if (i >= a.length)
+        throw new RedisCommandError(SYNTAX);
+    let threshold = a[i++];
+    if (strategy === 'MAXLEN') {
+        if (commandInteger(threshold) < 0)
+            throw new RedisCommandError('ERR The MAXLEN argument must be >= 0.');
+    }
+    else
+        threshold = streamArgument(threshold);
+    let limit = Infinity;
+    if (a[i]?.toUpperCase() === 'LIMIT') {
+        if (i + 1 >= a.length)
+            throw new RedisCommandError(SYNTAX);
+        i++;
+        limit = commandInteger(a[i++]);
+        if (limit < 0)
+            throw new RedisCommandError('ERR The LIMIT argument must be >= 0.');
+        // source: https://raw.githubusercontent.com/redis/redis/c9d29f6a918c335bc1778d9f68e521c1bbb36a0f/src/t_stream.c "syntax error, LIMIT cannot be used without the special ~ option"
+        if (!approximate)
+            throw new RedisCommandError('ERR syntax error, LIMIT cannot be used without the special ~ option');
+        if (limit === 0)
+            limit = Infinity;
+    }
+    return { strategy, threshold, limit, next: i };
+}
+function trimEntries(entries, spec) {
+    const remove = spec.strategy === 'MAXLEN' ? Math.max(0, entries.length - Number(spec.threshold)) : entries.filter(([id]) => compareStreamIds(id, parseStreamBound(spec.threshold, 'min')) < 0).length;
+    return entries.slice(Math.min(remove, spec.limit));
 }
 function xadd(space, a, nowMs) {
     let i = 1;
     let noMkStream = false;
+    let trim;
     for (; i < a.length; i++) {
         const tok = a[i].toLowerCase();
         if (tok === 'nomkstream') {
             noMkStream = true;
             continue;
         }
-        // Accepting a trim option and silently NOT trimming would be a fake success, so it is refused.
-        if (tok === 'maxlen' || tok === 'minid')
-            throw new RedisCommandError(space.ctx.dialect.unmodeled(`XADD ${tok.toUpperCase()} trimming`));
+        if (tok === 'maxlen' || tok === 'minid') {
+            if (trim)
+                throw new RedisCommandError('ERR syntax error, MAXLEN and MINID options at the same time are not compatible');
+            trim = trimSpec(a, i);
+            i = trim.next - 1;
+            continue;
+        }
         break;
     }
     const row = space.get(a[0]);
     if (!row && noMkStream)
         return null;
     const entries = asStream(row);
-    const idSpec = a[i];
+    if (row?.lastId === '18446744073709551615-18446744073709551615')
+        throw new RedisCommandError('ERR The stream has exhausted the last possible ID, unable to add more items');
+    const rawId = a[i];
+    if (rawId === undefined)
+        throw new RedisCommandError(wrongArity('xadd'));
     const fields = a.slice(i + 1);
     if (fields.length === 0 || fields.length % 2 !== 0)
         throw new RedisCommandError(wrongArity('xadd'));
+    const idSpec = rawId === '*' ? rawId : streamArgument(rawId, true);
     let id;
     if (idSpec === '*') {
         // The id's ms part is the REQUEST CLOCK (`occurredAt`), never `Date.now()`. Two entries added
         // in the same pinned millisecond get sequence 0, 1, 2 … exactly as Redis does — which is what
         // makes a stream verify reproducible.
-        const [lastMs = 0, lastSeq = 0] = (row?.lastId ?? '0-0').split('-').map(Number);
-        id = nowMs > lastMs ? `${nowMs}-0` : `${lastMs}-${lastSeq + 1}`;
+        const [lastMs = 0n, lastSeq = 0n] = (row?.lastId ?? '0-0').split('-').map(BigInt);
+        id = BigInt(nowMs) > lastMs ? `${nowMs}-0` : `${lastMs}-${lastSeq + 1n}`;
+    }
+    else if (/^(0|[1-9]\d*)-\*$/.test(idSpec) && BigInt(idSpec.split('-')[0]) <= 18446744073709551615n) {
+        const ms = BigInt(idSpec.split('-')[0]);
+        const [lastMs = 0n, lastSeq = 0n] = (row?.lastId ?? '0-0').split('-').map(BigInt);
+        if (ms < lastMs)
+            throw new RedisCommandError('ERR The ID specified in XADD is equal or smaller than the target stream top item');
+        id = `${ms}-${ms === lastMs ? lastSeq + 1n : 0n}`;
     }
     else {
         id = idSpec.includes('-') ? idSpec : `${idSpec}-0`;
-        if (!/^\d+-\d+$/.test(id))
+        if (!/^(0|[1-9]\d*)-(0|[1-9]\d*)$/.test(id) || id.split('-').some((v) => BigInt(v) > 18446744073709551615n))
             throw new RedisCommandError('ERR Invalid stream ID specified as stream command argument');
         // Compare against the RETAINED last-id, not merely the last surviving entry: Redis keeps
         // `last_id` past an XDEL, so an id that was used and then deleted stays refused forever. §9
         // round 1 found the entries-only comparison re-accepting `5-5` after `XDEL st 5-5`.
+        if (id === '0-0')
+            throw new RedisCommandError('ERR The ID specified in XADD must be greater than 0-0');
         const top = row?.lastId ?? (entries.length > 0 ? entries[entries.length - 1][0] : '0-0');
         if (compareStreamIds(id, top) <= 0) {
             throw new RedisCommandError('ERR The ID specified in XADD is equal or smaller than the target stream top item');
         }
     }
+    if (id === '0-0')
+        throw new RedisCommandError('ERR The ID specified in XADD must be greater than 0-0');
+    if (id.split('-').some((v) => BigInt(v) > 18446744073709551615n))
+        throw new RedisCommandError('ERR The stream has exhausted the last possible ID, unable to add more items');
     const pairs = [];
     for (let j = 0; j < fields.length; j += 2)
         pairs.push([fields[j], fields[j + 1]]);
     entries.push([id, pairs]);
-    space.put({ name: a[0], kind: STREAM, v: entries, pexpireAt: row?.pexpireAt ?? null, lastId: id }, 'stream.add');
+    space.put({ name: a[0], kind: STREAM, v: trim ? trimEntries(entries, trim) : entries, pexpireAt: row?.pexpireAt ?? null, lastId: id }, 'stream.add');
     return id;
 }
 // ── the script cache ───────────────────────────────────────────────────────────────────────────
@@ -1552,6 +1749,8 @@ function redisToLua(v) {
         return false; // nil bulk reply → Lua `false`
     if (typeof v === 'number' || typeof v === 'string')
         return v;
+    if (v instanceof RedisInteger)
+        return Number(v.integer);
     if (v instanceof RedisStatus) {
         const t = new LuaTable();
         t.set('ok', v.value); // status reply → Lua table {ok=…}
@@ -1659,5 +1858,5 @@ export async function execRedisRun(commands, ctx) {
     }
     const wrote = space.dirty;
     await (space.ctx.dialect.storage?.flush(space) ?? flushKeySpace(space));
-    return { items, wrote };
+    return { items, wrote, instant: nowMs };
 }

package/dist/src/redis/frames.d.ts

@@ -0,0 +1,17 @@
+import { type RedisValue } from './engine.js';
+export declare const binaryText: (b: Uint8Array) => string;
+export declare const binaryBytes: (s: string) => Uint8Array;
+export type Frame = {
+    value: any;
+    end: number;
+    error?: boolean;
+    type: string;
+};
+export declare function readResp(s: string, start?: number): Frame | undefined;
+export declare function respReply(value: RedisValue | {
+    error: string;
+} | Record<string, any>): string;
+export declare const commandFrame: (command: string[]) => Uint8Array;
+export declare function inlineCommand(line: string): string[];
+/** Carry RESP integer/status tags across an internal JSON request without losing int64 bytes. */
+export declare function wireValue(value: any): any;