@naturalcycles/redis-lib 4.5.0 → 4.7.0

package/dist/redisClient.d.ts

@@ -13,7 +13,7 @@ export interface CommonClient extends AsyncDisposable {
 export interface RedisClientCfg {
     redisOptions?: RedisOptions;
     /**
-     * Defaults to console.
+     * Defaults to consoleLogger.
      */
     logger?: CommonLogger;
 }
@@ -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,5 @@
+import { _assert } from '@naturalcycles/js-lib/error';
+import { consoleLogger } from '@naturalcycles/js-lib/log';
 import { _stringMapEntries } from '@naturalcycles/js-lib/types';
 import { Pipeline } from '@naturalcycles/nodejs-lib/stream';
 /**
@@ -11,7 +13,7 @@ import { Pipeline } from '@naturalcycles/nodejs-lib/stream';
 export class RedisClient {
     constructor(cfg = {}) {
         this.cfg = {
-            logger: console,
+            logger: consoleLogger,
             ...cfg,
             redisOptions: {
                 showFriendlyErrorStack: true,
@@ -50,7 +52,7 @@ export class RedisClient {
     async disconnect() {
         const redis = await this.redis();
         this.log('redis: quit...');
-        this.log(`redis: quit`, await redis.quit());
+        this.log({ msg: `redis: quit`, result: await redis.quit() });
         this.connected = false;
     }
     async [Symbol.asyncDispose]() {
@@ -149,10 +151,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 +194,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);
@@ -240,7 +294,7 @@ export class RedisClient {
         await fn(pipeline);
         await pipeline.exec();
     }
-    log(...args) {
-        this.cfg.logger.log(...args);
+    log(input) {
+        this.cfg.logger.log(input);
     }
 }

package/package.json

@@ -9,9 +9,9 @@
     "tslib": "^2"
   },
   "devDependencies": {
+    "@naturalcycles/dev-lib": "20.64.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.7.0",
   "description": "Redis implementation of CommonKeyValueDB interface",
   "author": "Natural Cycles Team",
   "license": "MIT",

package/src/redisClient.ts

@@ -1,4 +1,6 @@
-import type { CommonLogger } from '@naturalcycles/js-lib/log'
+import { _assert } from '@naturalcycles/js-lib/error'
+import { consoleLogger } from '@naturalcycles/js-lib/log'
+import type { CommonLogger, LogInput } from '@naturalcycles/js-lib/log'
 import type {
   AnyObject,
   NullableBuffer,
@@ -24,7 +26,7 @@ export interface RedisClientCfg {
   redisOptions?: RedisOptions
 
   /**
-   * Defaults to console.
+   * Defaults to consoleLogger.
    */
   logger?: CommonLogger
 }
@@ -40,7 +42,7 @@ export interface RedisClientCfg {
 export class RedisClient implements CommonClient {
   constructor(cfg: RedisClientCfg = {}) {
     this.cfg = {
-      logger: console,
+      logger: consoleLogger,
       ...cfg,
       redisOptions: {
         showFriendlyErrorStack: true,
@@ -90,7 +92,7 @@ export class RedisClient implements CommonClient {
   async disconnect(): Promise<void> {
     const redis = await this.redis()
     this.log('redis: quit...')
-    this.log(`redis: quit`, await redis.quit())
+    this.log({ msg: `redis: quit`, result: await redis.quit() })
     this.connected = false
   }
 
@@ -221,11 +223,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 +276,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)
@@ -338,7 +404,7 @@ export class RedisClient implements CommonClient {
     await pipeline.exec()
   }
 
-  private log(...args: any[]): void {
-    this.cfg.logger.log(...args)
+  private log(input: LogInput): void {
+    this.cfg.logger.log(input)
   }
 }