Registry / database / redis-parser

redis-parser

JSON →
library3.0.0jsnpmunverified

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.

database
npm install redis-parser
github ↗package ↗
INSTALL
IMPORT
SIG · REDIS-PARSER
R
redis-parser
databasejavascriptv3.0.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
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
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Parser
✓ const Parser = require('redis-parser');
✗ import { Parser } from '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
✓ const { RedisError } = require('redis-parser');
✗ import { RedisError } from '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
✓ const { ParserError } = require('redis-parser');
✗ import { ParserError } from '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.

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]);
Debug
Known issues
breakingVersion 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`.
affects: >=3.0.0
breakingSupport 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.
affects: >=3.0.0
gotchaJavaScript'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.
affects: >=2.0.0
gotchaBy 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.
affects: >=2.0.0
gotchaProtocol 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.
affects: >=2.0.0
deprecatedInternal 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.
affects: <2.6.0
Errors
Common errors & fixes
Error: Command reply out of sync. Please check your connection and client logic.
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
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
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))`.
Upgrade
Version history
3.0.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
9 hits · last 30 days
node
8
Resources
githubhttps://github.com/NodeRedis/node-redis-parser ↗
packagehttps://www.npmjs.com/package/redis-parser ↗
redis-parser — npm install redis-parser · libregistry