{"id":13657,"library":"node-redis-scan","title":"Node Redis Scanner","description":"node-redis-scan is a utility library for Node.js (requiring Node 10+) that simplifies key space scanning in Redis, leveraging the `SCAN`, `HSCAN`, `SSCAN`, and `ZSCAN` commands. It provides a higher-level API over the raw Redis commands, abstracting the cursor management typically required for incremental iteration. The current stable version is 1.3.8, with recent releases primarily focusing on `devDependencies` security updates rather than new features. A key differentiator is its provision of `scan()` for retrieving all matching keys in one go and `eachScan()` for processing keys iteratively as they are found, with the ability to cancel. However, it explicitly supports only `node-redis` client versions 3.x and earlier. Users of `node-redis` v4.x or newer are advised to use the client's built-in `scanIterator()` for similar functionality, which offers async iteration capabilities.","status":"maintenance","version":"1.3.8","language":"javascript","source_language":"en","source_url":"https://github.com/GigSalad/node-redis-scan","tags":["javascript","redis","scan","scanner"],"install":[{"cmd":"npm install node-redis-scan","lang":"bash","label":"npm"},{"cmd":"yarn add node-redis-scan","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-redis-scan","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This library requires an instantiated Node Redis client (version 3.x) to perform scan operations. It does not support Node Redis v4.x or newer.","package":"redis","optional":false}],"imports":[{"note":"The library exports the `RedisScan` class as its default export for ESM. The package is also primarily consumed via CommonJS `require`.","wrong":"import { RedisScan } from 'node-redis-scan';","symbol":"RedisScan","correct":"import RedisScan from 'node-redis-scan';"},{"note":"For CommonJS environments, the class is the default export and should be imported without destructuring.","wrong":"const { redisScan } = require('node-redis-scan');","symbol":"redisScan (CommonJS)","correct":"const redisScan = require('node-redis-scan');"},{"note":"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.","wrong":"import redis from 'redis'; const client = redis.createClient();","symbol":"createClient (from Redis client)","correct":"import { createClient } from 'redis';"}],"quickstart":{"code":"import { createClient } from 'redis';\nimport RedisScan from 'node-redis-scan';\n\nasync function runScanExample() {\n  // For node-redis v3.x compatibility, which this library requires.\n  // In a real application, ensure your 'redis' package is v3.x.\n  // Connecting to default Redis instance on localhost:6379\n  const client = createClient();\n\n  client.on('error', (err) => {\n    console.error('Redis Client Error', err);\n    // Handle connection errors gracefully\n  });\n\n  // For node-redis v3.x, you might need to connect manually or await client.connect() if using newer patterns.\n  // The example implies an auto-connecting client.\n\n  const scanner = new RedisScan(client);\n\n  console.log('Starting Redis key scan...');\n  scanner.scan('your-pattern-*', { count: 1000 }, (err, matchingKeys) => {\n    if (err) {\n      console.error('Scan Error:', err);\n      // Properly disconnect if using client.connect()\n      client.quit();\n      return;\n    }\n\n    if (matchingKeys.length > 0) {\n      console.log(`Found ${matchingKeys.length} matching keys:`)\n      console.log(matchingKeys);\n    } else {\n      console.log('No keys matched the pattern.');\n    }\n\n    // Always disconnect the Redis client when done\n    client.quit();\n  });\n}\n\nrunScanExample();","lang":"javascript","description":"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."},"warnings":[{"fix":"For 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.","message":"This 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.","severity":"breaking","affected_versions":">=1.0.0 (when used with node-redis >=4.0.0)"},{"fix":"Implement additional client-side filtering or processing if an exact number of results is critical.","message":"The `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*.","severity":"gotcha","affected_versions":">=1.3.0"},{"fix":"Ensure your Redis server is version 6.0 or newer if you plan to utilize the `type` scanning option. Otherwise, omit the `type` option.","message":"Using 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.","severity":"gotcha","affected_versions":">=1.3.0 (when used with Redis server < 6.0)"},{"fix":"Always 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.","message":"The 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.","severity":"deprecated","affected_versions":"<1.3.8"},{"fix":"Upgrade to `node-redis-scan` v1.3.1 or newer to ensure you are using a patched version of `node-redis` v3.x.","message":"The 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.","severity":"deprecated","affected_versions":"<1.3.1"}],"env_vars":null,"search_vec":"'1.3.8':58 '10':16 '3':113 'abil':100 'abstract':44 'advis':126 'api':38 'async':141 'built':133 'built-in':132 'cancel':102 'capabl':143 'client':111,130 'command':31,43 'current':54 'cursor':46 'devdepend':65 'differenti':74 'eachscan':89 'earlier':116 'explicit':105 'featur':71 'focus':63 'found':97 'function':138 'go':87 'higher':36 'higher-level':35 'howev':103 'hscan':27 'increment':51 'iter':52,93,142 'javascript':144 'key':19,73,84,92 'level':37 'leverag':24 'librari':11 'manag':47 'match':83 'new':70 'newer':124 'node':1,5,15,109,120 'node-redi':108,119 'node-redis-scan':4 'node.js':13 'offer':140 'one':86 'primarili':62 'process':91 'provid':33 'provis':77 'rather':68 'raw':41 'recent':60 'redi':2,6,23,42,110,121,145 'releas':61 'requir':14,49 'retriev':81 'scan':7,21,26,79,146 'scaniter':135 'scanner':3,147 'secur':66 'similar':137 'simplifi':18 'space':20 'sscan':28 'stabl':55 'support':106 'typic':48 'updat':67 'use':128 'user':117 'util':10 'v4.x':122 'version':56,112 'x':114 'zscan':30","created_at":"2026-04-20T01:55:37.904039+00:00","updated_at":"2026-04-20T01:55:37.904039+00:00","problems":[{"fix":"For ES modules, use `import RedisScan from 'node-redis-scan';`. For CommonJS, use `const RedisScan = require('node-redis-scan');`.","cause":"Attempting to instantiate `node-redis-scan` without correctly importing the class in an ES module environment, or trying to destructure a CommonJS default export.","error":"TypeError: redisScan is not a constructor"},{"fix":"Upgrade your Redis server to version 6.0 or higher, or remove the `type` option from your `scan` call.","cause":"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.","error":"Error: ERR unsupported SCAN option TYPE"},{"fix":"Ensure your `redis` package dependency is version 3.x. If you need `node-redis` v4.x+, use its built-in `scanIterator()` instead of this library.","cause":"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.","error":"TypeError: client.scan is not a function"},{"fix":"Verify 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.","cause":"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.","error":"Redis Client Error { err: Error: connect ECONNREFUSED 127.0.0.1:6379 }"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/GigSalad/node-redis-scan","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/node-redis-scan","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}