ioredis-toolkit 0.0.9 → 0.5.0

package/docs/modules/cache/usage.md

@@ -0,0 +1,156 @@
+# Cache Module — Complete Usage Guide
+
+`RedisCache` is a namespaced JSON cache built on the package's shared `RedisClientWrapper`. It supports TTLs, conditional writes, bounded value sizes, and cluster-aware invalidation.
+
+## 1. Setup
+
+```ts
+import { createRedisClient } from 'ioredis-toolkit';
+
+const redis = createRedisClient({
+  mode: 'standalone',
+  host: '127.0.0.1',
+  port: 6379,
+  cache: {
+    enabled: true,
+    namespace: 'myapp:cache',
+    defaultTtl: 300,
+    maxValueBytes: 1024 * 1024,
+  },
+});
+```
+
+The module uses the same Redis connection as the rest of the package. Do not create a second Redis client just for caching.
+
+`cache.enabled` defaults to `false`. Accessing `redis.cache` while disabled throws `RedisConfigurationError`; set `enabled: true` to use the module.
+
+## 2. Configuration
+
+| Option | Type | Default | Description |
+|---|---|---:|---|
+| `enabled` | `boolean` | `false` | Enables the module. `redis.cache` throws `RedisConfigurationError` while disabled; `new RedisCache(...)` remains directly constructible either way. |
+| `namespace` | `string` | `cache` | Prefix placed before every cache key. |
+| `defaultTtl` | `number` | `300` | Default TTL in seconds. |
+| `maxValueBytes` | `number` | `1048576` | Maximum UTF-8 encoded JSON size. |
+
+## 3. Methods
+
+### `key(key)`
+
+Returns the physical Redis key. Example: `cache:user:42`.
+
+```ts
+redis.cache.key('user:42');
+```
+
+### `get<T>(key)`
+
+Returns `{ hit, value }`. A miss returns `{ hit: false, value: null }`. A cached value that is not valid JSON (for example, written directly by another, non-conforming client) throws a typed `CacheError` rather than crashing with an uncaught `SyntaxError` or silently returning a miss.
+
+```ts
+import { CacheError } from 'ioredis-toolkit';
+
+try {
+  const result = await redis.cache.get<User>('user:42');
+  if (result.hit) console.log(result.value.email);
+} catch (error) {
+  if (error instanceof CacheError) {
+    // The stored value could not be decoded as JSON.
+  }
+}
+```
+
+### `getValue<T>(key)`
+
+Convenience form returning the decoded value or `null`.
+
+```ts
+const user = await redis.cache.getValue<User>('user:42');
+if (!user) {
+  // cache miss
+}
+```
+
+### `set<T>(key, value, options?)`
+
+Stores a JSON value. `ttl` is in seconds. `nx` means create only when absent; `xx` means update only when present. `nx` and `xx` cannot both be true.
+
+```ts
+await redis.cache.set('user:42', { id: '42', name: 'Anwar' }, { ttl: 600 });
+await redis.cache.set('config', { version: 4 }, { nx: true, ttl: 60 });
+await redis.cache.set('config', { version: 5 }, { xx: true, ttl: 60 });
+```
+
+Returns `true` when Redis accepted the write and `false` for a failed NX/XX condition.
+
+### `setIfAbsent<T>(key, value, ttl?)`
+
+Atomic create-if-absent helper.
+
+```ts
+const acquired = await redis.cache.setIfAbsent('job:123', { state: 'queued' }, 30);
+```
+
+### `has(key)`
+
+Checks whether the physical key exists.
+
+```ts
+if (await redis.cache.has('user:42')) {
+  console.log('cached');
+}
+```
+
+### `ttl(key)`
+
+Returns Redis TTL in seconds using normal Redis semantics (`-1` means no expiration and `-2` means missing).
+
+```ts
+const seconds = await redis.cache.ttl('user:42');
+```
+
+### `delete(...keys)` / `del(key)`
+
+Deletes one or more entries. Cluster mode groups keys by Redis hash slot so a cross-slot `DEL` is not issued.
+
+```ts
+await redis.cache.delete('user:1', 'user:2', 'user:3');
+await redis.cache.del('user:4');
+```
+
+### `clear(pattern?)`
+
+Scans the cache namespace and deletes matching entries. It never uses `KEYS` or `FLUSHALL`.
+
+```ts
+await redis.cache.clear();
+await redis.cache.clear('user:*');
+```
+
+For production, keep patterns bounded and avoid calling large namespace clears on latency-sensitive request paths.
+
+## 4. Typed values
+
+The generic parameter describes the value you expect to receive; Redis itself does not store TypeScript type information.
+
+```ts
+type Product = { id: string; price: number };
+await redis.cache.set<Product>('product:1', { id: '1', price: 19.99 });
+const product = await redis.cache.getValue<Product>('product:1');
+```
+
+## 5. Serialization limits
+
+Values must be JSON-serializable. `undefined`, functions, symbols, cyclic structures, and values that cannot be represented by JSON are rejected. The encoded UTF-8 payload must not exceed `maxValueBytes`.
+
+## 6. Per-client overrides
+
+Global configuration can be merged or replaced:
+
+```ts
+redis.withCache({ defaultTtl: 60 });
+// namespace and maxValueBytes remain unchanged.
+
+redis.withCache({ namespace: 'short-cache' }, 'replace');
+// Unspecified values return to module defaults.
+```

