Redis Script Utility for Node.js

Common errors

• ERR wrong number of arguments for 'eval' command

  cause The `numKeys` parameter passed to your generated script function does not match the actual number of keys used in the Lua script's `KEYS` array.
  fix Review your Lua script to count how many `KEYS[n]` variables are accessed, and ensure the `numKeys` argument exactly matches this count when calling your script function.

• TypeError: Cannot read properties of undefined (reading 'eval')

  cause The `redis` or `ioredis` client object passed to `createScript` is `undefined`, `null`, or an improperly initialized object lacking the `eval` or `evalsha` methods.
  fix Verify that you are passing a valid, connected instance of either `node-redis`'s client or `ioredis`'s client to the `opts` object for `createScript`.

Warnings

• gotcha The `numKeys` argument passed to the generated script function is critical and directly corresponds to Redis's `EVAL` command. Incorrectly specifying the number of keys will lead to runtime errors in Redis.
  Fix: Always ensure the `numKeys` parameter accurately reflects the number of elements in your `KEYS` array within the Lua script.
• breaking This library requires Node.js version 10 or higher. Older Node.js versions are not supported.
  Fix: Upgrade your Node.js environment to version 10 or newer to ensure compatibility and proper function execution.
• gotcha The `redis` or `ioredis` client provided to `createScript` must be a properly initialized and connected client instance. Passing an unconnected or invalid client will result in execution failures.
  Fix: Ensure your Redis client (either `node-redis` or `ioredis`) is fully connected and ready before passing it to `createScript`. For `node-redis` v4+, remember to call `.connect()`.

Install

• npm install node-redis-script npm
• yarn add node-redis-script yarn
• pnpm add node-redis-script pnpm

Imports

• createScript
  wrong:

  const createScript = require('node-redis-script').createScript;

  correct:

  import { createScript } from 'node-redis-script';

  ESM import for `createScript`. While the README shows CommonJS, modern Node.js environments typically use ESM. The library ships with CJS for Node 10+.
• createScript
  wrong:

  import { createScript } from 'node-redis-script';

  correct:

  const { createScript } = require('node-redis-script');

  CommonJS import for `createScript`, matching the documentation example. This is suitable for older Node.js versions or CJS modules.
• * as RedisScript
  wrong:

  import RedisScript from 'node-redis-script';

  correct:

  import * as RedisScript from 'node-redis-script';

  Importing all named exports as a namespace, useful if multiple utilities were exposed. There is no default export.

Quickstart

This example demonstrates how to initialize a Redis client, define a Lua script, create a script function using `createScript`, and then execute it with specific keys and arguments. It showcases a common pattern for an atomic increment-and-expire operation.

import { createClient } from 'redis'; // or from 'ioredis'
import { createScript } from 'node-redis-script';

async function runRedisScript() {
  const redisClient = createClient();
  redisClient.on('error', (err) => console.log('Redis Client Error', err));
  await redisClient.connect();

  const incrbyExSrc = `
    local current
    current = redis.call('incrby',KEYS[1],ARGV[1])
    redis.call('expire',KEYS[1],ARGV[2]);
    return current
  `;

  // give it a redis client and script source
  const opts = { redis: redisClient }; // For ioredis: { ioredis: ioredisClient }
  const incrbyEx = createScript(opts, incrbyExSrc);

  // redis requires you to tell it how many keys to expect
  const numKeys = 1;
  const key = 'myCounterKey';
  const incr = 5;
  const ex = 60; // expire in 60 seconds

  const result = await incrbyEx(numKeys, key, incr, ex);
  console.log(`Current value of ${key}: ${result}`); // Should print 5 the first time, 10 the second, etc.

  await redisClient.disconnect();
}

runRedisScript().catch(console.error);