redis-consumer 1.1.9 → 1.2.0

package/README.md

@@ -3,73 +3,80 @@
 Simple node package for easy use of Redis Streams functionality. This package allows for creation of a Redis consumer and producer.
 
 - [Installation](#installation)
-- [Usage](#usage)
-  - [Basic Example](#basic-example)
-  - [Class RedisClient](#class-redisclient)
-    - [RedisClientOptions](#redisclientoptions)
-    - [Methods](#methods)
-  - [Class RedisConsumer](#class-redisconsumer)
-    - [RedisConsumerOptions](#redisconsumeroptions)
-    - [Methods](#methods-1)
-    - [StreamToListen Object](#streamtolisten-object)
-  - [Class RedisProducer](#class-redisproducer)
-    - [Methods](#methods-2)
-  - [Events](#events)
-- [Typescript](#typescript)
+- [Quick start](#quick-start)
+- [Class RedisClient](#class-redisclient)
+  - [RedisClientOptions](#redisclientoptions)
+  - [Methods](#methods)
+- [Class RedisConsumer](#class-redisconsumer)
+  - [How messages are processed](#how-messages-are-processed)
+  - [RedisConsumerOptions](#redisconsumeroptions)
+  - [Methods](#methods-1)
+  - [StreamToListen object](#streamtolisten-object)
+- [Class RedisProducer](#class-redisproducer)
+  - [Methods](#methods-2)
+- [Events](#events)
+- [Recipes](#recipes)
+  - [Dead-letter stream](#dead-letter-stream)
+  - [Graceful shutdown](#graceful-shutdown)
+- [Performance](#performance)
+- [TypeScript](#typescript)
+- [Upgrading from 1.1.x](#upgrading-from-11x)
 
 ## Installation
 
-Make sure you have NodeJs installed, then:
+Requires NodeJs 24 or newer.
+
+This package is ESM only (`"type": "module"` in `package.json`). Use `import`. On Node 22.12+ `require()` also happens to work through Node's ESM interop, but `import` is the supported path.
+
+The `redis` API is not re-exported. Import it from `redis` directly.
 
 ```bash
-npm install redis-consumer
+pnpm install redis-consumer
 ```
 
-## Usage
-
-### Basic example
+## Quick start
 
 ```typescript
 import { RedisClient } from 'redis-consumer';
 
-(async () => {
-  // Client name must be unique per client
-  const client = new RedisClient({
-    groupName: 'mygroup',
-    clientName: 'myclient1',
-  });
+const client = new RedisClient({
+  groupName: 'mygroup',
+  // Must be unique per consumer within the group.
+  clientName: 'myclient1',
+});
 
-  client.on('error', err => console.log('Redis Client Error', err));
+client.on('error', err => console.error('Redis client error', err));
 
-  await client.connect();
+await client.connect();
 
-  const consumer = client.createConsumer();
+const producer = client.createProducer();
+const consumer = client.createConsumer();
 
-  // Redis stream to listen to and processable function
-  const stream = {
-    name: 'mystream',
-    executable: (data, stream) => console.log('Redis message for stream ' + stream, data),
-  };
+// Redis stream to listen to and the function that processes its messages.
+consumer.listen({
+  name: 'mystream',
+  executable: (data, stream) => console.log('Message for stream ' + stream, data.message),
+});
+
+await producer.add('mystream', { firstName: 'John', lastName: 'Doe' });
 
-  // Listen for new messages and process them according the
-  // defined executable function
-  consumer.listen(stream);
-})();
+// Stops reading and closes the consumer's own connection.
+await consumer.close();
+await client.close();
 ```
 
-When creating the Redis client, make sure to define a group and client name. Note, the client name must be
-unique in order for Redis to distinguish each individual client within the consumer group.
+A more complete, runnable version is in [`example/index.ts`](example/index.ts).
 
-### Class RedisClient
+## Class RedisClient
 
-_Constructor_ : `new RedisClient(options)`
+_Constructor_: `new RedisClient(options)`
 
 - `options` [RedisClientOptions](#redisclientoptions)
 - extends the `node-redis` client constructor
 
 The `RedisClient` is an extension of the original client from the [node-redis](https://www.npmjs.com/package/redis) package. All constructor options within the `node-redis` package are available to this class as well.
 
-#### Example
+### Example
 
 ```typescript
 // Connect client to Redis server with TLS enabled
@@ -85,16 +92,18 @@ const client = new RedisClient({
 });
 ```
 
-#### RedisClientOptions
+### RedisClientOptions
 
 | Parameters | Description                                   | Required |
 | ---------- | --------------------------------------------- | -------- |
 | groupName  | Name of the consumer group                    | Yes      |
 | clientName | Name of the client, must be unique per client | Yes      |
 
+`groupName` and `clientName` are consumed by this package and are never forwarded to the `redis` client.
+
 Other options can be found in the official `node-redis` github repository over [here](https://github.com/redis/node-redis/blob/master/docs/client-configuration.md).
 
-#### Methods
+### Methods
 
 For all available methods, please look in the official `node-redis` repository over [here](https://github.com/redis/node-redis/blob/master/README.md).
 
@@ -110,108 +119,143 @@ For all available methods, please look in the official `node-redis` repository o
 `streamExists(key)`
 
 - `key` key name of the stream
-- Returns a _boolean_
+- Returns a _Promise<boolean>_
 
 `groupExists(key)`
 
 - `key` name of the stream
-- Returns a _boolean_
+- Returns a _Promise<boolean>_, `false` when the stream does not exist
 
 `createGroup(key)`
 
 - `key` name of the stream
-- Returns a _string_
+- Creates the consumer group with `XGROUP CREATE ... $ MKSTREAM`, so the stream is created when missing and the group starts at the end of it
+- Returns a _Promise<string>_. A group that already exists is not an error: `BUSYGROUP` is swallowed and `'OK'` is returned, so calling this repeatedly (or from several processes at once) is safe
 
-### Class RedisConsumer
+## Class RedisConsumer
 
-_Constructor_ : `client.createConsumer(options)`
+_Constructor_: `client.createConsumer(options)`
 
 - `options` [RedisConsumerOptions](#redisconsumeroptions)
 
-The `RedisConsumer` is able to listen for incomming message in a stream. You can define an object or an array of objects in which you can define the name of the stream to listen for and which function should be executed for processing of the message. The consumer has a build-in retry mechanism which triggers an event `retry-failed` if all retries were unsuccessfull.
+The `RedisConsumer` listens for incoming messages in one or more streams. You can pass a single stream object or an array of them, each with the stream name and the function that processes its messages. A built-in retry mechanism emits `retry-failed` once all retries were unsuccessful.
+
+When a message is successfully processed (also in retry state), the consumer acknowledges it with `XACK` and removes it from the stream with `XDEL`. While a message is not acknowledged it stays in the consumer group's pending list.
 
-When a message is successfully processed (also in retry state), the consumer will send an acknowledgement signal to the Redis server. When the acknowlegdement is performed, the message will be removed from the pending list for that consumer group.
+### How messages are processed
 
-When the consumer starts, it will process all remaining pending messages at first before listening for new incomming messsage. However, you can overrule this behaviour by defining your own starting id.
+- By default the consumer starts at id `'0-0'`, so it first re-processes the messages that are still pending **for this `clientName`** before it starts listening for new ones. Pass `id: '>'` on a stream to skip the pending list and only receive new messages.
+- The executable is awaited. When it returns without throwing, the message is acknowledged and deleted.
+- When it throws, `process-error` is emitted, the message is **not** acknowledged, and a retry is scheduled.
+- Retries are attempted in memory according to `retries` and `retryTime`. The `retry` event fires before each attempt. When the last attempt fails, `retry-failed` is emitted and the message is left in the pending list until you acknowledge it yourself.
+- Messages that are never acknowledged are redelivered the next time a consumer with the same `clientName` starts.
 
-#### Example
+### Example
 
 ```typescript
-  const consumer = client.createConsumer({
-    COUNT: 3,
-    retries: 1,
-    retryTime: ['5s'],
-  });
+const consumer = client.createConsumer({
+  COUNT: 3,
+  retries: 1,
+  retryTime: ['5s'],
+});
 
-  const streams = [
-    {
-      name: 'mystream',
-      id: '>',
-      executable: (data) => console.log('Only listen to new messages', data.message)
-    },
-    {
-      name: 'myssecondstresm',
-      executable: (data, stream) => console.log('Message for stream ' + stream, data.message)
-    }
-  ];
-
-  consumer.client.on('retry-failed', (err, data) => {
-    console.error('Failed processing message in stream ' + data.stream + '. Amount of retries: ' + data.retries, data.message);
-  });
+const streams = [
+  {
+    name: 'mystream',
+    id: '>',
+    executable: (data, stream) => console.log('Only new messages for ' + stream, data.message),
+  },
+  {
+    name: 'mysecondstream',
+    executable: (data, stream) => console.log('Message for stream ' + stream, data.message),
+  },
+];
 
-  consumer.client.on('process-error', (err, data) => {
-    console.error('An unexpected error occured for stream ' + data.stream, err.message);
-  });
+consumer.client.on('retry-failed', (err, data) => {
+  console.error('Failed processing message ' + data.message.id + ' in stream ' + data.stream, err.message);
+});
 
-  consumer.listen(streams);
+consumer.client.on('process-error', (err, data) => {
+  console.error('An unexpected error occurred for stream ' + data.stream, err.message);
 });
+
+await consumer.listen(streams);
 ```
 
-#### RedisConsumerOptions
+### RedisConsumerOptions
 
-| Parameters | Description                                       | Required | Default              |
-| ---------- | ------------------------------------------------- | -------- | -------------------- |
-| COUNT      | Number of elements to read                        | No       | 1                    |
-| BLOCK      | Time in miliseconds to block while reading stream | No       | 0                    |
-| retries    | Amount of retries for processing messages         | No       | 3                    |
-| retryTime  | Time interval between each retry                  | No       | ['15s', '1m', '15m'] |
+| Parameters    | Description                                             | Required | Default              |
+| ------------- | ------------------------------------------------------- | -------- | -------------------- |
+| COUNT         | Number of elements to read                              | No       | 5000                 |
+| BLOCK         | Time in milliseconds to block while reading a stream    | No       | 0                    |
+| retries       | Amount of retries for processing messages               | No       | 3                    |
+| retryTime     | Time interval between each retry                        | No       | ['15s', '1m', '15m'] |
+| batchMessages | Hand the whole batch of a single read to the executable | No       | false                |
 
-More information about the `BLOCK` and `COUNT` parameters can be found at the official [docs](https://redis.io/documentation) of Redis.
+More information about the `BLOCK` and `COUNT` parameters can be found at the official [docs](https://redis.io/documentation) of Redis. `BLOCK: 0` blocks until a message arrives.
 
 The `retryTime` is an array of time strings. Seconds, minutes and hours are supported ('s', 'm', 'h'). When there are less items in the `retryTime` array than the amount of retries, the last time string item is used.
 
 If you want to disable the retry mechanism, select a value of 0 for `retries`.
 
-#### Methods
+When `batchMessages` is enabled, the executable receives the complete array of messages of a single read instead of being called once per message. The option applies to the whole consumer, so every stream it listens to has to use the batch form:
+
+```typescript
+const consumer = client.createConsumer({ batchMessages: true, COUNT: 100 });
 
-`listen(streams)`
+await consumer.listen({
+  name: 'mystream',
+  // `messages` is an array of StreamMessageReply objects
+  executable: messages => console.log('Processing ' + messages.length + ' messages at once'),
+});
+```
+
+If a batch call throws, the consumer cannot tell which message failed, so every message of that read is retried individually.
+
+### Methods
+
+`listen(streams, flag?)`
 
 - `streams` [StreamToListen](#streamtolisten-object) | Array([StreamToListen](#streamtolisten-object))
+- `flag` optional, legacy positional form of the `batchMessages` option
+- Returns a _Promise_ that resolves once the read loop has been started
+
+The consumer group is created automatically for every stream. Calling `listen` a second time with new streams adds them to the already running consumer instead of starting a second read loop; the new stream is picked up as soon as the current read returns. A stream that is already being listened to is left untouched.
+
+`close()`
+
+- Returns a _Promise_ that resolves once the read loop stopped and the consumer's connection is closed. Use it to shut down the consumer and let the process exit. Calling it more than once is safe.
+
+`close()` also cancels the pending retries (their timers would otherwise keep the event loop alive for up to the longest `retryTime`) and flushes acknowledgements that are still queued, so the process can exit and nothing that was already processed is left in the pending list.
+
+`flushAcks()`
+
+- Returns a _Promise_ that resolves once the queued acknowledgements (`XACK` + `XDEL`) were sent to Redis
 
 `addAckMessage(stream, id)`
 
 - `stream` key name of the stream
 - `id` id of the message
 
-Adds the message to the acknowlegdement list.
+Adds the message to the acknowledgement queue. The read loop flushes the queue after every read, so normally you do not need `flushAcks()`. Call it when you queue an acknowledgement from outside the read loop — for example in a `retry-failed` handler — and want the message to leave the pending list right away. Flushes are serialised, so concurrent calls cannot interleave their `XACK`/`XDEL` batches.
 
-#### StreamToListen Object
+### StreamToListen object
 
 ```typescript
 {
   name: 'mystream',                                        // Keyname of the Redis stream
   executable: (message, stream) => console.log(message),   // Message processing function to be executed
-  id: '>'                                                  // Optional, start listining from the message id. Defaults to '0-0'
+  id: '>'                                                  // Optional, start listening from this message id. Defaults to '0-0'
 }
 ```
 
-### Class RedisProducer
+## Class RedisProducer
 
-_Constructor_ : `client.createProducer()`
+_Constructor_: `client.createProducer()`
 
 The `RedisProducer` is used to add new messages to the Redis stream.
 
-#### Example
+### Example
 
 ```typescript
 const message = {
@@ -220,30 +264,88 @@ const message = {
 };
 
 const producer = client.createProducer();
-producer.add('mystream', message);
+const id = await producer.add('mystream', message);
 ```
 
-#### Methods
+### Methods
 
 `add(stream, message)`
 
 - `stream` key name of the stream
 - `message` object/message to add to the stream
+- Returns a _Promise<string>_ resolving with the id of the added message
+
+## Events
 
-### Events
+All events are emitted on `consumer.client`, not on the consumer itself.
 
-| Event name    | Description                                                                                                                                                                                                                                                    |
-| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| process-error | Event is triggered on the `RedisConsumer` when an error occurs during execution of the streams processing function. First argument is the error object, second argument is an object containing the `stream`, `message` and `retries`.                         |
-| retry         | Event is triggered on the `RedisConsumer` just before a retry is attempted. A data object with properties `stream`, `message`, `retries` and `timestamp` is forwarded to the event.                                                                            |
-| retry-failed  | Event is triggered on the `RedisConsumer` when retry of the message has failed/ended. The first argument that is forwarded to the event is the `error`. The second arguments is a data object with properties `stream`, `message`, `retries` and `timestamps`. |
+| Event name    | Signature                                     | Description                                                                                                                                                                                                                                                   |
+| ------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| process-error | `(err: Error, data: ProcessErrorData)`         | An error occurred during execution of the stream processing function. `data` contains `stream`, `message` and `retries`.                                                                                                                                       |
+| retry         | `(data: RetryMessage)`                         | Fired just before a retry is attempted. `data` contains `stream`, `message`, `retries` and `timestamp`.                                                                                                                                                        |
+| retry-failed  | `(err: Error, data: RetryFailedMessage)`       | All retries for a message were unsuccessful. `data` contains `stream`, `message`, `retries` and `timestamps`. The message is still in the pending list.                                                                                                        |
+| listen-error  | `(err: Error)`                                 | A Redis command issued by the consumer failed. Reading is retried after a short delay, and a failed acknowledgement stays queued for the next flush.                                                                                                            |
 
-## Typescript
+## Recipes
 
-This package has full Typescript support. See the example below on how to define a processing function with typed message data.
+### Dead-letter stream
+
+When the retries are exhausted, move the message somewhere else and acknowledge it so it does not stay in the pending list forever:
 
 ```typescript
-import { RedisClient, StreamsToListen, StreamMessageReply } from 'redis-consumer';
+consumer.client.on('retry-failed', async (err, data) => {
+  console.error(`Giving up on ${data.stream} ${data.message.id}: ${err.message}`);
+
+  await producer.add('dead-letters', {
+    sourceStream: data.stream,
+    sourceId: data.message.id,
+    payload: JSON.stringify(data.message.message),
+  });
+
+  consumer.addAckMessage(data.stream, data.message.id);
+  await consumer.flushAcks();
+});
+```
+
+### Graceful shutdown
+
+```typescript
+const shutdown = async (signal: string) => {
+  console.log(`${signal} received, shutting down`);
+  await consumer.close();
+  await client.close();
+};
+
+process.on('SIGINT', () => void shutdown('SIGINT'));
+process.on('SIGTERM', () => void shutdown('SIGTERM'));
+```
+
+## TypeScript
+
+This package has full TypeScript support. Use `StreamProcessingFunction<T>` for a per-message executable and `StreamBatchProcessingFunction<T>` for a batched one to get your message data typed:
+
+```typescript
+import {
+  RedisClient,
+  StreamBatchProcessingFunction,
+  StreamMessageReply,
+  StreamsToListen,
+} from 'redis-consumer';
+
+// Define the interface of your message data
+interface MyMessage {
+  firstName: string;
+  lastName: string;
+}
+
+const processing: StreamBatchProcessingFunction<MyMessage> = async messages => {
+  for (const data of messages) {
+    const message = data.message;
+    const fullName = message.firstName + ' ' + message.lastName; // Fully typed
+
+    console.log('Hello, my name is ' + fullName);
+  }
+};
 
 const client = new RedisClient({
   groupName: 'mygroup',
@@ -258,19 +360,56 @@ const streams: StreamsToListen = [
   },
 ];
 
-const consumer = client.createConsumer();
-consumer.listen(streams);
+const consumer = client.createConsumer({ batchMessages: true });
+await consumer.listen(streams);
+```
 
-// Define interface of your message data
-interface MyMessage {
-  firstName: string;
-  lastName: string;
-}
+Use `StreamProcessingFunction<T>` instead when `batchMessages` is off; the executable then receives a single `StreamMessageReply<T>`.
 
-function processing(data: StreamMessageReply<MyMessage>) {
-  const message = data.message;
-  const fullName = message.firstName + ' ' + message.lastName; // Full typing of message
+`StreamMessageReply<T>` is the shape handed to the executable: `{ id, message, millisElapsedFromDelivery?, deliveriesCounter? }`, where `message` is `T`.
 
-  console.log('Hello, my name is ' + fullName);
-}
-```
+## Performance
+
+`COUNT` is by far the biggest throughput lever: every read, and every acknowledgement batch, is a round trip to Redis.
+
+Measured against a local Redis 7.0.12 with a no-op executable, 2000 messages per run, median of 3 runs:
+
+| Consumer options                   | Throughput  | Redis commands per message |
+| ---------------------------------- | ----------- | -------------------------- |
+| `COUNT: 1`                         | ~1.7k msg/s | ~3.0                       |
+| `COUNT: 10`                        | ~9.6k msg/s | ~0.30                      |
+| `COUNT: 100`                       | ~24k msg/s  | ~0.03                      |
+| `COUNT: 1000, batchMessages: true` | ~38k msg/s  | ~0.003                     |
+
+100,000 messages in a single run, same machine:
+
+| Consumer options                    | Produce | Consume | Throughput | Consumer memory |
+| ----------------------------------- | ------- | ------- | ---------- | --------------- |
+| default (`COUNT: 5000`)             | 2.4 s   | 2.1 s   | ~48k msg/s | ~12 MB          |
+| `COUNT: 5000, batchMessages: true`  | 2.1 s   | 1.9 s   | ~50k msg/s | ~4 MB           |
+| `COUNT: 1000, batchMessages: true`  | 2.1 s   | 2.6 s   | ~38k msg/s | —               |
+
+All 100,000 messages were processed exactly once — no duplicates, none missed — in every configuration.
+
+Guidance:
+
+- `COUNT` defaults to `5000`. Raise it for more throughput, lower it for lower latency: a read returns as soon as `COUNT` messages are available, so a small `COUNT` hands messages over sooner but costs far more round trips.
+- `batchMessages` barely changes throughput. It avoids per-call setup in the executable, but the speed-up above comes from `COUNT`, not from batching.
+- The memory column is the consumer's cost on top of a stream that is already populated, so with the default `COUNT: 5000` expect roughly 10 MB of headroom for in-flight messages.
+- Acknowledgements are pipelined: the `XACK` and `XDEL` of every stream are sent in a single write, so a flush costs one round trip no matter how many streams are involved.
+- Retries run in memory and do not block the read loop. A failed read of `COUNT` messages registers one retry per message, so a large `COUNT` with a short `retryTime` can start many concurrent retry chains at once. A failed read also emits one `process-error` per message, and arming those retries is synchronous: a 200,000-message batch that fails takes about 5 s and ~290 MB before the first retry fires, and `close()` then needs a moment to cancel them all. If your executable can fail on a whole batch, prefer a smaller `COUNT` and let several reads fill the pipeline.
+
+The absolute numbers depend heavily on the round trip time to your Redis; over a real network the effect of `COUNT` is larger, not smaller.
+
+## Upgrading from 1.1.x
+
+- **NodeJs 24 or newer** is required (the `redis` package requires at least NodeJs 20).
+- **ESM only.** The package is published as an ES module. `import` is the supported path; `require()` only works through Node's ESM interop.
+- **The `redis` API is no longer re-exported.** `export * from 'redis'` was removed because node-redis 6 exports a runtime `RedisClient` of its own, which collided with this package's `RedisClient` and made `require()` hand out the wrong class. Import `createClient` and friends from `redis` directly.
+- **`redis` was upgraded from 4.x to 6.x.** Commands and their replies follow the `redis` 6 API. `xPending` for example returns `{ pending, firstId, lastId, consumers }` where `redis` 4 returned `{ total, ... }`.
+- The `@redis/client` deep imports are gone. `StreamMessageId`, `StreamMessageData` and `StreamMessageReply` are exported by this package.
+- `producer.add()` now returns the id of the added message instead of discarding it.
+- `consumer.listen()` can be called repeatedly and no longer starts a second read loop.
+- `consumer.close()` was added, and the consumer no longer keeps the process alive after it.
+- `batchMessages` was added; the positional `flag` argument of `listen()` is kept as a legacy alias.
+- **`COUNT` now defaults to `5000` instead of `1`.** A read now returns up to 5000 messages instead of one, which is where most of the throughput comes from. Set `COUNT: 1` explicitly if you want the old latency-first behaviour, and see [Performance](#performance) for the trade-off.

package/dist/client.d.ts

@@ -1,9 +1,9 @@
-import { RedisScripts } from 'redis';
-import { RedisClientOptions } from 'redis';
-import { RedisConsumer, ConsumerOptions, ProcessErrorData } from './consumer';
-import { RedisProducer } from './producer';
-import { RetryFailedMessage, RetryMessage } from './retry-processor';
-declare const InstRedisClient: import("@redis/client/dist/lib/client").InstantiableRedisClient<import("redis").RedisModules, import("redis").RedisFunctions, RedisScripts>;
+import type { RedisClientOptions, RedisClientType, RedisScripts } from 'redis';
+import { RedisConsumer, ConsumerOptions, ProcessErrorData } from './consumer.js';
+import { RedisProducer } from './producer.js';
+import { RetryFailedMessage, RetryMessage } from './retry-processor.js';
+type NodeRedisClientType = RedisClientType<{}, {}, {}>;
+declare const InstRedisClient: new (options?: RedisClientOptions) => NodeRedisClientType;
 interface AdditionalClientOptions {
     groupName: string;
     clientName: string;
@@ -12,6 +12,7 @@ export declare interface RedisClient<S extends RedisScripts = RedisScripts> {
     on(event: 'process-error', listener: (err: Error, data: ProcessErrorData) => void): this;
     on(event: 'retry-failed', listener: (err: Error, data: RetryFailedMessage) => void): this;
     on(event: 'retry', listener: (data: RetryMessage) => void): this;
+    on(event: 'listen-error', listener: (err: Error) => void): this;
     on(event: string, listener: (data: any) => void): this;
 }
 export declare class RedisClient<S extends RedisScripts> extends InstRedisClient {
@@ -20,7 +21,7 @@ export declare class RedisClient<S extends RedisScripts> extends InstRedisClient
     constructor(options: Omit<RedisClientOptions<never, never, S>, 'modules'> & AdditionalClientOptions);
     createConsumer<S extends RedisScripts>(options?: ConsumerOptions): RedisConsumer<S>;
     createProducer(): RedisProducer<S>;
-    streamExists(key: string): Promise<number>;
+    streamExists(key: string): Promise<boolean>;
     groupExists(key: string): Promise<boolean>;
     createGroup(key: string): Promise<string>;
 }

package/dist/client.js

@@ -1,29 +1,31 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.RedisClient = void 0;
-const client_1 = __importDefault(require("@redis/client/dist/lib/client"));
-const consumer_1 = require("./consumer");
-const producer_1 = require("./producer");
-const InstRedisClient = client_1.default.extend();
-class RedisClient extends InstRedisClient {
+import { createClient } from 'redis';
+import { RedisConsumer } from './consumer.js';
+import { RedisProducer } from './producer.js';
+// node-redis v5 removed the public `RedisClient.extend()` helper, so the
+// command-augmented client class can no longer be obtained by calling it.
+// `createClient()` returns an instance of that class (its factory wraps the
+// subclass built by `attachConfig()`), so the class can be taken off the
+// instance. That keeps subclassing - and `instanceof RedisClient` - working.
+const InstRedisClient = createClient({}).constructor;
+export class RedisClient extends InstRedisClient {
     groupName;
     clientName;
     constructor(options) {
-        super(options);
-        this.groupName = options.groupName;
-        this.clientName = options.clientName;
+        // `groupName`/`clientName` are not Redis options: node-redis v6 mutates and
+        // persists whatever it is handed, so keep them off the client options.
+        const { groupName, clientName, ...clientOptions } = options;
+        super(clientOptions);
+        this.groupName = groupName;
+        this.clientName = clientName;
     }
     createConsumer(options) {
-        return new consumer_1.RedisConsumer(this, options);
+        return new RedisConsumer(this, options);
     }
     createProducer() {
-        return new producer_1.RedisProducer(this);
+        return new RedisProducer(this);
     }
     async streamExists(key) {
-        return await this.exists(key);
+        return (await this.exists(key)) > 0;
     }
     async groupExists(key) {
         if (!(await this.streamExists(key)))
@@ -32,8 +34,16 @@ class RedisClient extends InstRedisClient {
         return groupInfo.length > 0;
     }
     async createGroup(key) {
-        const result = await this.xGroupCreate(key, this.groupName, '$', { MKSTREAM: true });
-        return result;
+        try {
+            return await this.xGroupCreate(key, this.groupName, '$', { MKSTREAM: true });
+        }
+        catch (err) {
+            // Another consumer may have created the group in the meantime; that is
+            // the desired end state, so treat it as success.
+            if (err instanceof Error && err.message.includes('BUSYGROUP')) {
+                return 'OK';
+            }
+            throw err;
+        }
     }
 }
-exports.RedisClient = RedisClient;