@jusbid/redis 1.0.0

package/index.js

@@ -0,0 +1,893 @@
+const { createClient } = require('redis');
+const { logger } = require('@jusbid/logger');
+
+const redisOptions = {};
+
+// Build Redis connection options dynamically
+if (process.env.REDIS_URL) {
+  redisOptions.url = process.env.REDIS_URL;
+} else {
+  const protocol = process.env.REDIS_TLS === 'true' ? 'rediss' : 'redis';
+  const host = process.env.REDIS_HOST || 'localhost';
+  const port = process.env.REDIS_PORT || 6379;
+  const username = process.env.REDIS_USERNAME || '';
+  const password = process.env.REDIS_PASSWORD || '';
+
+  if (password) {
+    redisOptions.url = `${protocol}://${username ? `${encodeURIComponent(username)}:` : ''}${encodeURIComponent(password)}@${host}:${port}`;
+  } else {
+    redisOptions.url = `${protocol}://${host}:${port}`;
+  }
+}
+
+// Enable secure TLS settings for enterprise Redis cloud deployments (e.g. AWS, Upstash)
+redisOptions.socket = {
+  reconnectStrategy: (retries) => {
+    const delay = Math.min(retries * 100, 10000);
+    logger.warn(`Redis client disconnected. Retrying connection in ${delay}ms... (attempt ${retries})`);
+    return delay;
+  },
+};
+
+if (process.env.REDIS_TLS === 'true') {
+  redisOptions.socket.tls = true;
+  if (process.env.REDIS_REJECT_UNAUTHORIZED === 'false') {
+    redisOptions.socket.rejectUnauthorized = false;
+  }
+}
+
+const rawRedisClient = createClient(redisOptions);
+
+rawRedisClient.on('error', (err) => {
+  logger.error('Redis client error occurred', { error: err.message, stack: err.stack });
+});
+
+rawRedisClient.on('connect', () => {
+  logger.info('Connecting to Redis server...');
+});
+
+rawRedisClient.on('ready', () => {
+  logger.info('Redis client connected and ready.');
+});
+
+// Lazy connection management
+let isConnected = false;
+let connectingPromise = null;
+
+const ensureConnected = async () => {
+  if (rawRedisClient.isOpen && isConnected) {
+    return;
+  }
+
+  if (connectingPromise) {
+    return connectingPromise;
+  }
+
+  connectingPromise = (async () => {
+    try {
+      await rawRedisClient.connect();
+      isConnected = true;
+    } catch (err) {
+      logger.error('Failed to initialize Redis connection', { error: err.message });
+      isConnected = false;
+      throw err;
+    } finally {
+      connectingPromise = null;
+    }
+  })();
+
+  return connectingPromise;
+};
+
+// Create a proxy wrapper to dynamically connect on the first method invocation
+const redisClient = new Proxy(rawRedisClient, {
+  get(target, prop) {
+    const origValue = target[prop];
+    if (typeof origValue === 'function') {
+      return async (...args) => {
+        // Exclude listener attachments, connection initiation, and closing from trigger
+        if (prop !== 'connect' && prop !== 'on' && prop !== 'off' && prop !== 'once' && prop !== 'quit') {
+          await ensureConnected();
+        }
+        return origValue.apply(target, args);
+      };
+    }
+    return origValue;
+  }
+});
+
+const get = async (key) => {
+  try {
+    const data = await redisClient.get(key);
+    return data ? JSON.parse(data) : null;
+  } catch (error) {
+    logger.error(`Redis GET error for key ${key}`, { error: error.message });
+    return null;
+  }
+};
+
+const sIsMember = async (key, action) => {
+  try {
+    const data = await redisClient.sIsMember(key, action);
+    return data ? JSON.parse(data) : null;
+  } catch (error) {
+    logger.error(`Redis sIsMember error for key ${key}`, { error: error.message });
+    return null;
+  }
+};
+
+const sAdd = async (key, action) => {
+  try {
+    await redisClient.sAdd(key, action);
+    return true;
+  }
+  catch (error) {
+    logger.error(`Redis sAdd error for key ${key}`, { error: error.message });
+    return false;
+  }
+}
+
+const sMembers = async (key) => {
+  try {
+    await redisClient.sMembers(key);
+    return true;
+  }
+  catch (error) {
+    logger.error(`Redis sAdd error for key ${key}`, { error: error.message });
+    return false;
+  }
+}
+
+const set = async (key, value, ttlSeconds = null) => {
+  try {
+    const stringified = JSON.stringify(value);
+    if (ttlSeconds) {
+      await redisClient.set(key, stringified, { EX: ttlSeconds });
+    } else {
+      await redisClient.set(key, stringified);
+    }
+    return true;
+  } catch (error) {
+    logger.error(`Redis SET error for key ${key}`, { error: error.message });
+    return false;
+  }
+};
+
+const del = async (key) => {
+  try {
+    await redisClient.del(key);
+    return true;
+  } catch (error) {
+    logger.error(`Redis DEL error for key ${key}`, { error: error.message });
+    return false;
+  }
+};
+
+const exists = async (key) => {
+  try {
+    return (await redisClient.exists(key)) === 1;
+  } catch (error) {
+    logger.error(`Redis EXISTS error for key ${key}`, { error: error.message });
+    return false;
+  }
+};
+
+const type = async (key) => {
+  try {
+    return await redisClient.type(key);
+  }
+  catch (error) {
+    logger.error(`Redis type error for key ${key}`, { error: error.message });
+    return null;
+  }
+}
+
+const hSet = async (key, value) => {
+  try {
+    await redisClient.hSet(key, value);
+    return true;
+  }
+  catch (error) {
+    logger.error(`Redis hSet error for key ${key}`, { error: error.message });
+    return false;
+  }
+}
+
+const hGet = async (key, field) => {
+  try {
+    const data = await redisClient.hGet(key, field);
+    return data ? JSON.parse(data) : null;
+  } catch (error) {
+    logger.error(`Redis hGet error for key ${key}`, { error: error.message });
+    return null;
+  }
+}
+
+const hGetAll = async (key) => {
+  try {
+    const data = await redisClient.hGetAll(key);
+    return data ? JSON.parse(data) : null;
+  } catch (error) {
+    logger.error(`Redis hGet error for key ${key}`, { error: error.message });
+    return null;
+  }
+}
+// ==============================
+// Redis Streams
+// ==============================
+
+/**
+ * Add message to Redis Stream
+ *
+ * @param {string} stream
+ * @param {object} data
+ * @returns {Promise<string>}
+ */
+
+// ==============================
+// Redis Streams
+// ==============================
+
+/**
+ * Add message to Redis Stream
+ *
+ * @param {string} stream
+ * @param {object} data
+ * @returns {Promise<string>}
+ */
+const xAdd = async (stream, data) => {
+  try {
+    const fields = {};
+
+    for (const [key, value] of Object.entries(data)) {
+      fields[key] =
+        typeof value === 'string'
+          ? value
+          : JSON.stringify(value);
+    }
+
+    return await redisClient.xAdd(
+      stream,
+      '*',
+      fields
+    );
+  } catch (error) {
+    logger.error('Redis XADD error', {
+      stream,
+      error: error.message,
+      stack: error.stack,
+    });
+
+    throw error;
+  }
+};
+
+
+/**
+ * Create consumer group
+ *
+ * If group already exists, that's fine.
+ *
+ * @param {string} stream
+ * @param {string} group
+ * @param {string} startId
+ */
+const xGroupCreate = async (
+  stream,
+  group,
+  startId = '0'
+) => {
+  try {
+    await redisClient.xGroupCreate(
+      stream,
+      group,
+      startId,
+      {
+        MKSTREAM: true,
+      }
+    );
+
+    return true;
+  } catch (error) {
+
+    if (
+      error?.message?.includes('BUSYGROUP')
+    ) {
+      return true;
+    }
+
+    logger.error('Redis XGROUP CREATE error', {
+      stream,
+      group,
+      error: error.message,
+      stack: error.stack,
+    });
+
+    throw error;
+  }
+};
+
+
+/**
+ * Read messages from consumer group
+ *
+ * `>` = only new messages that have never
+ * been delivered to this consumer group.
+ *
+ * @param {string} stream
+ * @param {string} group
+ * @param {string} consumer
+ * @param {number} count
+ * @param {number} block
+ */
+const xReadGroup = async (...args) => {
+  try {
+    let stream;
+    let group;
+    let consumer;
+    let count;
+    let block;
+
+    // OLD Redis command syntax:
+    // XREADGROUP GROUP group consumer COUNT count BLOCK block STREAMS stream >
+    if (args[0] === 'GROUP') {
+      group = args[1];
+      consumer = args[2];
+
+      const countIndex = args.indexOf('COUNT');
+      const blockIndex = args.indexOf('BLOCK');
+      const streamsIndex = args.indexOf('STREAMS');
+
+      count = Number(args[countIndex + 1]);
+      block = Number(args[blockIndex + 1]);
+      stream = args[streamsIndex + 1];
+
+    } else {
+      // New/internal syntax:
+      // stream, group, consumer, count, block
+      [
+        stream,
+        group,
+        consumer,
+        count,
+        block
+      ] = args;
+
+      count = Number(count);
+      block = Number(block);
+    }
+
+    if (!stream) {
+      throw new TypeError('Redis XREADGROUP: stream is required');
+    }
+
+    if (!group) {
+      throw new TypeError('Redis XREADGROUP: group is required');
+    }
+
+    if (!consumer) {
+      throw new TypeError('Redis XREADGROUP: consumer is required');
+    }
+
+    if (!Number.isInteger(count) || count <= 0) {
+      throw new TypeError(`Invalid count: ${count}`);
+    }
+
+    if (!Number.isInteger(block) || block < 0) {
+      throw new TypeError(`Invalid block: ${block}`);
+    }
+
+    return await redisClient.xReadGroup(
+      group,
+      consumer,
+      [
+        {
+          key: stream,
+          id: '>',
+        },
+      ],
+      {
+        COUNT: count,
+        BLOCK: block,
+      }
+    );
+
+  } catch (error) {
+    logger.error('Redis XREADGROUP error', {
+      args,
+      error: error.message,
+      stack: error.stack,
+    });
+
+    throw error;
+  }
+};
+
+
+/**
+ * Acknowledge messages
+ *
+ * @param {string} stream
+ * @param {string} group
+ * @param {string|string[]} ids
+ */
+const xAck = async (stream, group, ...ids) => {
+  try {
+    const messageIds = ids.flat();
+
+    if (messageIds.length === 0) {
+      return 0;
+    }
+
+    return await redisClient.xAck(
+      stream,
+      group,
+      messageIds
+    );
+
+  } catch (error) {
+    logger.error('Redis XACK error', {
+      stream,
+      group,
+      ids,
+      error: error.message,
+      stack: error.stack,
+    });
+
+    throw error;
+  }
+};
+
+/**
+ * Get pending summary
+ *
+ * IMPORTANT:
+ * This does NOT return an array of messages.
+ *
+ * Example:
+ *
+ * {
+ *   pending: 5,
+ *   firstId: '123-0',
+ *   lastId: '456-0',
+ *   consumers: [...]
+ * }
+ */
+const xPending = async (...args) => {
+  try {
+    let stream;
+    let group;
+    let minIdleTime;
+    let start = '-';
+    let end = '+';
+    let count = 10;
+
+    // Backward-compatible old syntax:
+    //
+    // xPending(
+    //   stream,
+    //   group,
+    //   'IDLE',
+    //   minIdleTime,
+    //   '-',
+    //   '+',
+    //   count
+    // )
+    if (args[2] === 'IDLE') {
+      stream = args[0];
+      group = args[1];
+      minIdleTime = Number(args[3]);
+      start = args[4] || '-';
+      end = args[5] || '+';
+      count = Number(args[6] ?? 10);
+    } else {
+      // New syntax:
+      //
+      // xPending(
+      //   stream,
+      //   group,
+      //   minIdleTime,
+      //   start,
+      //   end,
+      //   count
+      // )
+      stream = args[0];
+      group = args[1];
+      minIdleTime = Number(args[2]);
+      start = args[3] || '-';
+      end = args[4] || '+';
+      count = Number(args[5] ?? 10);
+    }
+
+    if (!stream) {
+      throw new TypeError('Redis XPENDING: stream is required');
+    }
+
+    if (!group) {
+      throw new TypeError('Redis XPENDING: group is required');
+    }
+
+    if (!Number.isInteger(minIdleTime) || minIdleTime < 0) {
+      throw new TypeError(`Invalid minIdleTime: ${minIdleTime}`);
+    }
+
+    if (!Number.isInteger(count) || count <= 0) {
+      throw new TypeError(`Invalid count: ${count}`);
+    }
+
+    const result = await redisClient.xPending(
+      stream,
+      group,
+      {
+        IDLE: minIdleTime,
+        START: start,
+        END: end,
+        COUNT: count,
+      }
+    );
+
+    /*
+     * node-redis may return:
+     *
+     * [
+     *   {
+     *     id: '123-0',
+     *     owner: 'consumer-1',
+     *     millisecondsSinceLastDelivery: 40000,
+     *     deliveriesCounter: 1
+     *   }
+     * ]
+     *
+     * Normalize it to an array for existing consumers.
+     */
+
+    if (Array.isArray(result)) {
+      return result;
+    }
+
+    // Some node-redis versions / command overloads can return
+    // an object-shaped result. Normalize it.
+    if (result && typeof result === 'object') {
+      if (Array.isArray(result.entries)) {
+        return result.entries;
+      }
+
+      if (Array.isArray(result.pending)) {
+        return result.pending;
+      }
+
+      // If it's a single pending entry, normalize it.
+      if (
+        result.id &&
+        (
+          result.owner ||
+          result.consumer
+        )
+      ) {
+        return [result];
+      }
+    }
+
+    // Nothing pending.
+    return [];
+
+  } catch (error) {
+    logger.error('Redis XPENDING RANGE error', {
+      args,
+      error: error.message,
+      stack: error.stack,
+    });
+
+    throw error;
+  }
+};
+
+/**
+ * Reclaim stale pending messages
+ *
+ * XAUTOCLAIM returns:
+ *
+ * [
+ *   nextStartId,
+ *   messages,
+ *   deletedMessageIds
+ * ]
+ *
+ * depending on node-redis version.
+ */
+const xAutoClaim = async (
+  stream,
+  group,
+  consumer,
+  minIdleTime = 30000,
+  startId = '0-0',
+  count = 10
+) => {
+  try {
+    minIdleTime = Number(minIdleTime);
+    count = Number(count);
+
+    if (!Number.isInteger(minIdleTime) || minIdleTime < 0) {
+      throw new TypeError(
+        `Invalid minIdleTime: ${minIdleTime}`
+      );
+    }
+
+    if (!Number.isInteger(count) || count <= 0) {
+      throw new TypeError(
+        `Invalid count: ${count}`
+      );
+    }
+
+    return await redisClient.xAutoClaim(
+      stream,
+      group,
+      consumer,
+      minIdleTime,
+      startId,
+      {
+        COUNT: count,
+      }
+    );
+
+  } catch (error) {
+    logger.error('Redis XAUTOCLAIM error', {
+      stream,
+      group,
+      consumer,
+      minIdleTime,
+      startId,
+      count,
+      error: error.message,
+      stack: error.stack,
+    });
+
+    throw error;
+  }
+};
+
+
+/**
+ * Delete messages from stream
+ *
+ * Usually DON'T call this after XACK.
+ */
+const xDel = async (
+  stream,
+  ids
+) => {
+  try {
+
+    if (!ids) {
+      return 0;
+    }
+
+    const messageIds = Array.isArray(ids)
+      ? ids
+      : [ids];
+
+    if (messageIds.length === 0) {
+      return 0;
+    }
+
+    return await redisClient.xDel(
+      stream,
+      messageIds
+    );
+
+  } catch (error) {
+
+    logger.error('Redis XDEL error', {
+      stream,
+      ids,
+      error: error.message,
+      stack: error.stack,
+    });
+
+    throw error;
+  }
+};
+
+
+/**
+ * Trim stream
+ */
+const xTrim = async (
+  stream,
+  maxLen
+) => {
+  try {
+
+    maxLen = Number(maxLen);
+
+    if (!Number.isInteger(maxLen) || maxLen <= 0) {
+      throw new TypeError(
+        `Invalid maxLen: ${maxLen}`
+      );
+    }
+
+    return await redisClient.xTrim(
+      stream,
+      'MAXLEN',
+      maxLen,
+      {
+        strategyModifier: '~',
+      }
+    );
+
+  } catch (error) {
+
+    logger.error('Redis XTRIM error', {
+      stream,
+      maxLen,
+      error: error.message,
+      stack: error.stack,
+    });
+
+    throw error;
+  }
+};
+
+
+const xReadGroupNew = async (...args) => {
+  try {
+    let stream;
+    let group;
+    let consumer;
+    let count;
+    let block;
+
+    // Existing caller format:
+    //
+    // GROUP group consumer
+    // COUNT count
+    // BLOCK block
+    // STREAMS stream >
+    if (args[0] === 'GROUP') {
+      group = args[1];
+      consumer = args[2];
+
+      const countIndex = args.indexOf('COUNT');
+      const blockIndex = args.indexOf('BLOCK');
+      const streamsIndex = args.indexOf('STREAMS');
+
+      count = Number(args[countIndex + 1]);
+      block = Number(args[blockIndex + 1]);
+      stream = args[streamsIndex + 1];
+    } else {
+      stream = args[0];
+      group = args[1];
+      consumer = args[2];
+      count = Number(args[3]);
+      block = Number(args[4]);
+    }
+
+    if (!stream) {
+      throw new TypeError('XREADGROUP: stream is required');
+    }
+
+    if (!group) {
+      throw new TypeError('XREADGROUP: group is required');
+    }
+
+    if (!consumer) {
+      throw new TypeError('XREADGROUP: consumer is required');
+    }
+
+    if (!Number.isInteger(count) || count <= 0) {
+      throw new TypeError(`Invalid count: ${count}`);
+    }
+
+    if (!Number.isInteger(block) || block < 0) {
+      throw new TypeError(`Invalid block: ${block}`);
+    }
+
+    const result = await redisClient.xReadGroup(
+      group,
+      consumer,
+      [
+        {
+          key: stream,
+          id: '>',
+        },
+      ],
+      {
+        COUNT: count,
+        BLOCK: block,
+      }
+    );
+
+    if (!result || result.length === 0) {
+      return null;
+    }
+
+    /*
+     * node-redis:
+     *
+     * [
+     *   {
+     *     name: 'activity-log',
+     *     messages: [
+     *       {
+     *         id: '123-0',
+     *         message: {
+     *           payload: '...',
+     *           event_id: '...'
+     *         }
+     *       }
+     *     ]
+     *   }
+     * ]
+     *
+     * Existing consumer expects:
+     *
+     * [
+     *   [
+     *     'activity-log',
+     *     [
+     *       [
+     *         '123-0',
+     *         ['payload', '...']
+     *       ]
+     *     ]
+     *   ]
+     * ]
+     */
+
+    return result.map((streamResult) => {
+      const entries = (streamResult.messages || []).map((message) => {
+        const fields = [];
+
+        for (const [key, value] of Object.entries(message.message || {})) {
+          fields.push(key);
+          fields.push(value);
+        }
+
+        return [
+          message.id,
+          fields,
+        ];
+      });
+
+      return [
+        streamResult.name,
+        entries,
+      ];
+    });
+
+  } catch (error) {
+    logger.error('Redis XREADGROUP error', {
+      args,
+      error: error.message,
+      stack: error.stack,
+    });
+
+    throw error;
+  }
+};
+
+module.exports = {
+  redisClient,
+  get,
+  set,
+  del,
+  exists,
+  sIsMember,
+  sAdd,
+  sMembers,
+  type,
+  hSet,
+  hGet,
+  hGetAll,
+
+  // Redis Streams
+  xAdd,
+  xGroupCreate,
+  xReadGroup,
+  xAck,
+  xPending,
+  xAutoClaim,
+  xDel,
+  xTrim,
+  xReadGroupNew
+};

package/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@jusbid/redis",
+  "version": "1.0.0",
+  "main": "index.js",
+  "private": false,
+  "dependencies": {
+    "redis": "^4.6.13",
+    "@jusbid/logger": "1.0.0"
+  }
+}