Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
RedisScan
✓ import RedisScan from 'node-redis-scan';
✗ import { RedisScan } from 'node-redis-scan';
The library exports the `RedisScan` class as its default export for ESM. The package is also primarily consumed via CommonJS `require`.
redisScan (CommonJS)
✓ const redisScan = require('node-redis-scan');
✗ const { redisScan } = require('node-redis-scan');
For CommonJS environments, the class is the default export and should be imported without destructuring.
createClient (from Redis client)
✓ import { createClient } from 'redis';
✗ import redis from 'redis'; const client = redis.createClient();
While `node-redis-scan` doesn't export this, `createClient` from the underlying `node-redis` package is essential for instantiation. For `node-redis` v4+, `createClient` is a named export. For v3, it was often a direct property of the default export.
This example demonstrates how to instantiate the `node-redis-scan` class with a `node-redis` v3.x client and perform a basic `scan()` operation with a pattern and `count` option.
import { createClient } from 'redis';
import RedisScan from 'node-redis-scan';
async function runScanExample() {
// For node-redis v3.x compatibility, which this library requires.
// In a real application, ensure your 'redis' package is v3.x.
// Connecting to default Redis instance on localhost:6379
const client = createClient();
client.on('error', (err) => {
console.error('Redis Client Error', err);
// Handle connection errors gracefully
});
// For node-redis v3.x, you might need to connect manually or await client.connect() if using newer patterns.
// The example implies an auto-connecting client.
const scanner = new RedisScan(client);
console.log('Starting Redis key scan...');
scanner.scan('your-pattern-*', { count: 1000 }, (err, matchingKeys) => {
if (err) {
console.error('Scan Error:', err);
// Properly disconnect if using client.connect()
client.quit();
return;
}
if (matchingKeys.length > 0) {
console.log(`Found ${matchingKeys.length} matching keys:`)
console.log(matchingKeys);
} else {
console.log('No keys matched the pattern.');
}
// Always disconnect the Redis client when done
client.quit();
});
}
runScanExample();
Debug
Known issues
breakingThis library is explicitly incompatible with `node-redis` client versions 4.x or newer. Attempting to use it with a `node-redis` v4+ client will result in errors due to API changes in the underlying Redis client.fixFor new projects or existing projects using `node-redis` v4.x+, consider using the `scanIterator()` method provided directly by the `node-redis` client. If you must use `node-redis-scan`, downgrade your `node-redis` dependency to a 3.x version.
affects: >=1.0.0 (when used with node-redis >=4.0.0)
gotchaThe `limit` option, introduced in v1.3.0, is a hint for stopping the scan and does not guarantee an exact number of returned keys. The scan will halt when the limit is reached *or exceeded*.fixImplement additional client-side filtering or processing if an exact number of results is critical.
affects: >=1.3.0
gotchaUsing the `type` option (introduced in v1.3.0) requires Redis server version 6.0 or newer. Attempting to use this option with older Redis server versions will result in an error.fixEnsure your Redis server is version 6.0 or newer if you plan to utilize the `type` scanning option. Otherwise, omit the `type` option.
affects: >=1.3.0 (when used with Redis server < 6.0)
deprecatedThe package has received numerous dependency updates to address various security vulnerabilities in development dependencies (`minimist`, `nanoid`, `y18n`, `path-parse`, `mocha`). While these are not direct runtime dependencies, they highlight a pattern of maintenance focused on tooling rather than new features, and older versions may have insecure dev tooling.fixAlways use the latest stable version of `node-redis-scan` to benefit from these crucial dev-dependency security updates. Regularly audit your project's full dependency tree.
affects: <1.3.8
deprecatedThe underlying `node-redis` v3.x dependency itself had a minor security issue, which `node-redis-scan` v1.3.1 addressed by upgrading `node-redis`. Using `node-redis-scan` versions prior to v1.3.1 means you might be exposed to this vulnerability through the transitive `node-redis` dependency.fixUpgrade to `node-redis-scan` v1.3.1 or newer to ensure you are using a patched version of `node-redis` v3.x.
affects: <1.3.1
Errors
Common errors & fixes
TypeError: redisScan is not a constructor
Attempting to instantiate `node-redis-scan` without correctly importing the class in an ES module environment, or trying to destructure a CommonJS default export.
fixFor ES modules, use `import RedisScan from 'node-redis-scan';`. For CommonJS, use `const RedisScan = require('node-redis-scan');`. Error: ERR unsupported SCAN option TYPE
The `type` option was used in a `scan` method call, but the connected Redis server is older than version 6.0, which does not support this option.
fixUpgrade your Redis server to version 6.0 or higher, or remove the `type` option from your `scan` call.
TypeError: client.scan is not a function
An incompatible `node-redis` client (v4.x or newer) was passed to the `RedisScan` constructor. The `node-redis-scan` library expects the API shape of `node-redis` v3.x.
fixEnsure your `redis` package dependency is version 3.x. If you need `node-redis` v4.x+, use its built-in `scanIterator()` instead of this library.
Redis Client Error { err: Error: connect ECONNREFUSED 127.0.0.1:6379 }
The `node-redis` client could not establish a connection to the Redis server, likely because the server is not running or is configured on a different host/port.
fixVerify that your Redis server is running and accessible at the specified host and port (default is `localhost:6379`). Adjust `createClient()` options if your Redis instance is elsewhere.
Audit
Dependencies
redisrequiredThis library requires an instantiated Node Redis client (version 3.x) to perform scan operations. It does not support Node Redis v4.x or newer.