redis-evalsha

library1.1.1jsnpmunverified

Shavaluator wrapper around Redis EVALSHA/EVAL for efficient Lua script execution. Version 1.1.1 is latest (stable). Provides a simple API to pre-register Lua scripts with SHA-1 hashes, automatically falling back from EVALSHA to EVAL if the script is not cached on the Redis server. Avoids recomputing SHA-1 on every call (unlike node-redis's built-in eval). Designed for the node-redis client (mranney/node-redis). Lightweight: zero runtime dependencies. No TypeScript types.

database

npm install redis-evalsha

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REDIS-EVALSHA

redis-evalsha

databasejavascriptv1.1.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Shavaluator

✓ const Shavaluator = require('redis-evalsha')

✗ import Shavaluator from 'redis-evalsha'

This package is CommonJS-only and does not export an ESM module. Use require() to load it.

default export (class constructor)

✓ const Shavaluator = require('redis-evalsha'); const shav = new Shavaluator(redisClient)

✗ const { Shavaluator } = require('redis-evalsha')

The default export is the constructor itself; there is no named export 'Shavaluator'.

exec

✓ shav.exec('scriptName', ['key1'], ['arg1'], callback)

✗ shav.exec('scriptName', ['key1'], ['arg1'], callback, 'someExtra')

exec takes exactly 4 arguments: scriptName, keysArray, argsArray, callback. No extra parameters.

Initialize Shavaluator with a Redis client, add a Lua script, and execute it with EVALSHA/EVAL fallback.

const redis = require('redis'); const Shavaluator = require('redis-evalsha'); const client = redis.createClient({ url: process.env.REDIS_URL ?? 'redis://localhost:6379' }); await client.connect(); const shav = new Shavaluator(client); shav.add('delequal', "if redis.call('GET', KEYS[1]) == ARGV[1] then\n" + " return redis.call('DEL', KEYS[1])\n" + "end\n" + "return 0"); shav.exec('delequal', ['mykey'], ['valueToMatch'], (err, result) => { if (err) console.error(err); else console.log('Deleted?', result); client.quit(); });

Debug

Known issues

gotchaThe exec callback does not follow the standard Node.js callback signature (error, result) for some internal errors; the error may be a string instead of an Error object.

fix

Check if the first argument is truthy and handle both strings and Error objects.

affects: >=0.0.0

gotchaKeys and args arrays must be plain arrays; passing Array-like objects or non-array values can cause unexpected behavior.

fix

Always pass arrays: ['key1'], ['arg1'].

affects: >=0.0.0

gotchaThis package only works with the node-redis library (the one that uses sendCommand). It is not compatible with ioredis or other Redis clients.

fix

Use only with node-redis (redis npm package version 2.x or 3.x). For ioredis, use its built-in evalsha or another library.

affects: >=0.0.0

deprecatedThe underlying node-redis library (v2/v3) is deprecated in favor of redis v4+. This package may not work with redis v4's new API.

fix

Consider migrating to redis v4 and using its native EVALSHA support, or find an alternative wrapper.

affects: >=0.0.0

gotchaShavaluator.add does not validate the Lua script syntax; it only computes the SHA-1 hash. Invalid scripts cause errors only at execution time.

fix

Test your Lua scripts manually before using them in production.

affects: >=0.0.0

Errors

Common errors & fixes

TypeError: redisClient.sendCommand is not a function

Using a Redis client that does not expose sendCommand (e.g., ioredis or redis v4).

fix

Use node-redis version 2.x or 3.x. For redis v4, consider using its built-in EVALSHA or find another library.

ERR Error running script (call to f_...): @user_script:1: user_script:1: attempt to call a nil value (global 'redis')

The Lua script references 'redis' object, but it is only available when executing via EVAL/EVALSHA. Ensure the script is valid Lua and uses 'redis.call' correctly.

fix

Check your Lua script syntax and ensure it uses 'redis.call('COMMAND', ...)' or 'redis.pcall' correctly.

TypeError: Cannot read property 'apply' of undefined

Exec method called with missing or malformed arguments (e.g., no callback).

fix

Ensure exec is called with exactly four arguments: scriptName (string), keys (array), args (array), callback (function).

Error: The script named 'xyz' has not been added

Trying to exec a script that was never added via add().

fix

Call shavaluator.add('scriptName', 'luaScriptBody') before attempting to execute it.

Upgrade

Version history

1.1.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

14 hits · last 30 days

node