redis-scan.js

/**
 * Given a Redis instance this class provides a couple methods for easily
 * scanning the entire keyspace.
 *
 * @name RedisScan
 * @class
 * @param {Object} redis - An instance of Node Redis:
 * https://github.com/NodeRedis/node_redis
 */
class RedisScan {

	constructor(redis) {
		this.redisClient = redis;
	}

	/**
	 * Scans the entire Redis keyspace to find matching keys. The matching
	 * keys are returned in sets via the `eachScanCallback` function which is
	 * called after each iteration of the Redis `SCAN` command. This method is
	 * useful if you want to operate on chunks and/or perform work with results
	 * at the same time as the keyspace is being scanned. That is, you want to
	 * be efficient while searching through or expecting to match on tens of
	 * thousands or even millions of keys.
	 *
	 * @name eachScan
	 *
	 * @method
	 *
	 * @param {String} pattern - A Redis glob-style string pattern of keys to
	 * match.
	 *
	 * @param {Function} eachScanCallback - A function called after each
	 * call to the Redis `SCAN` command. Invoked with (matchingKeys). If this
	 * function returns `true` (NOT truthy) the scan will be cancelled and
	 * `callback` will be called with the keys that were scanned.
	 *
	 * @param {Function} [callback] - A function called after the full scan has
	 * completed and all keys have been returned.
	 * 
	 * @param {Number} [count] - The COUNT parameter. Defaults to 10 (the Redis default)
	 */
	eachScan(pattern, eachScanCallback, callback, count = 10) {
		let matchingKeysCount = 0;

		// Because we're using the `scan()` method of the node-redis library
		// a recursive function seems easiest here.
		const recursiveScan = (cursor = 0) => {
			// Build a Redis `SCAN` command using the `MATCH` option.
			// See: https://redis.io/commands/scan#the-match-option
			this.redisClient.scan(cursor, 'MATCH', pattern, 'COUNT', count, (err, data) => {
				if (err) {
					callback(err);
				} else {
					// client.scan() returns an array with two elements. The
					// first element is the next cursor and the second is an
					// array of matching keys (which might be empty). We'll
					// destructure this into two variables.
					const [cursor, matchingKeys] = data;

					matchingKeysCount += matchingKeys.length;
					
					if (eachScanCallback(matchingKeys) === true) {
						callback(null, matchingKeysCount);
						return;
					}

					// We're done once Redis returns 0 for the next cursor.
					if (cursor === '0') {
						callback(null, matchingKeysCount);
					} else {
						// Otherwise, call this function again AKA recurse
						// and pass the next cursor.
						recursiveScan(cursor);
					}
				}
			});
		};

		// Begin the scan.
		recursiveScan();
	}

	/**
	 * Scans the entire Redis keyspace to find matching keys. The matching
	 * keys are returned as an array of strings via callback. Depending on
	 * the size of your keyspace this function might not be ideal for
	 * performance. It may take tens of seconds or more for Redis databases
	 * with huge keyspaces (i.e. millions of keys or more).
	 *
	 * @name scan
	 *
	 * @method
	 *
	 * @param {String} pattern - A Redis glob-style string pattern of keys to
	 * match.
	 *
	 * @param {Function} [callback] - A function called after the full scan
	 * of the Redis keyspace completes having searched for the given pattern.
	 * Invoked with (err, keys).
	 */
	scan(pattern, callback) {
		let keys = [];

		// Collect all our keys into a single array using the `eachScan()`
		// method from above.
		this.eachScan(pattern, (matchingKeys) => {
			keys = keys.concat(matchingKeys);
		}, (err, count) => {
			if (err) {
				callback(err);
			} else {
				callback(null, keys);
			}
		});
	}
}

module.exports = RedisScan;