@perryts/redis

A pure-TypeScript Redis / Valkey driver that speaks the wire protocol directly — no native addons, no hiredis, no FFI shims. It runs unchanged on Node.js, Bun, and Perry, where the same source is ahead-of-time compiled to a native binary via LLVM — giving you a real standalone executable that talks to Redis with no JS runtime attached.

Perry is a TypeScript-to-native compiler: it lowers a strict subset of TS through LLVM into a statically-linked binary. @perryts/redis is the third reference driver in the family (after @perryts/postgres and @perryts/mysql), showcasing Perry's ability to host real systems code: every socket read, TLS handshake, and crypto op goes through perry-stdlib.

bun add @perryts/redis
npm install @perryts/redis
pnpm add @perryts/redis

import { connect } from '@perryts/redis';

const conn = await connect({ host: '127.0.0.1', port: 6379 });

await conn.command('SET', 'greeting', 'hello from perry');
const got = await conn.command<Buffer>('GET', 'greeting');
console.log(got.value?.toString('utf8'));   // → 'hello from perry'

await conn.close();

Why another Redis driver?

Most Node Redis clients (ioredis, node-redis) work great on V8 but make assumptions a strict TypeScript-to-native compiler can't honor: runtime-mutable prototypes, dynamic method dispatch, process.nextTick, EventEmitter inheritance, require('hiredis') for parsing speed. None of those translate cleanly to a Perry binary.

@perryts/redis was designed against the Perry AOT constraint set from day one: module-level state maps instead of this.method closures, explicit branching instead of ?. / ??, no for-of on arrays, no dynamic key access. The same source compiles to a native binary AND runs unchanged on Node.js / Bun.

Features

• RESP2 + RESP3 — both parsers ship from day one. HELLO 3 is tried by default; on -NOPROTO we fall back to RESP2 + legacy AUTH transparently.
• Authentication — legacy requirepass, ACL (HELLO 3 AUTH user pass), pluggable via registerAuthPlugin.
• TLS — full TLS-from-SYN via rediss:// (no mid-stream upgrade).
• Pipelining — client.pipeline().add(...).add(...).exec() writes N commands in one syscall; per-command errors don't fail the batch.
• Pub/Sub — client.subscribe(chan, cb) works against both RESP2 array messages and RESP3 push frames; the callback shape is uniform.
• Transactions — client.multi() builder; WATCH-abort returns { aborted: true } cleanly.
• Scripts — client.eval / client.evalsha with automatic -NOSCRIPT retry via cached source.
• Client-side caching — client.tracking.enable({...}) + tracking.on('invalidate', cb) for RESP3 invalidation pushes.
• Blocking commands — client.blockingCommand(args, timeoutMs) sets a pool-visible busy flag so BLPOP / WAIT / XREAD BLOCK don't break pooling.
• Cluster — CRC16 slot routing, MOVED/ASK redirection, per-node pools, hashtag co-location.
• Pool — idle set + waiting queue + RESET-on-release.
• Cancel — second-connection CLIENT KILL ID <id>.
• URLs and env vars — redis://, rediss://, unix://, REDIS_URL, REDIS_HOST, REDIS_PORT, REDIS_USERNAME, REDIS_PASSWORD, REDIS_DB, REDIS_TLS, REDIS_NAME.
• Zero native dependencies. Pure TypeScript over Buffer, node:net, node:tls, node:crypto. Nothing to rebuild per platform.
• GUI-shaped result surface. CommandReply carries the decoded value, the RESP type tag, and the raw RespValue for byte-exact round-trip in tools like Tusk.

Runtime targets

| Runtime | Status | Notes | | ---------------- | -------- | --------------------------------------------------------------------------------- | | Perry (AOT → native) | supported | Same source, compiled via LLVM. No JS runtime at execution time. | | Node.js ≥ 22 | supported | Uses node:net, node:tls, node:crypto, Buffer. | | Bun ≥ 1.3 | supported | Fully works; TLS-from-SYN bypasses Bun's known mid-stream upgrade quirk. |

Quickstart

Connecting

// Object form
const conn = await connect({
  host: '127.0.0.1', port: 6379,
  username: 'alice', password: 'acltestpw',  // ACL — both required
  database: 0,
  name: 'tusk-client-1',                    // CLIENT SETNAME via HELLO
});

// URL form (via `resolveConnectOptions`)
import { resolveConnectOptions } from '@perryts/redis';
const conn = await connect(resolveConnectOptions({
  url: 'redis://alice:[email protected]:6379/0?name=tusk-client-1',
}));

// TLS
const conn = await connect(resolveConnectOptions({
  url: 'rediss://db.internal:6380?tls=verify-full',
}));

Pool

import { Pool } from '@perryts/redis';
const pool = new Pool({ host: '127.0.0.1', port: 6379, max: 10 });

// Acquire + run + release in one call:
const r = await pool.command('GET', 'key');

// Or manually:
await pool.withConnection(async (conn) => {
  await conn.command('MULTI');
  await conn.command('SET', 'a', '1');
  await conn.command('EXEC');
});

await pool.close();

Pipelining

const p = conn.pipeline();
for (let i = 0; i < 1000; i++) p.add('SET', 'k' + i, String(i));
const replies = await p.exec();
// replies[i] = { ok: true, value: CommandReply } | { ok: false, error: RedisError }

Pub/Sub

await conn.subscribe('news', (msg) => {
  console.log(msg.channel, msg.payload.toString('utf8'));
});

Transactions

const m = conn.multi();
m.add('SET', 'a', '1');
m.add('SET', 'b', '2');
const out = await m.exec();
// out[i] = { ok: true, value: CommandReply } | { ok: false, error } | { aborted: true }

Scripts

import { evalScript, evalShaScript, sha1Hex } from '@perryts/redis';
const sha1 = sha1Hex("return tonumber(ARGV[1]) * 2");
await evalScript(conn, "return tonumber(ARGV[1]) * 2", [], ['21']);
await evalShaScript(conn, sha1, [], ['21']);  // auto-retries on -NOSCRIPT

Cluster

import { ClusterClient } from '@perryts/redis';
const cluster = new ClusterClient({
  nodes: [
    { host: 'cluster1', port: 7001 },
    { host: 'cluster2', port: 7002 },
    { host: 'cluster3', port: 7003 },
  ],
  password: 'secret',
});
await cluster.command('SET', 'user:{1000}.profile', JSON.stringify({...}));

Development

bun install
bun test                    # unit + mock-server integration tests
bun run typecheck           # tsc --noEmit
bun run build               # tsc → dist/

# Live-server tests (requires a running Redis):
redis-server --port 36379 --daemonize yes
REDIS_HOST=127.0.0.1 REDIS_PORT=36379 bun test tests/integration/real-server.test.ts

License

MIT — see LICENSE.