{"id":11919,"library":"redis-parser","title":"Redis Protocol Parser for Node.js","description":"redis-parser is a high-performance JavaScript implementation of the Redis Serialization Protocol (RESP) parser, specifically designed for Node.js environments. It serves as the underlying parsing engine for popular Redis clients like node-redis and ioredis. The current stable version is 3.0.0. This library focuses on efficiently converting raw Redis protocol buffers into usable JavaScript data structures, supporting various RESP data types including strings, numbers, arrays, and errors. Its development prioritizes performance, especially for large data structures, and graceful handling of malformed input, making it a critical component for robust Redis client libraries. It also exports dedicated error classes for specific parsing and reply errors.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/NodeRedis/node-redis-parser","tags":["javascript","redis","protocol","parser","database","node","nodejs","resp"],"install":[{"cmd":"npm install redis-parser","lang":"bash","label":"npm"},{"cmd":"yarn add redis-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add redis-parser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import { Parser } from 'redis-parser';","symbol":"Parser","correct":"const Parser = require('redis-parser');"},{"note":"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.","wrong":"import { RedisError } from 'redis-parser';","symbol":"RedisError","correct":"const { RedisError } = require('redis-parser');"},{"note":"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.","wrong":"import { ParserError } from 'redis-parser';","symbol":"ParserError","correct":"const { ParserError } = require('redis-parser');"}],"quickstart":{"code":"const Parser = require('redis-parser');\n\nclass MyRedisClient {\n  constructor() {\n    this.replies = [];\n    this.errors = [];\n    this.fatalErrors = [];\n    this.parser = new Parser({\n      returnReply: this.handleReply.bind(this),\n      returnError: this.handleError.bind(this),\n      returnFatalError: this.handleFatalError.bind(this),\n      returnBuffers: false, // Default: return strings instead of Buffers\n      stringNumbers: false  // Default: return JavaScript numbers, not strings\n    });\n  }\n\n  handleReply(reply) {\n    this.replies.push(reply);\n    console.log('Received Reply:', reply);\n  }\n\n  handleError(err) {\n    this.errors.push(err);\n    console.error('Received Error:', err.message);\n  }\n\n  handleFatalError(err) {\n    this.fatalErrors.push(err);\n    console.error('Received FATAL Error (protocol error):', err.message);\n    // In a real Redis client, this is where you would typically:\n    // 1. Log the error for debugging.\n    // 2. Reject all outstanding commands.\n    // 3. Destroy the current socket connection.\n    // 4. Attempt to reconnect to the Redis server.\n    // This prevents further data corruption due to protocol desynchronization.\n  }\n\n  processStreamData(dataBuffer) {\n    // Simulate receiving raw Redis protocol data (as a Buffer) from a stream\n    this.parser.execute(dataBuffer);\n  }\n}\n\nconst client = new MyRedisClient();\n\n// Simulate receiving various Redis protocol responses\nclient.processStreamData(Buffer.from('$5\\r\\nHello\\r\\n')); // Bulk String \"Hello\"\nclient.processStreamData(Buffer.from(':12345\\r\\n'));    // Integer 12345\nclient.processStreamData(Buffer.from('*2\\r\\n$3\\r\\nfoo\\r\\n$3\\r\\nbar\\r\\n')); // Array [\"foo\", \"bar\"]\nclient.processStreamData(Buffer.from('-ERR unknown command `FOO`\\r\\n')); // Error Reply\n\nconsole.log('\\n--- Parser State & Collected Data ---');\nconsole.log('Total Replies:', client.replies.length, client.replies);\nconsole.log('Total Errors:', client.errors.length, client.errors.map(e => e.message));\n\n// Demonstrate dynamic option change: return numbers as strings for large integers\nclient.parser.setStringNumbers(true);\nclient.processStreamData(Buffer.from(':90071992547409920\\r\\n')); // A number larger than Number.MAX_SAFE_INTEGER\nconsole.log('Last Reply (string number):', client.replies[client.replies.length - 1]);","lang":"javascript","description":"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."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"When initializing the Parser, set `stringNumbers: true` (e.g., `new Parser({ stringNumbers: true, ... })`) or call `parser.setStringNumbers(true)` on an existing instance.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Initialize the Parser with `returnBuffers: true` (e.g., `new Parser({ returnBuffers: true, ... })`) or invoke `parser.setReturnBuffers(true)` on a parser instance.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Provide a specific `returnFatalError` callback function during Parser instantiation to implement robust recovery logic for critical protocol violations.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"deprecated","affected_versions":"<2.6.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"Error: Command reply out of sync. Please check your connection and client logic."},{"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.","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.","error":"RangeError: Invalid array length"},{"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))`.","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`.","error":"TypeError: 'buffer' argument must be of type Buffer. Received type string"}],"ecosystem":"npm"}