package/docs/modules/lock/README.md

@@ -0,0 +1,7 @@
+# Lock module
+
+This directory contains the complete usage documentation for the lock module.
+
+**Full guide:** [usage.md](./usage.md)
+
+The usage guide documents configuration, public types, every public method, arguments, return values, semantics, error/edge-case behavior, and multiple examples.

package/docs/modules/lock/usage.md

@@ -0,0 +1,105 @@
+# Lock Module — Complete Usage Guide
+
+`RedisLock` provides a small distributed-lock primitive based on a random ownership token and atomic compare-and-delete/compare-and-expire Lua operations.
+
+## Setup
+
+```ts
+import { createRedisClient } from 'ioredis-toolkit';
+
+const redis = createRedisClient({
+  mode: 'standalone',
+  host: '127.0.0.1',
+  port: 6379,
+  lock: { enabled: true, namespace: 'myapp:locks', defaultTtl: 30, maxTtl: 300 },
+});
+```
+
+`lock.enabled` defaults to `false`. Accessing `redis.lock` while disabled throws `RedisConfigurationError`; set `enabled: true` to use the module.
+
+## Configuration
+
+| Option | Type | Default | Description |
+|---|---|---:|---|
+| `enabled` | `boolean` | `false` | Enables the module. `redis.lock` throws `RedisConfigurationError` while disabled; `new RedisLock(...)` remains directly constructible either way. |
+| `namespace` | `string` | `lock` | Physical key prefix. |
+| `defaultTtl` | `number` | `30` | Default lease in seconds. Must not exceed `maxTtl`. |
+| `maxTtl` | `number` | `300` | Maximum permitted lease. |
+
+`parseLockConfig()` rejects a configuration where `defaultTtl > maxTtl` at config-parse time, instead of letting every `acquire()`/`extend()` call using the default TTL throw a `RangeError` later.
+
+## Methods
+
+### `key(name)`
+
+Builds the physical lock key.
+
+```ts
+redis.lock.key('order:123'); // lock:order:123
+```
+
+### `acquire(name, ttl?)`
+
+Attempts an atomic `SET ... NX PX`. The returned token proves ownership and must be treated as a secret.
+
+```ts
+const result = await redis.lock.acquire('order:123', 15);
+if (!result.acquired) {
+  return; // another worker owns it
+}
+try {
+  await processOrder();
+} finally {
+  await redis.lock.release('order:123', result.token);
+}
+```
+
+### `release(name, token)`
+
+Deletes the lock only if the current Redis value equals the supplied ownership token. This prevents an expired lock from being deleted by a previous owner.
+
+```ts
+const lock = await redis.lock.acquire('invoice:42');
+if (lock.acquired) await redis.lock.release('invoice:42', lock.token);
+```
+
+### `extend(name, token, ttl?)`
+
+Atomically extends the lease only for the current owner.
+
+```ts
+const lock = await redis.lock.acquire('long-job', 20);
+if (lock.acquired) {
+  await doFirstPart();
+  const extended = await redis.lock.extend('long-job', lock.token, 20);
+  if (!extended) throw new Error('Lock ownership was lost');
+  await doSecondPart();
+  await redis.lock.release('long-job', lock.token);
+}
+```
+
+### `using(name, fn, ttl?)`
+
+Acquires a lock, executes the callback, and releases the lock in `finally`. The callback receives the ownership token so it can extend the lease.
+
+```ts
+const result = await redis.lock.using('report:daily', async token => {
+  // token is available if the job needs an extension.
+  return await generateReport();
+}, 60);
+```
+
+If acquisition fails, `using()` throws instead of executing the callback.
+
+## Important semantics
+
+This is a lease, not a consensus protocol. If the process pauses longer than the TTL, another owner may acquire the lock. Choose TTLs that safely cover the critical section and extend them when necessary.
+
+Do not use the lock as proof that a database transaction committed. Prefer fencing tokens when an external resource requires strict stale-writer protection.
+
+## Overrides
+
+```ts
+redis.withLock({ defaultTtl: 10, maxTtl: 60 });
+redis.withLock({ namespace: 'maintenance' }, 'replace');
+```

