Redis Protocol Parser for Node.js

Common errors

• Error: Command reply out of sync. Please check your connection and client logic.

  cause This error often indicates a desynchronization in the Redis protocol stream. It can be caused by network issues, a misbehaving Redis server, or incorrect client logic that sends malformed data or misinterprets responses, leading the parser to encounter unexpected data.
  fix Implement the `returnFatalError` callback to specifically handle protocol desynchronization. Within this callback, you should reset the parser state (`parser.reset()`), destroy the current network connection, and initiate a new one. All outstanding commands should be either rejected or re-queued for execution on the new connection.

• RangeError: Invalid array length

  cause In older versions of `redis-parser` (prior to v2.3.0), parsing extremely large or deeply nested Redis arrays could sometimes lead to inefficiencies in memory handling or exceeding JavaScript's recursion limits, resulting in this error.
  fix Upgrade `redis-parser` to version 2.3.0 or higher. This version introduced significant performance improvements for handling large arrays, making the parsing time linear and much more resilient to arbitrary array sizes.

• TypeError: 'buffer' argument must be of type Buffer. Received type string

  cause The `parser.execute()` method strictly expects a Node.js `Buffer` object as its input, containing the raw Redis protocol data. Passing a JavaScript string directly will result in this `TypeError`.
  fix Ensure that any data fed to `parser.execute()` is first converted into a `Buffer`. For example, if you receive string data, use `parser.execute(Buffer.from(yourStringData))`.

Warnings

• breaking Version 3.0.0 of `redis-parser` drops support for Node.js versions older than 4. Users on Node.js 0.x or 3.x environments must upgrade to Node.js 4 or newer, or pin their `redis-parser` dependency to '~2.x' to avoid compatibility issues.
  Fix: Upgrade Node.js to version 4 or higher. Alternatively, if upgrading Node.js is not possible, specify `"redis-parser": "~2.x"` in your `package.json`.
• breaking Support for the optional native `hiredis` C++ parser has been completely removed in `redis-parser` v3.0.0. The package now exclusively uses its highly optimized JavaScript parser. While the JS parser has seen significant performance improvements, environments specifically configured to leverage `hiredis` might observe changes in parsing behavior or performance characteristics.
  Fix: No direct fix is required as the library will now default to its JavaScript implementation. Users should test their applications for any unexpected performance regressions if `hiredis` was previously integral to their setup.
• gotcha JavaScript's `Number.MAX_SAFE_INTEGER` (`2^53 - 1`) limits the precision of integers. Redis can return numbers larger than this. If not handled, these large numbers will be truncated or inaccurate. To prevent data loss, use the `stringNumbers: true` option to receive all numbers as strings.
  Fix: When initializing the Parser, set `stringNumbers: true` (e.g., `new Parser({ stringNumbers: true, ... })`) or call `parser.setStringNumbers(true)` on an existing instance.
• gotcha By default, `redis-parser` returns bulk strings and array elements as JavaScript strings (UTF-8 decoded). If your application requires raw binary data (e.g., for storing images, serialized objects, or specific encodings), you must enable the `returnBuffers` option to receive `Buffer` objects.
  Fix: Initialize the Parser with `returnBuffers: true` (e.g., `new Parser({ returnBuffers: true, ... })`) or invoke `parser.setReturnBuffers(true)` on a parser instance.
• gotcha Protocol errors (indicating severe issues with the Redis response format) are typically passed to the `returnFatalError` callback. If this callback is not provided, fatal errors will be routed to `returnError`. It is crucial to implement `returnFatalError` to gracefully handle these scenarios, which usually involves tearing down the connection, rejecting any outstanding commands, and attempting a reconnect.
  Fix: Provide a specific `returnFatalError` callback function during Parser instantiation to implement robust recovery logic for critical protocol violations.
