redis-stream-kit

library0.1.4jsnpmunverified

Tiny TypeScript wrapper over Redis Streams providing typed Producer and Consumer classes with an injected Redis client. Current version 0.1.4 supports Node >=18 and Redis >=6.2 for XAUTOCLAIM. Differentiators: fully typed, manual ack control, configurable concurrency, auto-claim for stale recovery, and ESM-only design. Release cadence is irregular; API is stable for basic usage but breaking changes may occur before 1.0.

database

npm install redis-stream-kit

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REDIS-STREAM-KIT

redis-stream-kit

databasejavascriptv0.1.4

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

Producer

✓ import { Producer } from 'redis-stream-kit'

✗ const Producer = require('redis-stream-kit').Producer

ESM-only package; CJS require will not work with named exports in some bundlers

Consumer

✓ import { Consumer } from 'redis-stream-kit'

✗ import Consumer from 'redis-stream-kit'

Consumer is a named export, not default

Producer and Consumer together

✓ import { Producer, Consumer } from 'redis-stream-kit'

✗ import { Producer, Consumer } from 'redis-stream-kit/stream'

All exports are from the package root, no subpaths

Demonstrates creating Producer and Consumer with typed events, emitting a message, handling it with auto-claim, and graceful shutdown.

import Redis from 'ioredis'; import { Producer, Consumer } from 'redis-stream-kit'; const client = new Redis({ host: 'localhost', port: 6379 }); type Event = { userId: string; action: string; }; const producer = new Producer<Event>(client, 'events', { maxLen: 10000 }); await producer.start(); await producer.emit({ userId: 'u1', action: 'login' }); const consumer = new Consumer<Event>(client, 'events', 'workers', async (data, meta) => { console.log(meta.id, data.userId, data.action); // XACK automatically on success }, { concurrency: 4, onError: (err, data, meta) => console.error('handler failed', meta.id, err), autoClaim: { idleMs: 60_000, intervalMs: 30_000 }, }); await consumer.start(); // Graceful shutdown after some work... await consumer.stop(); await producer.stop(); client.disconnect();

Debug

Known issues

gotchaHandler errors or decode failures do NOT ack the message. The message stays pending and can be recovered via autoClaim or manual processing.

fix

Implement onError to log or dead-letter; ensure handler logic does not throw unexpectedly.

affects: >=0.0.0

gotchaConsumer options createIfMissing (default true) may create the stream and consumer group automatically. If the stream has existing data with different schema, the consumer will attempt to decode all pending messages, potentially causing errors.

fix

Set createIfMissing: false if stream is already managed externally.

affects: >=0.0.0

deprecatedThe 'autoClaim' option currently exists but may be reworked in future versions. Check changelog for breaking changes.

fix

Keep an eye on releases; no immediate action needed.

affects: <1.0.0

gotchaEach top-level field of the payload is JSON-encoded into a separate Redis stream field. Fields with non-JSON-serializable values (e.g., BigInt, undefined) will cause encode failure at emit time.

fix

Ensure all payload values are JSON-serializable; use a wrapper type if needed.

affects: >=0.0.0

breakingVersion 0.1.0 changed the constructor signature: options parameter moved from second to third position. Old code using positional args will fail.

fix

Update constructor calls to match new signature: new Producer(client, stream, options?) and new Consumer(client, stream, group, handler, options?).

affects: <0.1.0

Errors

Common errors & fixes

Error: Cannot find module 'redis-stream-kit'

Package not installed or import path incorrect.

fix

Run 'npm install redis-stream-kit' and ensure import is 'redis-stream-kit' (no subpath).

TypeError: consumer.start is not a function

Consumer constructor called without 'new' or imported incorrectly (e.g., default import instead of named).

fix

Use 'import { Consumer } from 'redis-stream-kit' and instantiate with 'new Consumer(...)'.

Error: ERR wrong number of arguments for 'xadd' command

Producer.emit called with non-object or after producer.stop().

fix

Ensure emit receives a plain object and producer is started (call await producer.start()).

Error: NOGROUP No such key 'stream' or consumer group 'group'

Stream or consumer group does not exist and createIfMissing is false.

fix

Set createIfMissing: true (default) or manually create stream and group via Redis CLI.

Error: Unhandled 'error' event on Redis client – connection refused

Redis client not connected or wrong host/port.

fix

Verify Redis is running and client configuration is correct: new Redis({ host: 'localhost', port: 6379 }).

Upgrade

Version history

0.1.4latest on npm

Audit

Dependencies

ioredisoptionalRequired to create Redis client instance used by Producer and Consumer

Agent activity

18 hits · last 30 days

node