package/docs/modules/pubsub/README.md

@@ -0,0 +1,7 @@
+# Pubsub module
+
+This directory contains the complete usage documentation for the pubsub module.
+
+**Full guide:** [usage.md](./usage.md)
+
+The usage guide documents configuration, public types, every public method, arguments, return values, semantics, error/edge-case behavior, and multiple examples.

package/docs/modules/pubsub/usage.md

@@ -0,0 +1,106 @@
+# Pub/Sub Module — Complete Usage Guide
+
+`RedisPubSub` provides JSON Pub/Sub with namespaced channels and a dedicated subscriber connection. Pub/Sub is ephemeral: messages are not persisted for offline subscribers.
+
+## Setup
+
+```ts
+import { createRedisClient } from 'ioredis-toolkit';
+
+const redis = createRedisClient({
+  mode: 'standalone',
+  host: '127.0.0.1',
+  port: 6379,
+  pubsub: { enabled: true, channelPrefix: 'myapp:events', maxMessageBytes: 1024 * 1024 },
+});
+```
+
+`pubsub.enabled` defaults to `false`. Accessing `redis.pubsub` while disabled throws `RedisConfigurationError`; set `enabled: true` to use the module.
+
+## Configuration
+
+| Option | Type | Default | Description |
+|---|---|---:|---|
+| `enabled` | `boolean` | `false` | Enables the module. `redis.pubsub` throws `RedisConfigurationError` while disabled; `new RedisPubSub(...)` remains directly constructible either way. |
+| `channelPrefix` | `string` | `events` | Physical channel prefix. |
+| `maxMessageBytes` | `number` | `1048576` | Maximum encoded JSON message size. |
+
+## Resilience
+
+The dedicated subscriber connection has a default `'error'` listener attached automatically, so a connection drop, auth failure, or network error on it can no longer crash the process with an uncaught exception. Attach your own listener on the connection if you need alerting/observability beyond that default.
+
+A malformed (non-JSON) message delivered on a subscribed channel — for example, published by a non-conforming external client — is silently dropped instead of throwing inside ioredis's `message` event and crashing the process. Handlers are only invoked for messages that parse successfully.
+
+Repeated `subscribe()` calls for the same physical channel issue a single underlying `SUBSCRIBE`; the physical `UNSUBSCRIBE` is only issued once the last logical handler for that channel unsubscribes.
+
+## `publish<T>(channel, value)`
+
+JSON-encodes a value and publishes it. The return value is Redis's subscriber count at publication time.
+
+```ts
+const subscribers = await redis.pubsub.publish('orders.created', {
+  orderId: 'ord_123',
+  userId: 'user_42',
+});
+console.log(`Delivered to ${subscribers} subscribers`);
+```
+
+## `subscribe<T>(channel, handler)`
+
+Creates a logical subscription and returns a `Subscription` handle.
+
+```ts
+const subscription = await redis.pubsub.subscribe<OrderCreated>(
+  'orders.created',
+  message => {
+    console.log(message.channel, message.value.orderId);
+  },
+);
+
+await subscription.unsubscribe();
+```
+
+The callback receives a `PubSubMessage<T>` containing the logical channel and decoded value.
+
+Multiple subscriptions to the same logical channel share the dedicated subscriber connection.
+
+```ts
+const a = await redis.pubsub.subscribe('cache.invalidate', msg => console.log('A', msg.value));
+const b = await redis.pubsub.subscribe('cache.invalidate', msg => console.log('B', msg.value));
+await a.unsubscribe();
+// B remains subscribed.
+await b.unsubscribe();
+```
+
+## `fullChannel(channel)`
+
+Returns the namespaced physical channel.
+
+```ts
+redis.pubsub.fullChannel('orders.created');
+// myapp:events:orders.created
+```
+
+## `close()`
+
+Closes the dedicated subscriber connection. Call it during application shutdown.
+
+```ts
+process.on('SIGTERM', async () => {
+  await redis.pubsub.close();
+  process.exit(0);
+});
+```
+
+## Pub/Sub vs Streams
+
+Use Pub/Sub when losing messages while nobody is listening is acceptable and low-latency fan-out is the priority. Use Streams when messages need persistence, consumer groups, acknowledgements, replay, or controlled processing.
+
+## Overrides
+
+```ts
+redis.withPubSub({ channelPrefix: 'critical' });
+redis.withPubSub({ maxMessageBytes: 256 * 1024 }, 'replace');
+```
+
+When replacing or reconfiguring Pub/Sub, close the previous subscriber connection before relying on the new configuration.