• deprecated Internal use of `new Buffer()` (which is deprecated in modern Node.js) was present in `redis-parser` versions prior to 2.6.0. Version 2.6.0 updated internal implementations to utilize `Buffer.allocUnsafe` for improved performance and alignment with current Node.js best practices.
  Fix: Upgrade `redis-parser` to version 2.6.0 or newer to ensure the use of modern and optimized buffer allocation methods, reducing potential warnings or issues in newer Node.js environments.

Install

• npm install redis-parser npm
• yarn add redis-parser yarn
• pnpm add redis-parser pnpm

Imports

• Parser
  wrong:

  import { Parser } from 'redis-parser';

  correct:

  const Parser = require('redis-parser');

  The `Parser` class is the primary export. This package is primarily distributed as CommonJS. While internals might use ES6 features, direct ES Module imports (`import`) might not function correctly without a transpilation step or specific `type: module` configuration in the consuming project, as it does not explicitly provide ESM entry points.
• RedisError
  wrong:

  import { RedisError } from 'redis-parser';

  correct:

  const { RedisError } = require('redis-parser');

  The `RedisError` class is the base class for all errors generated by the parser. Although the README mentions importing error classes from `redis-errors`, `redis-parser` itself exports `RedisError` directly since v2.4.0.
• ParserError
  wrong:

  import { ParserError } from 'redis-parser';

  correct:

  const { ParserError } = require('redis-parser');

  The `ParserError` class represents errors specifically encountered during the Redis protocol parsing process (e.g., malformed data). This class has been exported directly from `redis-parser` since v2.5.0 and allows for differentiation from general `ReplyError` instances.

Quickstart

This quickstart initializes `redis-parser` with necessary callback functions for handling parsed replies, standard errors, and critical protocol errors. It demonstrates feeding various Redis protocol buffers to the parser's `execute` method and dynamically adjusting parsing options like `stringNumbers` for safe handling of large integers.

const Parser = require('redis-parser');

class MyRedisClient {
  constructor() {
    this.replies = [];
    this.errors = [];
    this.fatalErrors = [];
    this.parser = new Parser({
      returnReply: this.handleReply.bind(this),
      returnError: this.handleError.bind(this),
      returnFatalError: this.handleFatalError.bind(this),
      returnBuffers: false, // Default: return strings instead of Buffers
      stringNumbers: false  // Default: return JavaScript numbers, not strings
    });
  }

  handleReply(reply) {
    this.replies.push(reply);
    console.log('Received Reply:', reply);
  }

  handleError(err) {
    this.errors.push(err);
    console.error('Received Error:', err.message);
  }

  handleFatalError(err) {
    this.fatalErrors.push(err);
    console.error('Received FATAL Error (protocol error):', err.message);
    // In a real Redis client, this is where you would typically:
    // 1. Log the error for debugging.
    // 2. Reject all outstanding commands.
    // 3. Destroy the current socket connection.
    // 4. Attempt to reconnect to the Redis server.
    // This prevents further data corruption due to protocol desynchronization.
  }

  processStreamData(dataBuffer) {
    // Simulate receiving raw Redis protocol data (as a Buffer) from a stream
    this.parser.execute(dataBuffer);
  }
}

const client = new MyRedisClient();

// Simulate receiving various Redis protocol responses
client.processStreamData(Buffer.from('$5\r\nHello\r\n')); // Bulk String "Hello"
client.processStreamData(Buffer.from(':12345\r\n'));    // Integer 12345
client.processStreamData(Buffer.from('*2\r\n$3\r\nfoo\r\n$3\r\nbar\r\n')); // Array ["foo", "bar"]
client.processStreamData(Buffer.from('-ERR unknown command `FOO`\r\n')); // Error Reply

console.log('\n--- Parser State & Collected Data ---');
console.log('Total Replies:', client.replies.length, client.replies);
console.log('Total Errors:', client.errors.length, client.errors.map(e => e.message));

// Demonstrate dynamic option change: return numbers as strings for large integers
client.parser.setStringNumbers(true);
client.processStreamData(Buffer.from(':90071992547409920\r\n')); // A number larger than Number.MAX_SAFE_INTEGER
console.log('Last Reply (string number):', client.replies[client.replies.length - 1]);