feat: add control client for adjusting blocking behavior

BREAKING CHANGE: only permitted options are accepted

Author: calebboyd

README.md

@@ -32,8 +32,3 @@ async function populate(stream, count) {
 
 See the [API Docs](docs/classes/RedisStream.md#constructor) for available options.
 
-## Advanced Usage
-
-A common use case for redis streams is task processing. This iterable abstraction can help with handling tasks _at least once_.
-
-For example, You can immediately setup a group and consumer for any stream or streams.

docs/classes/RedisStream.md

@@ -15,6 +15,7 @@
 - [buffers](RedisStream.md#buffers)
 - [client](RedisStream.md#client)
 - [consumer](RedisStream.md#consumer)
+- [control](RedisStream.md#control)
 - [count](RedisStream.md#count)
 - [deleteOnAck](RedisStream.md#deleteonack)
 - [done](RedisStream.md#done)
@@ -46,7 +47,7 @@
 
 #### Defined in
 
-[stream.ts:63](https://github.com/calebboyd/redis-x-stream/blob/4a00dad/src/stream.ts#L63)
+[stream.ts:75](https://github.com/calebboyd/redis-x-stream/blob/52317a3/src/stream.ts#L75)
 
 ## Properties
 
@@ -56,7 +57,7 @@
 
 #### Defined in
 
-[stream.ts:35](https://github.com/calebboyd/redis-x-stream/blob/4a00dad/src/stream.ts#L35)
+[stream.ts:43](https://github.com/calebboyd/redis-x-stream/blob/52317a3/src/stream.ts#L43)
 
 ___
 
@@ -66,7 +67,7 @@ ___
 
 #### Defined in
 
-[stream.ts:31](https://github.com/calebboyd/redis-x-stream/blob/4a00dad/src/stream.ts#L31)
+[stream.ts:39](https://github.com/calebboyd/redis-x-stream/blob/52317a3/src/stream.ts#L39)
 
 ___
 
@@ -76,21 +77,17 @@ ___
 
 #### Defined in
 
-[stream.ts:32](https://github.com/calebboyd/redis-x-stream/blob/4a00dad/src/stream.ts#L32)
+[stream.ts:40](https://github.com/calebboyd/redis-x-stream/blob/52317a3/src/stream.ts#L40)
 
 ___
 
 ### client
 
 • `Readonly` **client**: `Redis`
 
-'entry' mode will dispense each entry of each stream
-'stream' mode will dispense each stream containing entries
-'batch' mode will dispense all streams with all entries
-
 #### Defined in
 
-[stream.ts:23](https://github.com/calebboyd/redis-x-stream/blob/4a00dad/src/stream.ts#L23)
+[stream.ts:30](https://github.com/calebboyd/redis-x-stream/blob/52317a3/src/stream.ts#L30)
 
 ___
 
@@ -100,7 +97,17 @@ ___
 
 #### Defined in
 
-[stream.ts:25](https://github.com/calebboyd/redis-x-stream/blob/4a00dad/src/stream.ts#L25)
+[stream.ts:33](https://github.com/calebboyd/redis-x-stream/blob/52317a3/src/stream.ts#L33)
+
+___
+
+### control
+
+• `Optional` `Readonly` **control**: `Redis`
+
+#### Defined in
+
+[stream.ts:31](https://github.com/calebboyd/redis-x-stream/blob/52317a3/src/stream.ts#L31)
 
 ___
 
@@ -110,7 +117,7 @@ ___
 
 #### Defined in
 
-[stream.ts:29](https://github.com/calebboyd/redis-x-stream/blob/4a00dad/src/stream.ts#L29)
+[stream.ts:37](https://github.com/calebboyd/redis-x-stream/blob/52317a3/src/stream.ts#L37)
 
 ___
 
@@ -120,7 +127,7 @@ ___
 
 #### Defined in
 
-[stream.ts:36](https://github.com/calebboyd/redis-x-stream/blob/4a00dad/src/stream.ts#L36)
+[stream.ts:44](https://github.com/calebboyd/redis-x-stream/blob/52317a3/src/stream.ts#L44)
 
 ___
 
@@ -132,7 +139,7 @@ Flag for iterable state
 
 #### Defined in
 
-[stream.ts:48](https://github.com/calebboyd/redis-x-stream/blob/4a00dad/src/stream.ts#L48)
+[stream.ts:56](https://github.com/calebboyd/redis-x-stream/blob/52317a3/src/stream.ts#L56)
 
 ___
 
@@ -142,7 +149,7 @@ ___
 
 #### Defined in
 
-[stream.ts:49](https://github.com/calebboyd/redis-x-stream/blob/4a00dad/src/stream.ts#L49)
+[stream.ts:57](https://github.com/calebboyd/redis-x-stream/blob/52317a3/src/stream.ts#L57)
 
 ___
 
@@ -152,7 +159,7 @@ ___
 
 #### Defined in
 
-[stream.ts:24](https://github.com/calebboyd/redis-x-stream/blob/4a00dad/src/stream.ts#L24)
+[stream.ts:32](https://github.com/calebboyd/redis-x-stream/blob/52317a3/src/stream.ts#L32)
 
 ___
 
@@ -162,7 +169,7 @@ ___
 
 #### Defined in
 
-[stream.ts:30](https://github.com/calebboyd/redis-x-stream/blob/4a00dad/src/stream.ts#L30)
+[stream.ts:38](https://github.com/calebboyd/redis-x-stream/blob/52317a3/src/stream.ts#L38)
 
 ___
 
@@ -171,12 +178,12 @@ ___
 • **pendingAcks**: `Map`<`string`, `string`[]\>
 
 Acks waiting to be sent on either:
-- timeout
+- interval
 - async iteration
 
 #### Defined in
 
-[stream.ts:44](https://github.com/calebboyd/redis-x-stream/blob/4a00dad/src/stream.ts#L44)
+[stream.ts:52](https://github.com/calebboyd/redis-x-stream/blob/52317a3/src/stream.ts#L52)
 
 ___
 
@@ -186,7 +193,7 @@ ___
 
 #### Defined in
 
-[stream.ts:28](https://github.com/calebboyd/redis-x-stream/blob/4a00dad/src/stream.ts#L28)
+[stream.ts:36](https://github.com/calebboyd/redis-x-stream/blob/52317a3/src/stream.ts#L36)
 
 ## Methods
 
@@ -200,7 +207,7 @@ ___
 
 #### Defined in
 
-[stream.ts:128](https://github.com/calebboyd/redis-x-stream/blob/4a00dad/src/stream.ts#L128)
+[stream.ts:145](https://github.com/calebboyd/redis-x-stream/blob/52317a3/src/stream.ts#L145)
 
 ___
 
@@ -221,7 +228,7 @@ ___
 
 #### Defined in
 
-[stream.ts:185](https://github.com/calebboyd/redis-x-stream/blob/4a00dad/src/stream.ts#L185)
+[stream.ts:204](https://github.com/calebboyd/redis-x-stream/blob/52317a3/src/stream.ts#L204)
 
 ___
 
@@ -235,7 +242,7 @@ ___
 
 #### Defined in
 
-[stream.ts:174](https://github.com/calebboyd/redis-x-stream/blob/4a00dad/src/stream.ts#L174)
+[stream.ts:190](https://github.com/calebboyd/redis-x-stream/blob/52317a3/src/stream.ts#L190)
 
 ___
 
@@ -249,4 +256,4 @@ ___
 
 #### Defined in
 
-[stream.ts:195](https://github.com/calebboyd/redis-x-stream/blob/4a00dad/src/stream.ts#L195)
+[stream.ts:214](https://github.com/calebboyd/redis-x-stream/blob/52317a3/src/stream.ts#L214)

docs/interfaces/RedisStreamOptions.md

@@ -16,6 +16,7 @@
 - [group](RedisStreamOptions.md#group)
 - [noack](RedisStreamOptions.md#noack)
 - [redis](RedisStreamOptions.md#redis)
+- [redisControl](RedisStreamOptions.md#rediscontrol)
 - [streams](RedisStreamOptions.md#streams)
 
 ## Properties
@@ -33,7 +34,7 @@ false
 
 #### Defined in
 
-[types.ts:71](https://github.com/calebboyd/redis-x-stream/blob/4a00dad/src/types.ts#L71)
+[types.ts:77](https://github.com/calebboyd/redis-x-stream/blob/52317a3/src/types.ts#L77)
 
 ___
 
@@ -46,7 +47,7 @@ while waiting for new entries on any stream, passed to xread or xreadgroup
 
 #### Defined in
 
-[types.ts:65](https://github.com/calebboyd/redis-x-stream/blob/4a00dad/src/types.ts#L65)
+[types.ts:71](https://github.com/calebboyd/redis-x-stream/blob/52317a3/src/types.ts#L71)
 
 ___
 
@@ -59,7 +60,7 @@ This applies to entry id and kv results
 
 #### Defined in
 
-[types.ts:54](https://github.com/calebboyd/redis-x-stream/blob/4a00dad/src/types.ts#L54)
+[types.ts:60](https://github.com/calebboyd/redis-x-stream/blob/52317a3/src/types.ts#L60)
 
 ___
 
@@ -72,7 +73,7 @@ Note: if only consumer is provided, a group is created automatically
 
 #### Defined in
 
-[types.ts:44](https://github.com/calebboyd/redis-x-stream/blob/4a00dad/src/types.ts#L44)
+[types.ts:44](https://github.com/calebboyd/redis-x-stream/blob/52317a3/src/types.ts#L44)
 
 ___
 
@@ -89,7 +90,7 @@ eg. the "highWaterMark"
 
 #### Defined in
 
-[types.ts:60](https://github.com/calebboyd/redis-x-stream/blob/4a00dad/src/types.ts#L60)
+[types.ts:66](https://github.com/calebboyd/redis-x-stream/blob/52317a3/src/types.ts#L66)
 
 ___
 
@@ -106,7 +107,7 @@ false
 
 #### Defined in
 
-[types.ts:77](https://github.com/calebboyd/redis-x-stream/blob/4a00dad/src/types.ts#L77)
+[types.ts:83](https://github.com/calebboyd/redis-x-stream/blob/52317a3/src/types.ts#L83)
 
 ___
 
@@ -121,7 +122,7 @@ TODO: not yet implemented
 
 #### Defined in
 
-[types.ts:89](https://github.com/calebboyd/redis-x-stream/blob/4a00dad/src/types.ts#L89)
+[types.ts:95](https://github.com/calebboyd/redis-x-stream/blob/52317a3/src/types.ts#L95)
 
 ___
 
@@ -134,7 +135,7 @@ Note: if only a group is provided a consumer is created automatically
 
 #### Defined in
 
-[types.ts:39](https://github.com/calebboyd/redis-x-stream/blob/4a00dad/src/types.ts#L39)
+[types.ts:39](https://github.com/calebboyd/redis-x-stream/blob/52317a3/src/types.ts#L39)
 
 ___
 
@@ -150,20 +151,34 @@ false
 
 #### Defined in
 
-[types.ts:82](https://github.com/calebboyd/redis-x-stream/blob/4a00dad/src/types.ts#L82)
+[types.ts:88](https://github.com/calebboyd/redis-x-stream/blob/52317a3/src/types.ts#L88)
 
 ___
 
 ### redis
 
 • `Optional` **redis**: `string` \| `Redis` \| `RedisOptions`
 
-The IORedis client connection.
+The IORedis client connection (reader).
 NOTE: by default this connection becomes a "reader" when block > 0
 
 #### Defined in
 
-[types.ts:49](https://github.com/calebboyd/redis-x-stream/blob/4a00dad/src/types.ts#L49)
+[types.ts:49](https://github.com/calebboyd/redis-x-stream/blob/52317a3/src/types.ts#L49)
+
+___
+
+### redisControl
+
+• `Optional` **redisControl**: `string` \| `Redis` \| `RedisOptions`
+
+The IORedis control client connection (writer).
+NOTE: by default this connection becomes a "writer" when block = 0 or Infinity
+Only allowed if block = 0 or Infinity
+
+#### Defined in
+
+[types.ts:55](https://github.com/calebboyd/redis-x-stream/blob/52317a3/src/types.ts#L55)
 
 ___
 
@@ -175,4 +190,4 @@ Redis stream keys to be read. If a Record is provided each value is the starting
 
 #### Defined in
 
-[types.ts:34](https://github.com/calebboyd/redis-x-stream/blob/4a00dad/src/types.ts#L34)
+[types.ts:34](https://github.com/calebboyd/redis-x-stream/blob/52317a3/src/types.ts#L34)

docs/modules.md

@@ -35,4 +35,4 @@
 
 #### Defined in
 
-[stream.ts:200](https://github.com/calebboyd/redis-x-stream/blob/4a00dad/src/stream.ts#L200)
+[stream.ts:219](https://github.com/calebboyd/redis-x-stream/blob/52317a3/src/stream.ts#L219)

src/redis.ts

@@ -1,7 +1,7 @@
-import { ChainableCommander } from 'ioredis'
+import Redis, { ChainableCommander, RedisOptions } from 'ioredis'
 import { RedisStream } from './stream.js'
 import mkDebug from 'debug'
-import { XBatchResult, XStreamResult } from './types.js'
+import { XBatchResult, XStreamResult, env } from './types.js'
 
 const debug = mkDebug('redis-x-stream')
 
@@ -102,3 +102,23 @@ function xreadgroup(
     ...streams.values()
   )
 }
+
+export function createClient(options?: Redis | string | RedisOptions) {
+  let client: Redis,
+    created = true
+  if (typeof options === 'object') {
+    if ('pipeline' in options) {
+      client = options
+      created = false
+    } else {
+      client = new Redis({ ...options })
+    }
+  } else if (typeof options === 'string') {
+    client = new Redis(options)
+  } else if (env.REDIS_X_STREAM_URL) {
+    client = new Redis(env.REDIS_X_STREAM_URL)
+  } else {
+    client = new Redis()
+  }
+  return { client, created }
+}