@owlmeans/redis-resource 0.1.18-rc.20 → 0.1.18-rc.22

package/README.md

@@ -1,139 +1,224 @@
 # @owlmeans/redis-resource
 
-Redis-backed resource with pub/sub, keyspace watching and streams for real-time features.
-
-## Overview
-
-- `makeRedisResource(alias, dbAlias?, serviceAlias?)` — creates a Redis resource
-- `RedisResource<T>` — `Resource<T>` composed with `PubSubResource`, `WatchableResource` and
-  `StreamResource`
-- One JSON document per namespaced key: `resource.key(id)` → `<schema>-<alias>:<id>`
-- Used for authentication caches, pub/sub channels, and async event streams
+Redis-backed `Resource<T>` for server apps, with pub/sub, keyspace watching and streams. Use it
+when data has a Redis-shaped property:
+- **Expiry**: sessions, OTPs, nonces, idempotency keys.
+- **Cache**: a miss must stay invisible to the user.
+- **Lock or counter.**
+- **Fan-out between processes**: pub/sub channels and streams.
+
+It is never the source of truth, and it does not fit an unbounded keyspace, because anything other
+than a read by id walks the namespace. Records the product queries belong in
+[`@owlmeans/postgres-resource`](../postgres-resource) or
+[`@owlmeans/mongo-resource`](../mongo-resource). Job queues are
+[`@owlmeans/queue`](../queue) with [`@owlmeans/redis-queue`](../redis-queue).
 
 ## Installation
 
 ```bash
-bun add @owlmeans/redis-resource@^0.1.18-rc.11
+bun add @owlmeans/redis-resource@^0.1.18-rc.21
 ```
 
+`ioredis` and `ajv` are peer dependencies. The connection service comes from
+[`@owlmeans/redis`](../redis) (`appendRedis`).
+
+## Concepts
+
+- **Namespace**: each record is one JSON document under `<prefix>-<name>:<id>`. The prefix comes
+  from the `cfg.dbs` entry's `schema`; the name is `resource.name` or the registration alias.
+  `resource.key(id)` builds a key, and `key()` gives the namespace glob.
+- **By-id vs walk**: `load(id)`, `get(id)`, `delete(id)` and `take(id)` are single-key commands.
+  `load(where)`, `list`, `count` and `purge` `SCAN` the namespace and evaluate criteria in memory.
+- **TTL**: a per-call write option. A number is seconds from now and a `Date` is an absolute
+  instant. It is not a property of the resource, and every rewrite must pass it again.
+- **Channel** (`publish`/`subscribe`): namespaced pub/sub between processes. **Watch** follows
+  one key through keyspace notifications.
+- **Stream** (`stream`/`consume`): an append-only Redis Stream, trimmed to `STREAM_MAX_LENGTH`,
+  read by tailing or through a consumer group.
+- **Unpaged**: `list(where)` returns every match. A `page` requires a `size`.
+
 ## Usage
 
-Register Redis resources in context setup:
+### Register and type once
 
-```typescript
+```ts
 import { makeRedisResource } from '@owlmeans/redis-resource'
+import type { RedisResource } from '@owlmeans/redis-resource'
 import { AUTH_CACHE } from '@owlmeans/server-auth'
 
+// in the server context factory, after appendRedis(context)
 context.registerResource(makeRedisResource(AUTH_CACHE))
-context.registerResource(makeRedisResource(AGENT_THINKING_STREAM))
-context.registerResource(makeRedisResource(AGENT_WATCHER_PUBSUB))
+context.registerResource(makeRedisResource<ResetToken>(RES_RESET_TOKEN))
+context.registerResource(makeRedisResource<ProjectEvent>(PROJECT_EVENT_PUBSUB))
+
+// type the RESOURCE where it is taken out of the context, never per method call
+const tokens = context.resource<RedisResource<ResetToken>>(RES_RESET_TOKEN)
 ```
 
-Type the resource once, at the point it is taken out of the context:
+### Expiring, single-use records
 
-```typescript
-import type { RedisResource } from '@owlmeans/redis-resource'
+```ts
+const created = await tokens.create({ userId, email }, { ttl: 15 * 60 })  // id generated, SET NX
+const byEmail = await tokens.load({ email })                              // walks the namespace
 
-const cache = context.resource<RedisResource<SessionData>>(AUTH_CACHE)
+try {
+  const token = await tokens.take(tokenId)                                // GETDEL: one caller only
+  await resetPassword(token.userId, password)
+} catch (error) {
+  if (error instanceof UnknownRecordError) {
+    throw new LinkExpired()                                               // already used or expired
+  }
+  throw error
+}
 
-await cache.create({ id, token }, { ttl: 3600 })   // seconds, or a Date
-const session = await cache.load({ token })        // criteria, not just an id
-await cache.take(id)                               // delete-and-return
+// a renewal rewrites the key, so it must carry the TTL again
+await sessions.update({ ...session, seenAt: Date.now() }, { ttl: 3600 })
 ```
 
