A high-performance JavaScript parser for the Valkey wire protocol (RESP).
When a Node.js application talks to a Valkey server, the data on the TCP socket is not JavaScript values — it is a stream of bytes framed in RESP (a compact, text-framed protocol). For example, the reply to GET name arrives as:
$5\r\nsrinu\r\n
This package decodes that byte stream into usable JavaScript values — strings, numbers, arrays, and error objects — and hands them to your callbacks. That is its entire job: bytes in, values out.
Decoding RESP correctly and quickly is harder than it looks:
- TCP is a stream, not messages. A single reply can arrive split across many chunks, and one chunk can carry the tail of one reply plus the head of the next. The parser holds partial state between calls — including partially received nested arrays — and resumes exactly where it stopped.
- Decoding sits on the hot path. A busy client parses enormous volumes of replies per second. The implementation avoids allocations wherever possible: a reusable, self-shrinking buffer pool, a zero-copy path for replies contained in one chunk, byte-by-byte integer parsing, and UTF-8-safe assembly of strings split across packets.
npm install valkey-parserconst Parser = require('valkey-parser')
const parser = new Parser({
returnReply (reply) { /* fully decoded value: string, number, array… */ },
returnError (err) { /* server-side ReplyError */ },
returnFatalError (err) { /* unrecoverable protocol error */ }
})
socket.on('data', chunk => parser.execute(chunk))Feed every raw socket chunk to parser.execute(). The parser fires returnReply once per fully decoded reply — no matter how the chunks were split.
| Option | Required | Description |
|---|---|---|
returnReply |
yes | Called once per fully decoded reply. |
returnError |
yes | Called when the server returns an error reply (ReplyError). |
returnFatalError |
no | Called on an unrecoverable protocol error. Defaults to returnError. |
returnBuffers |
no | Return raw Buffers instead of strings — for binary payloads. Default false. |
stringNumbers |
no | Return numbers as strings, preserving integers beyond 2^53. Default false. |
- A server error reply (
-ERR …) is delivered toreturnErroras aReplyError. - A corrupt stream (unknown type byte) raises a
ParserErrorthroughreturnFatalError, carrying the offending byte and offset. The parser drops its buffer — the correct response is to tear down the connection and reconnect; a corrupt RESP stream cannot be resynchronized safely.
This package only decodes server responses. Connection management, command encoding, pipelining, request queues, and reconnection belong to the client layer above it.