Skip to content

AGENTS.md

Latest commit

 

History

History
81 lines (62 loc) · 3.59 KB

AGENTS.md

File metadata and controls

81 lines (62 loc) · 3.59 KB
Raw

AGENTS.md

Guidance for agents working in this repo.

What this is

node-redis — modern Redis client for Node.js. A monorepo (npm workspaces) of publishable packages. Requires Node >= 20. TypeScript throughout.

Packages (packages/)

Package Purpose
redis "All-in-one" meta-package re-exporting client + all modules
client (@redis/client) Core: RedisClient, RedisCluster, RedisSentinel, pool, RESP codec, command framework
bloom (@redis/bloom) Probabilistic commands (bloom, cuckoo, count-min, t-digest, top-k)
json (@redis/json) RedisJSON commands
search (@redis/search) RediSearch commands
time-series (@redis/time-series) Time-series commands
entraid (@redis/entraid) Microsoft Entra ID token auth
test-utils (@redis/test-utils) Shared test harness; spins up Redis via docker

Module packages depend on @redis/client and follow the same command structure.

Core layout — packages/client/lib/

  • client/ — connection internals: index.ts (RedisClient), socket.ts, commands-queue.ts, parser.ts, pool.ts, pub-sub.ts, cache.ts
  • cluster/, sentinel/ — cluster & sentinel clients
  • commands/ — one file per Redis command (e.g. GET.ts) + index.ts registry
  • RESP/ — RESP2/RESP3 protocol: encoder.ts, decoder.ts, types.ts
  • authx/ — auth/credential providers

Command pattern

Each command is <NAME>.ts exporting a Command object:

export default {
  CACHEABLE: true,
  IS_READ_ONLY: true,
  parseCommand(parser: CommandParser, key: RedisArgument) {
    parser.push('GET');
    parser.pushKey(key);
  },
  transformReply: undefined as unknown as () => BlobStringReply | NullReply
} as const satisfies Command;
  • parseCommand builds wire args via CommandParser (push, pushKey, ...).
  • transformReply maps reply to JS type; undefined = pass-through. Can be keyed by RESP version { 2: ..., 3: ... }.
  • Register new command in the package's commands/index.ts (import + map entry). RESP3 is default — no extra RESP3 test needed for new commands.
  • JSDoc on commands is checked: npm run check:command-jsdoc.

Tests

  • Co-located <NAME>.spec.ts next to source. Mocha + tsx, node:assert.
  • testUtils.testAll(name, fn, { client, cluster }) runs same test across server + cluster topologies (see test-utils.ts, GLOBAL).
  • Docker required — test-utils starts real Redis containers.
  • Pure arg/reply tests use parseArgs(COMMAND, ...args).

Commands:

  • npm test — full suite, all workspaces (runs cleanup first).
  • npm test -w @redis/client — one package.
  • Single file from root: npm run test-single -- <path-to-spec>.
  • npm run build — tsc --build (project references; build before cross-package work).
  • Build can break on stale dist/ from project references. Clean rebuild: 
    find packages -type d -name "dist" -exec rm -rf {} + && npm run build
  • npm run lint — lint changed files only; npm run lint:all for everything.

Conventions

  • TypeScript strict mode; noUnusedLocals on. Target ES2022 / NodeNext modules.
  • Raw command names (HSET) and camelCase aliases (hSet) both exposed.
  • Conventional Commits. Per-package releases via release-it (npm run release).
  • Keep company-internal refs (Jira/Confluence IDs, internal links) out of OSS commits, branches, PRs, code.

Docs

Deep-dive guides in docs/ (client-configuration, clustering, sentinel, pool, RESP, transactions, programmability, pub-sub, scan-iterators, migration guides). Runnable examples in examples/, doctests/.