@naturalcycles/redis-lib 4.5.0 → 4.6.0

package/dist/redisClient.d.ts

@@ -53,8 +53,28 @@ export declare class RedisClient implements CommonClient {
     hsetWithTTL(_key: string, _value: AnyObject, _expireAt: UnixTimestamp): Promise<void>;
     mset(obj: Record<string, string | number>): Promise<void>;
     msetBuffer(obj: Record<string, Buffer>): Promise<void>;
+    /**
+     * For counters that are supposed to expire, use {@link incrWithTTL} instead.
+     */
     incr(key: string, by?: number): Promise<number>;
+    /**
+     * Increments the key and guarantees it has an expiry, in a single transaction.
+     *
+     * Returns the new value.
+     *
+     * Requires Redis 7.0+
+     */
+    incrWithTTL(key: string, expireAt: UnixTimestamp, by?: number): Promise<number>;
+    /**
+     * For counters that are supposed to expire, use {@link incrBatchWithTTL} instead.
+     */
     incrBatch(incrementTuples: [string, number][]): Promise<[string, number][]>;
+    /**
+     * Batch version of {@link incrWithTTL}, all increments and expiries in a single transaction.
+     *
+     * Requires Redis 7.0+
+     */
+    incrBatchWithTTL(incrementTuples: [string, number][], expireAt: UnixTimestamp): Promise<[string, number][]>;
     ttl(key: string): Promise<number>;
     dropTable(table: string): Promise<void>;
     clearAll(): Promise<void>;

package/dist/redisClient.js

@@ -1,3 +1,4 @@
+import { _assert } from '@naturalcycles/js-lib/error';
 import { _stringMapEntries } from '@naturalcycles/js-lib/types';
 import { Pipeline } from '@naturalcycles/nodejs-lib/stream';
 /**
@@ -149,10 +150,37 @@ export class RedisClient {
         const redis = await this.redis();
         await redis.mset(obj);
     }
+    /**
+     * For counters that are supposed to expire, use {@link incrWithTTL} instead.
+     */
     async incr(key, by = 1) {
         const redis = await this.redis();
         return await redis.incrby(key, by);
     }
+    /**
+     * Increments the key and guarantees it has an expiry, in a single transaction.
+     *
+     * Returns the new value.
+     *
+     * Requires Redis 7.0+
+     */
+    async incrWithTTL(key, expireAt, by = 1) {
+        const redis = await this.redis();
+        const results = await redis.multi().incrby(key, by).expireat(key, expireAt, 'NX').exec();
+        const result = results?.[0];
+        _assert(result, `redis: incrWithTTL transaction returned no result, key: ${key}`);
+        // Redis does not roll back, so a failed EXPIREAT leaves the key incremented and without an
+        // expiry. It self-heals on the next successful call, as EXPIREAT NX applies to a TTL-less key.
+        for (const [err] of results) {
+            if (err)
+                throw err;
+        }
+        const [, value] = result;
+        return value;
+    }
+    /**
+     * For counters that are supposed to expire, use {@link incrBatchWithTTL} instead.
+     */
     async incrBatch(incrementTuples) {
         const results = {};
         await this.withPipeline(async (pipeline) => {
@@ -165,6 +193,31 @@ export class RedisClient {
         const validResults = _stringMapEntries(results).filter(([_, v]) => v !== undefined);
         return validResults;
     }
+    /**
+     * Batch version of {@link incrWithTTL}, all increments and expiries in a single transaction.
+     *
+     * Requires Redis 7.0+
+     */
+    async incrBatchWithTTL(incrementTuples, expireAt) {
+        const redis = await this.redis();
+        const multi = redis.multi();
+        for (const [key, increment] of incrementTuples) {
+            multi.incrby(key, increment);
+            multi.expireat(key, expireAt, 'NX');
+        }
+        // 2 commands are queued per key, so the increments sit at the even indexes
+        const results = await multi.exec();
+        const expectedLength = incrementTuples.length * 2;
+        _assert(results?.length === expectedLength, `redis: incrBatchWithTTL expected ${expectedLength} results, got ${results?.length}`);
+        for (const [err] of results) {
+            if (err)
+                throw err;
+        }
+        return incrementTuples.map(([key], i) => {
+            const [, newValue] = results[i * 2];
+            return [key, newValue];
+        });
+    }
     async ttl(key) {
         const redis = await this.redis();
         return await redis.ttl(key);

package/package.json

@@ -9,9 +9,9 @@
     "tslib": "^2"
   },
   "devDependencies": {
+    "@naturalcycles/dev-lib": "0.0.0",
     "@types/node": "^26",
-    "typescript": "^7",
-    "@naturalcycles/dev-lib": "0.0.0"
+    "typescript": "^7"
   },
   "exports": {
     ".": "./dist/index.js"
@@ -38,7 +38,7 @@
   "engines": {
     "node": ">=24.10.0"
   },
-  "version": "4.5.0",
+  "version": "4.6.0",
   "description": "Redis implementation of CommonKeyValueDB interface",
   "author": "Natural Cycles Team",
   "license": "MIT",

package/src/redisClient.ts

@@ -1,3 +1,4 @@
+import { _assert } from '@naturalcycles/js-lib/error'
 import type { CommonLogger } from '@naturalcycles/js-lib/log'
 import type {
   AnyObject,
@@ -221,11 +222,40 @@ export class RedisClient implements CommonClient {
     await redis.mset(obj)
   }
 
+  /**
+   * For counters that are supposed to expire, use {@link incrWithTTL} instead.
+   */
   async incr(key: string, by = 1): Promise<number> {
     const redis = await this.redis()
     return await redis.incrby(key, by)
   }
 
+  /**
+   * Increments the key and guarantees it has an expiry, in a single transaction.
+   *
+   * Returns the new value.
+   *
+   * Requires Redis 7.0+
+   */
+  async incrWithTTL(key: string, expireAt: UnixTimestamp, by = 1): Promise<number> {
+    const redis = await this.redis()
+    const results = await redis.multi().incrby(key, by).expireat(key, expireAt, 'NX').exec()
+    const result = results?.[0]
+    _assert(result, `redis: incrWithTTL transaction returned no result, key: ${key}`)
+
+    // Redis does not roll back, so a failed EXPIREAT leaves the key incremented and without an
+    // expiry. It self-heals on the next successful call, as EXPIREAT NX applies to a TTL-less key.
+    for (const [err] of results) {
+      if (err) throw err
+    }
+
+    const [, value] = result
+    return value as number
+  }
+
+  /**
+   * For counters that are supposed to expire, use {@link incrBatchWithTTL} instead.
+   */
   async incrBatch(incrementTuples: [string, number][]): Promise<[string, number][]> {
     const results: StringMap<number | undefined> = {}
 
@@ -245,6 +275,41 @@ export class RedisClient implements CommonClient {
     return validResults
   }
 
+  /**
+   * Batch version of {@link incrWithTTL}, all increments and expiries in a single transaction.
+   *
+   * Requires Redis 7.0+
+   */
+  async incrBatchWithTTL(
+    incrementTuples: [string, number][],
+    expireAt: UnixTimestamp,
+  ): Promise<[string, number][]> {
+    const redis = await this.redis()
+    const multi = redis.multi()
+
+    for (const [key, increment] of incrementTuples) {
+      multi.incrby(key, increment)
+      multi.expireat(key, expireAt, 'NX')
+    }
+
+    // 2 commands are queued per key, so the increments sit at the even indexes
+    const results = await multi.exec()
+    const expectedLength = incrementTuples.length * 2
+    _assert(
+      results?.length === expectedLength,
+      `redis: incrBatchWithTTL expected ${expectedLength} results, got ${results?.length}`,
+    )
+
+    for (const [err] of results) {
+      if (err) throw err
+    }
+
+    return incrementTuples.map(([key], i) => {
+      const [, newValue] = results[i * 2]!
+      return [key, newValue as number]
+    })
+  }
+
   async ttl(key: string): Promise<number> {
     const redis = await this.redis()
     return await redis.ttl(key)