-Publish and subscribe:
+`UnknownRecordError` comes from `@owlmeans/resource`; `LinkExpired` stands for an app error.
+
+### Pub/sub between processes
 
-```typescript
-const pubsub = context.resource<RedisResource<AgentWatcherEvent>>(AGENT_WATCHER_PUBSUB)
+```ts
+const events = context.resource<RedisResource<ProjectEvent>>(PROJECT_EVENT_PUBSUB)
 
-await pubsub.publish({ type: 'update', payload: data }, channel)
+// producer: one channel per organization entity
+await events.publish({ type: 'updated', projectId }, entityId)
 
-const unsubscribe = await pubsub.subscribe(
-  event => handleEvent(event), { channel, once: true }
+// consumer (a socket handler, another service)
+const unsubscribe = await events.subscribe(
+  event => socket.send(JSON.stringify(event)),
+  { channel: entityId }
 )
+socket.on('close', () => { void unsubscribe() })
 ```
 
-Watch one record for changes (keyspace notifications):
+A shared bus is just a fixed channel name (`publish(event, 'bus')`,
+`subscribe(handler, { channel: 'bus' })`). Omitting the channel on `subscribe` listens to the
+resource's whole namespace.
 
-```typescript
+### Watch one record
+
+```ts
 const unwatch = await cache.watch(id, record => {
-  // `null` once the key is gone — deleted or expired
+  // the current value on every write; `null` once the key is gone (deleted or expired)
   render(record)
 }, { once: true })
 ```
 
-Stream events (Redis Streams):
+### Streams with a consumer group
 
-```typescript
-const stream = context.resource<RedisResource<AgentThinkingEvent>>(AGENT_THINKING_STREAM)
+```ts
+const thinking = context.resource<RedisResource<ThinkingEvent>>(THINKING_STREAM)
 
-await stream.stream('thinking-key', { step: 'reasoning', content: text })
+await thinking.stream(`run:${runId}`, { step: 'reasoning', content: text })
 
-for await (const event of stream.consume('thinking-key', { group: 'workers', consumer: 'worker-1' })) {
-  process(event)
+for await (const event of thinking.consume(`run:${runId}`, { group: 'renderers', consumer: podName })) {
+  await deliver(event)
 }
 ```
 
+Without `group`, `consume` tails from now with `XREAD`. With one, it joins the group and reclaims
+stale entries under the consumer name you pass.
+
 ## Reads
 
 `load(id)` / `get(id)` / `delete(id)` / `take(id)` are O(1) commands on one key. `load({ ... })`,
 `get({ ... })`, `list`, `count` and `purge` walk this resource's **own namespace** with `SCAN`
 (never `KEYS`, which blocks the server for the whole sweep), read the values with `MGET`, and
-evaluate the criteria in memory. That is O(N) over the namespace: right for a small namespaced set
-— a session cache, an adapter store — and wrong for anything unbounded or on a hot path. A
-resource that needs real queries belongs in `@owlmeans/mongo-resource` or
-`@owlmeans/postgres-resource`.
+evaluate the criteria in memory with the engine from `@owlmeans/resource`. That is O(N) over the
+namespace: right for a small namespaced set, such as a session cache or an adapter store, and wrong
+for anything unbounded or on a hot path. `load({ id })` is recognised and answered by key.
 
 Redis is **unpaged**: `list(where)` with no `size` returns every match, and `list(where, { page })`
 without a `size` throws `UnsupportedArgumentError('page-without-size')`. `ListResult.total` always
 counts every match.
 
-The namespace walk reaches one server, so `list` / `count` / `purge` are not cluster-safe — in a
-clustered deployment use the by-id operations only.
+The namespace walk reaches one server, so `list` / `count` / `purge` are not cluster-safe. In a
+clustered deployment, use the by-id operations only.
 
 ## TTL
 
 | `opts.ttl` | Meaning | Command |
 |---|---|---|
 | `number` | seconds from now | `EXPIRE` |
-| `Date` | the absolute instant to expire at | `PEXPIREAT` (milliseconds — what `Date.getTime()` gives) |
-| omitted | persistent (`PTTL` reports `-1`) | — |
+| `Date` | the absolute instant to expire at | `PEXPIREAT` (milliseconds, which is what `Date.getTime()` gives) |
+| omitted | persistent (`PTTL` reports `-1`) | none |
 
 A `Date` already in the past drops the record immediately. `update` and `save` rewrite the key, so
-a renewal has to pass its TTL again — otherwise the record becomes persistent.
+a renewal has to pass its TTL again. Otherwise the record becomes persistent.
 
 ## API
 
-### `makeRedisResource<R>(alias, dbAlias?, serviceAlias?): RedisResource<R>`
+### `makeRedisResource<R, T>(alias, dbAlias?, serviceAlias?): T`
 
-Creates a Redis resource. Both alias arguments default to `DEFAULT_DB_ALIAS` (`'redis'`).
+Creates a Redis resource (`T` defaults to `RedisResource<R>`). Both alias arguments default to
+`DEFAULT_DB_ALIAS` (`'redis'`).
 
 ### `RedisResource<T>`
 
 `Resource<T>` plus:
-- `publish(value, channel?): Promise<void>` — publish to a namespaced pub/sub channel
-- `subscribe(handler, { channel?, once?, ttl? }): Promise<Unsubscribe>` — channel pub/sub
-- `watch(id, handler, { once?, ttl? }): Promise<Unsubscribe>` — keyspace notifications for ONE
-  record; the handler is given `null` once the key is gone. Bound to **db 0**, so deployments
+- `publish(value, channel?): Promise<void>`, which publishes to a namespaced pub/sub channel
+- `subscribe(handler, { channel?, once?, ttl? }): Promise<Unsubscribe>`, channel pub/sub
+- `watch(id, handler, { once?, ttl? }): Promise<Unsubscribe>`, keyspace notifications for ONE
+  record. The handler is given `null` once the key is gone. It is bound to **db 0**, so deployments
   sharing an instance isolate on the key prefix, and the server needs `notify-keyspace-events`
-- `stream(key, value): Promise<void>` — append to a Redis Stream
-- `consume(key, { group?, consumer?, block? }): AsyncGenerator<T>` — consume from a Redis Stream
-- `key(key?): string` — the namespaced key, or the namespace's glob
+- `stream(key, value): Promise<void>`, which appends to a Redis Stream
+- `consume(key, { group?, consumer?, block? }): AsyncGenerator<T>`, which consumes from a Redis Stream
+- `key(key?): string`, the namespaced key, or the namespace's glob
+- `db: RedisDb`, `name?: string`
 
-### Constants
+`create` generates an id when none is given and refuses an existing one (`RecordExists`, via
+`SET NX`). `update` replaces the whole record and throws `UnknownRecordError` for an unknown id.
+`save` is the upsert. `delete` returns the removed record or `null`; `take` throws when the key is
+gone. `purge` refuses an empty criteria object.
 
-- `DEFAULT_DB_ALIAS` — `'redis'`
-- `DEFAULT_PAGE_SIZE` — `0`, meaning unpaged
+### Exports
+
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `makeRedisResource` | function | The resource factory |
+| `RedisResource<T>` | type | `Resource<T>` + `PubSubResource`, `WatchableResource`, `StreamResource`, `db`, `name`, `key` |
+| `RedisDbService` | type | Connection service contract implemented by `@owlmeans/redis`, including `options(alias?)` |
+| `RedisConnection` | type | Single-node or cluster connection settings plus the key prefix |
+| `RedisDb`, `RedisClient` | type | `{ client, prefix }` and `Redis \| Cluster` |
+| `DEFAULT_DB_ALIAS` | const | `'redis'` |
+| `DEFAULT_PAGE_SIZE` | const | `0`, meaning unpaged |
+| `SCAN_BATCH`, `READ_BATCH` | const | Keys per `SCAN` and per `MGET`/`DEL` round trip (200) |
+| `STREAM_MAX_LENGTH` | const | Approximate stream trim length (10 000) |
+| `DEFAULT_STREAM_BLOCK` | const | Stream read block time in ms (1 000) |
+| `RECLAIM_IDLE`, `RECLAIM_COUNT` | const | When (60 000 ms idle) and how many (10) pending entries a consumer reclaims |
+| `CONSUMER_ID_LENGTH` | const | Length of a generated consumer name (15) |
 
 ## Requirements
 
 Redis 6.2 or newer: `delete` and `take` use `GETDEL`.
 
-## Related Packages
-
-- [`@owlmeans/redis`](../redis) — Redis connection service
-- [`@owlmeans/resource`](../resource) — `Resource<T>` base interface and the criteria engine
-- [`@owlmeans/server-socket`](../server-socket) — WebSocket handlers often use Redis resources for streaming
+## Common pitfalls
+
+- **Using it as a source of truth.** If losing the record changes behaviour, it belongs in the
+  database.
+- **Criteria reads on a large or unbounded namespace.** `load(where)`, `list`, `count` and `purge`
+  are O(N) walks, unpaged and not cluster-safe.
+- **Renewing without a TTL.** `update`/`save` rewrite the key and the record becomes permanent.
+- **Expecting `update` to merge.** It replaces the whole record.
+- **Setting `resource.name` by accident.** Two resources with the same name share one id space.
+- **`watch` on a connection with `meta.dbIndex` other than 0**, or on a server without
+  `notify-keyspace-events`. The handler silently never fires.
+- **Claiming stream entries under a fixed consumer name.** Pass the real consumer name to
+  `consume`, or entries end up owned by a consumer that never reads.
+- **Asserting an expiry by trusting the command.** Read `PTTL` back; a TTL set in the wrong unit is
+  still an expiry, just millennia out.
+- **Simulating a queue with lists or streams.** Retried, restart-safe work is
+  `@owlmeans/queue`.
+
+## Related packages
+
+- [`@owlmeans/redis`](../redis): the Redis connection service and the `cfg.dbs` entry the prefix comes from
+- [`@owlmeans/resource`](../resource): `Resource<T>`, the criteria engine, the capability interfaces
+- [`@owlmeans/redis-queue`](../redis-queue): BullMQ queues on the same connections
+- [`@owlmeans/server-socket`](../server-socket): socket handlers that relay pub/sub and stream events
+- [`@owlmeans/postgres-resource`](../postgres-resource): where durable records live
 
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance
@@ -143,7 +228,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills@^0.1.18-rc.20
+npx @owlmeans/agent-skills@^0.1.18-rc.22
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/redis-resource",
-  "version": "0.1.18-rc.20",
-  "generatedAt": "2026-09-12T14:21:25.465Z",
+  "version": "0.1.18-rc.22",
+  "generatedAt": "2026-09-15T12:38:15.189Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/redis-resource/SKILL.md

@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/redis-resource
 
 **Layer:** Infra
-**Install:** `"@owlmeans/redis-resource": "^0.1.18-rc.20"` in `dependencies`
+**Install:** `"@owlmeans/redis-resource": "^0.1.18-rc.22"` in `dependencies`
 
 ## Key Exports
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/redis-resource",
-  "version": "0.1.18-rc.20",
+  "version": "0.1.18-rc.22",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -25,10 +25,10 @@
     "ioredis": "*"
   },
   "dependencies": {
-    "@owlmeans/basic-ids": "^0.1.18-rc.17",
-    "@owlmeans/context": "^0.1.18-rc.16",
-    "@owlmeans/resource": "^0.1.18-rc.17",
-    "@owlmeans/server-context": "^0.1.18-rc.20"
+    "@owlmeans/basic-ids": "^0.1.18-rc.19",
+    "@owlmeans/context": "^0.1.18-rc.18",
+    "@owlmeans/resource": "^0.1.18-rc.19",
+    "@owlmeans/server-context": "^0.1.18-rc.22"
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",