package/docs/modules/rate-limit/README.md

@@ -0,0 +1,7 @@
+# Rate limit module
+
+This directory contains the complete usage documentation for the rate limit module.
+
+**Full guide:** [usage.md](./usage.md)
+
+The usage guide documents configuration, public types, every public method, arguments, return values, semantics, error/edge-case behavior, and multiple examples.

package/docs/modules/rate-limit/usage.md

@@ -0,0 +1,100 @@
+# Rate Limiting Module — Complete Usage Guide
+
+`RedisRateLimiter` implements an atomic fixed-window counter. It is suitable for request, API-key, user, IP, job, or other subject-based quotas.
+
+## Setup
+
+```ts
+import { createRedisClient } from 'ioredis-toolkit';
+
+const redis = createRedisClient({
+  mode: 'standalone',
+  host: '127.0.0.1',
+  port: 6379,
+  rateLimit: {
+    enabled: true,
+    namespace: 'api:limit',
+    windowSeconds: 60,
+    maxRequests: 100,
+  },
+});
+```
+
+`rateLimit.enabled` defaults to `false`. Accessing `redis.rateLimiter` while disabled throws `RedisConfigurationError`; set `enabled: true` to use the module.
+
+## Configuration
+
+| Option | Type | Default | Description |
+|---|---|---:|---|
+| `enabled` | `boolean` | `false` | Enables the module. `redis.rateLimiter` throws `RedisConfigurationError` while disabled; `new RedisRateLimiter(...)` remains directly constructible either way. |
+| `namespace` | `string` | `rate-limit` | Counter key prefix. |
+| `windowSeconds` | `number` | `60` | Fixed-window duration. |
+| `maxRequests` | `number` | `100` | Maximum units per window. |
+
+## Methods
+
+### `key(subject, nowSeconds?)`
+
+Returns the counter key for the current fixed window. Supplying `nowSeconds` makes tests deterministic.
+
+```ts
+redis.rateLimiter.key('user:42', 120); // rate-limit:user:42:2 for a 60s window
+```
+
+### `consume(subject, cost?, nowSeconds?)`
+
+Atomically increments the current window and creates its TTL on the first increment.
+
+```ts
+const decision = await redis.rateLimiter.consume('user:42');
+if (!decision.allowed) {
+  throw new Error(`Rate limited; retry in ${decision.retryAfterSeconds}s`);
+}
+```
+
+Weighted costs are useful for expensive operations:
+
+```ts
+const decision = await redis.rateLimiter.consume('user:42', 5);
+```
+
+### `check(subject, nowSeconds?)`
+
+Reads the current counter without incrementing it.
+
+```ts
+const state = await redis.rateLimiter.check('user:42');
+console.log(state.remaining, state.resetAt);
+```
+
+`check()` is advisory. A concurrent `consume()` can change the result immediately afterward.
+
+### `reset(subject, nowSeconds?)`
+
+Deletes the current window counter.
+
+```ts
+await redis.rateLimiter.reset('user:42');
+```
+
+## Result type
+
+`RateLimitResult` contains:
+
+- `allowed`: whether the operation fits within the limit.
+- `limit`: configured maximum.
+- `remaining`: remaining units, never below zero.
+- `resetAt`: estimated Unix timestamp when the current window expires.
+- `retryAfterSeconds`: TTL to wait when denied, otherwise `0`.
+- `count`: current consumed units.
+
+## Fixed-window behavior
+
+A fixed window can allow bursts at a boundary. For example, a request near the end of one window and another immediately after the boundary count against different windows. If smoother traffic shaping is required, use a different algorithm rather than assuming this module is a sliding-window limiter.
+
+## Overrides
+
+```ts
+redis.withRateLimit({ maxRequests: 500 });
+redis.withRateLimit({ namespace: 'login' }, 'replace');
+```

package/docs/modules/sessions/README.md

@@ -0,0 +1,7 @@
+# Sessions module
+
+This directory contains the complete usage documentation for the sessions module.
+
+**Full guide:** [usage.md](./usage.md)
+
+The usage guide documents configuration, public types, every public method, arguments, return values, semantics, error/edge-case behavior, and multiple examples.