@owlmeans/redis-resource 0.1.18-rc.8 → 0.1.18

package/README.md

@@ -1,92 +1,224 @@
 # @owlmeans/redis-resource
 
-Redis-backed resource with pub/sub and streaming support for real-time features.
-
-## Overview
-
-- `makeRedisResource(alias, dbAlias?)` — creates a Redis resource
-- `RedisResource<T>` — extends `Resource<T>` with `subscribe`, `publish`, `stream`, and `consume`
-- 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
+bun add @owlmeans/redis-resource@^0.1.18
 ```
 
+`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)
 ```
 
-Define typed resource interfaces:
+### 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
+
+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
+}
 
-interface AgentThinkingStream extends RedisResource<AgentThinkingEvent> {}
-interface AgentWatcherPubsub extends RedisResource<AgentWatcherEvent> {}
+// 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<AgentWatcherPubsub>(AGENT_WATCHER_PUBSUB)
+```ts
+const events = context.resource<RedisResource<ProjectEvent>>(PROJECT_EVENT_PUBSUB)
 
-// Publisher side
-await pubsub.publish({ type: 'update', payload: data })
+// producer: one channel per organization entity
+await events.publish({ type: 'updated', projectId }, entityId)
 
-// Subscriber side
-const unsubscribe = await pubsub.subscribe(async (event) => {
-  handleEvent(event)
-})
+// consumer (a socket handler, another service)
+const unsubscribe = await events.subscribe(
+  event => socket.send(JSON.stringify(event)),
+  { channel: entityId }
+)
+socket.on('close', () => { void unsubscribe() })
 ```
 
-Stream events (Redis Streams):
+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
-const stream = context.resource<AgentThinkingStream>(AGENT_THINKING_STREAM)
+### Watch one record
 
-// Producer
-await stream.stream('thinking-key', { step: 'reasoning', content: text })
+```ts
+const unwatch = await cache.watch(id, record => {
+  // the current value on every write; `null` once the key is gone (deleted or expired)
+  render(record)
+}, { once: true })
+```
 
-// Consumer (async generator)
-for await (const event of stream.consume('thinking-key', 'workers', 'worker-1')) {
-  process(event)
+### Streams with a consumer group
+
+```ts
+const thinking = context.resource<RedisResource<ThinkingEvent>>(THINKING_STREAM)
+
+await thinking.stream(`run:${runId}`, { step: 'reasoning', content: text })
+
+for await (const event of thinking.consume(`run:${runId}`, { group: 'renderers', consumer: podName })) {
+  await deliver(event)
 }
 ```
 
-## API
+Without `group`, `consume` tails from now with `XREAD`. With one, it joins the group and reclaims
+stale entries under the consumer name you pass.
 
-### `makeRedisResource(alias, dbAlias?): RedisResource<T>`
+## Reads
 
-Creates a Redis resource. `dbAlias` defaults to `DEFAULT_DB_ALIAS` (`'redis'`).
+`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 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.
 
-### `RedisResource<T>`
+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.
 
-Extends `Resource<T>` with:
-- `subscribe<T>(handler, key?): Promise<() => Promise<void>>` — subscribe to pub/sub channel
-- `publish<T>(value, key?): Promise<void>` — publish to pub/sub channel
-- `stream<T>(key, data): Promise<void>` — append to a Redis Stream
-- `consume<T>(key, group?, consumer?): AsyncGenerator<T>` — consume from a Redis Stream
+## TTL
 
-### Constants
+| `opts.ttl` | Meaning | Command |
+|---|---|---|
+| `number` | seconds from now | `EXPIRE` |
+| `Date` | the absolute instant to expire at | `PEXPIREAT` (milliseconds, which is what `Date.getTime()` gives) |
+| omitted | persistent (`PTTL` reports `-1`) | none |
 
-- `DEFAULT_DB_ALIAS` — `'redis'`
+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.
 
-## Related Packages
+## API
+
+### `makeRedisResource<R, T>(alias, dbAlias?, serviceAlias?): T`
+
+Creates a Redis resource (`T` defaults to `RedisResource<R>`). Both alias arguments default to
+`DEFAULT_DB_ALIAS` (`'redis'`).
+
+### `RedisResource<T>`
 
-- [`@owlmeans/redis`](../redis) — Redis connection service
-- [`@owlmeans/resource`](../resource) — `Resource<T>` base interface
-- [`@owlmeans/server-socket`](../server-socket) — WebSocket handlers often use Redis resources for streaming
+`Resource<T>` plus:
+- `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>`, 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`
+
+`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.
+
+### 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`.
+
+## 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
@@ -96,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
+npx @owlmeans/agent-skills@^0.1.18
 ```
 
 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,
+  "schemaVersion": 3,
   "package": "@owlmeans/redis-resource",
-  "version": "0.1.18-rc.7",
-  "generatedAt": "2026-08-24T21:14:00.126Z",
+  "version": "0.1.18",
+  "generatedAt": "2026-10-28T00:31:34.738Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

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

@@ -1,6 +1,6 @@
 ---
 name: redis-resource
-description: How to use @owlmeans/redis-resource — Redis-backed Resource implementation for caching/state with TTL support. Auto-invoked when defining a resource backed by Redis.
+description: How to use @owlmeans/redis-resource — Redis-backed Resource implementation for caching/state with TTL, pub/sub, keyspace watching and streams. Auto-invoked when defining a resource backed by Redis.
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -8,17 +8,23 @@ user-invocable: false
 # @owlmeans/redis-resource
 
 **Layer:** Infra
-**Install:** `"@owlmeans/redis-resource": "^0.1.18-rc.7"` in `dependencies`
+**Install:** `"@owlmeans/redis-resource": "^0.1.18"` in `dependencies`
 
 ## Key Exports
 
 | Export | Description |
 |--------|-------------|
-| `makeRedisResource<R>(alias, dbAlias?, serviceAlias?, makeCustomResource?)` | Factory for a Redis-backed `Resource<R>`. Both alias defaults are `DEFAULT_DB_ALIAS` (`'redis'`) |
-| `RedisResource<R>`, `RedisDb`, `RedisClient`, `RedisDbService` | Types |
-| `DEFAULT_DB_ALIAS`, `DEFAULT_PAGE_SIZE` | Constants |
-
-Keys are namespaced by the db config's `schema`: `resource.key(id)` → `<prefix>:<id>`.
+| `makeRedisResource<R>(alias, dbAlias?, serviceAlias?)` | Factory for a Redis-backed `Resource<R>`. Both alias defaults are `DEFAULT_DB_ALIAS` (`'redis'`) |
+| `RedisResource<R>` | `Resource<R>` plus the `PubSubResource`, `WatchableResource` and `StreamResource` capabilities, `db`, `name` and `key(id?)` |
+| `RedisDb`, `RedisClient`, `RedisDbService`, `RedisConnection` | The db and connection contracts — `@owlmeans/redis` implements them |
+| `DEFAULT_DB_ALIAS`, `DEFAULT_PAGE_SIZE`, `SCAN_BATCH`, `READ_BATCH` | Constants for the record half |
+| `STREAM_MAX_LENGTH`, `DEFAULT_STREAM_BLOCK`, `RECLAIM_IDLE`, `RECLAIM_COUNT`, `CONSUMER_ID_LENGTH` | Constants for the stream half |
+
+Keys are namespaced by the db config's key prefix plus the resource's name:
+`resource.key(id)` → `<prefix>-<name>:<id>`, and `key()` with no argument yields the namespace's
+glob. The name is `resource.name` when set and the registration alias otherwise, so two resources
+can share one namespace deliberately — and a `name` given by accident quietly merges two id spaces.
+Every non-word character in either half is collapsed to `_`.
 
 ## Usage
 
@@ -27,47 +33,106 @@ import { makeRedisResource } from '@owlmeans/redis-resource'
 
 context.registerResource(makeRedisResource<SessionData>('sessions'))
 
+// Type the RESOURCE once — never a method
 const sessions = context.resource<RedisResource<SessionData>>('sessions')
 await sessions.create({ id, token }, { ttl: 3600 })   // seconds, or a Date
+const live = await sessions.load({ token })           // criteria, not just an id
 ```
 
-TTL is a **per-call option** on `create`/`update`, not a property of the factory. The prefix
-comes from the `dbs[]` config entry (`schema`), not from the resource.
+TTL is a **per-call option** on `create` / `update` / `save`, not a property of the factory. The
+prefix comes from the `dbs[]` config entry (`schema`), not from the resource.
+
+## Reads: one key is cheap, everything else is a walk
+
+`load(id)`, `get(id)`, `delete(id)`, `take(id)` are single-key commands.
+
+`load(where)`, `get(where)`, `list`, `count` and `purge` walk the resource's **own namespace** with
+`SCAN` + `MGET` and evaluate the criteria in memory with `firstMatch` / `filterRecords` /
+`applyQuery` from `@owlmeans/resource` — the same engine every other store without a query planner
+uses, so a criteria object means here exactly what it means in SQL. That is O(N) over the
+namespace, and `{ sort }` orders the records after the walk, not in redis.
+
+- Use it for a small namespaced set — a session cache, an OTP store, an adapter store.
+- Never for an unbounded keyspace or a hot path. A resource that needs real queries belongs in
+  mongo or postgres.
+- `SCAN`, never `KEYS`: `KEYS` blocks the server for the whole sweep.
+- The walk reaches one server, so `list` / `count` / `purge` are **not cluster-safe**. In a
+  clustered deployment stay on the by-id operations.
+- `load({ id })` is recognised and answered by key — the walk only starts for a real criteria.
+- A key in the namespace holding something other than a string — this resource's own streams
+  included — reads back as `null` from `MGET` and is skipped, so a stream never shows up as a
+  record.
+
+## Paging
+
+Redis is **UNPAGED**: `DEFAULT_PAGE_SIZE` is `0`, `list(where)` with no `size` returns every match,
+and `ListResult.total` always counts every match. `list(where, { page })` without a `size` throws
+`UnsupportedArgumentError('page-without-size')` — there is no implied default to take a window of.
 
 ## TTL
 
 | `opts.ttl` | Meaning | Command |
 |---|---|---|
-| `number` / numeric `string` | seconds from now | `EXPIRE` |
+| `number` | seconds from now | `EXPIRE` |
 | `Date` | the absolute instant to expire at | `PEXPIREAT` (milliseconds — what `Date.getTime()` gives) |
 | omitted | persistent (`PTTL` reports `-1`) | — |
 
-A `Date` already in the past drops the record immediately. `update` re-applies the TTL, so a
-renewal must pass one again — otherwise the key keeps whatever expiry it had.
+A `Date` already in the past drops the record immediately. `update` and `save` rewrite the key, so
+a renewal must pass a TTL again — otherwise the record becomes persistent.
 
 ## Rules
 
-- `delete(id)` — the plain by-id form — is the normal call and must remove the key. It returns the
-  removed record, or `null` when the id was not there. `pick(id)` is delete-and-return that
-  *throws* `UnknownRecordError` when the key is gone; choose by whether absence is an error.
-- `create` throws `RecordExists` when the id is present. For an upsert, use `save` (load → update
-  or create) rather than delete-then-create; the latter turns any lost delete into a hard failure
-  on the next write.
-- `load` rejects an `opts` argument (`UnsupportedArgumentError`) — pass only `id` and an optional
-  field name.
-- `list` walks `KEYS <prefix>:*`. Fine for small, namespaced sets; never for a hot path or an
-  unbounded keyspace.
-- `subscribe` relies on keyspace notifications, which are bound to **db 0** — deployments sharing
-  one instance must isolate on the key prefix, not on the db index.
-- Assert an expiry by reading `PTTL` back from redis, never by trusting that a command was issued —
-  the unit bug this contract had still "set an expiry", just one ~50 millennia away.
-
-## Depends On
-
-- `@owlmeans/redis`, `@owlmeans/resource`, `@owlmeans/server-context`
+- `delete(id)` returns the removed record or `null`; `take(id)` is the same read but **throws**
+  `UnknownRecordError` when the key is gone. Both use `GETDEL`, so two callers can never be handed
+  the same record. Choose by whether absence is an error.
+- `create` generates an id when the record carries none, and refuses an id that is already there
+  (`RecordExists`) using `SET NX` — no read-then-write race. The id is written into the stored
+  record, so what comes back always carries one.
+- `update` **replaces** the whole record and throws `UnknownRecordError` for an unknown id (and
+  `MisshapedRecord` when the record carries no id at all). It does not merge over what was stored;
+  pass every field that must survive.
+- `save` creates when the record carries no id and replaces otherwise — that is the upsert.
+- `purge(where)` refuses an empty criteria object. Use it instead of a page loop that deletes each
+  item.
+- `publish(value, channel?)` / `subscribe(handler, { channel?, once?, ttl? })` are channel pub/sub;
+  the channel name is namespaced like a key, and an omitted channel listens to the resource's whole
+  namespace. `watch(id, handler, { once?, ttl? })` is the keyspace-notification form for ONE
+  record — the handler receives the current value on every write, and `null` once the key is gone.
+  They are separate methods; a channel is never passed as a bare string.
+- `watch` subscribes to `__keyspace@0__:`, while redis publishes keyspace events per database as
+  `__keyspace@<db>__:`. So a resource on a connection whose `meta.dbIndex` is anything but 0 gets
+  no notifications at all and its `watch` handler silently never fires — deployments sharing one
+  instance isolate on the key prefix, not on the db index. The server also needs
+  `notify-keyspace-events` enabled; it emits nothing otherwise.
+- `stream(key, value)` appends to a namespaced redis stream, trimmed approximately to
+  `STREAM_MAX_LENGTH` so trimming stays cheap. `consume(key, { group?, consumer?, block? })` is the
+  async generator that reads it — with no `group` it tails from now with `XREAD`, with one it joins
+  the consumer group and reclaims stale entries under the **passed** consumer name. Claiming them
+  for a fixed name leaves them owned by a consumer that never reads.
+- Requires redis 6.2 or newer (`GETDEL`).
+- Assert an expiry by reading `PTTL` back from redis, never by trusting that a command was issued.
+  An expiry set in the wrong unit is still an expiry — just one tens of millennia out — so only the
+  value redis reports back proves anything.
 
 ## Tests
 
 Integration specs live in the `@owlmeans/redis` package's own `tests/` — the db package that backs
 this contract; putting them here would need a devDependency on this package's own dependent.
-Gated on `REDIS_URL` (see `/.env.example`); each suite namespaces its keys and flushes them.
+Gated on `REDIS_URL` (see `/.env.example`); each suite namespaces its keys and flushes them, and a
+spec that walks the namespace boots under its own resource alias so it never sees another test's
+records.
+
+## Depends On
+
+- `@owlmeans/resource` · `@owlmeans/context` · `@owlmeans/server-context` · `@owlmeans/basic-ids`
+- peer `ioredis` (the client types every method is written against), `ajv`
+
+`@owlmeans/redis` is NOT a dependency — it depends on this package, and that is the direction the
+connection contracts flow in.
+
+## Related
+
+- `redis` — the connection service implementing `RedisDbService`, and the `cfg.dbs` entry a
+  resource takes its prefix and db index from
+- `redis-queue` — BullMQ queues on the same connections
+- `resource` — the criteria language, paging and the error classes raised here

package/build/consts.d.ts

@@ -1,3 +1,22 @@
 export declare const DEFAULT_DB_ALIAS = "redis";
-export declare const DEFAULT_PAGE_SIZE = 10;
+/**
+ * Redis is UNPAGED: `list()` without a `size` returns every match, and `0` says exactly that.
+ * There is no server side LIMIT to fall back on — answering a criteria already walked the whole
+ * namespace — so an implied default would only hide records without saving any work.
+ */
+export declare const DEFAULT_PAGE_SIZE = 0;
+/** Keys per SCAN round trip. Bounded so one sweep never blocks the server the way KEYS does. */
+export declare const SCAN_BATCH = 200;
+/** Keys per MGET / DEL round trip once SCAN has collected them. */
+export declare const READ_BATCH = 200;
+/** Entries kept in a stream, trimmed approximately (`MAXLEN ~`) so trimming stays O(1)-ish. */
+export declare const STREAM_MAX_LENGTH = 10000;
+/** How long a stream read blocks before the consumer loops and looks for pending entries. */
+export declare const DEFAULT_STREAM_BLOCK = 1000;
+/** How long an unacknowledged entry may sit with its consumer before another may reclaim it. */
+export declare const RECLAIM_IDLE = 60000;
+/** Entries reclaimed per XAUTOCLAIM pass. */
+export declare const RECLAIM_COUNT = 10;
+/** Length of the generated consumer name when `consume` is not given one. */
+export declare const CONSUMER_ID_LENGTH = 15;
 //# sourceMappingURL=consts.d.ts.map

package/build/consts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,gBAAgB,UAAU,CAAA;AAEvC,eAAO,MAAM,iBAAiB,KAAK,CAAA"}
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,gBAAgB,UAAU,CAAA;AAEvC;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,IAAI,CAAA;AAElC,gGAAgG;AAChG,eAAO,MAAM,UAAU,MAAM,CAAA;AAE7B,mEAAmE;AACnE,eAAO,MAAM,UAAU,MAAM,CAAA;AAE7B,+FAA+F;AAC/F,eAAO,MAAM,iBAAiB,QAAQ,CAAA;AAEtC,6FAA6F;AAC7F,eAAO,MAAM,oBAAoB,OAAO,CAAA;AAExC,gGAAgG;AAChG,eAAO,MAAM,YAAY,QAAQ,CAAA;AAEjC,6CAA6C;AAC7C,eAAO,MAAM,aAAa,KAAK,CAAA;AAE/B,6EAA6E;AAC7E,eAAO,MAAM,kBAAkB,KAAK,CAAA"}

package/build/consts.js

@@ -1,3 +1,22 @@
 export const DEFAULT_DB_ALIAS = 'redis';
-export const DEFAULT_PAGE_SIZE = 10;
+/**
+ * Redis is UNPAGED: `list()` without a `size` returns every match, and `0` says exactly that.
+ * There is no server side LIMIT to fall back on — answering a criteria already walked the whole
+ * namespace — so an implied default would only hide records without saving any work.
+ */
+export const DEFAULT_PAGE_SIZE = 0;
+/** Keys per SCAN round trip. Bounded so one sweep never blocks the server the way KEYS does. */
+export const SCAN_BATCH = 200;
+/** Keys per MGET / DEL round trip once SCAN has collected them. */
+export const READ_BATCH = 200;
+/** Entries kept in a stream, trimmed approximately (`MAXLEN ~`) so trimming stays O(1)-ish. */
+export const STREAM_MAX_LENGTH = 10000;
+/** How long a stream read blocks before the consumer loops and looks for pending entries. */
+export const DEFAULT_STREAM_BLOCK = 1000;
+/** How long an unacknowledged entry may sit with its consumer before another may reclaim it. */
+export const RECLAIM_IDLE = 60000;
+/** Entries reclaimed per XAUTOCLAIM pass. */
+export const RECLAIM_COUNT = 10;
+/** Length of the generated consumer name when `consume` is not given one. */
+export const CONSUMER_ID_LENGTH = 15;
 //# sourceMappingURL=consts.js.map

package/build/consts.js.map

@@ -1 +1 @@
-{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,MAAM,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAA;AAEvC,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAA"}
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAA;AAEvC;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAA;AAElC,gGAAgG;AAChG,MAAM,CAAC,MAAM,UAAU,GAAG,GAAG,CAAA;AAE7B,mEAAmE;AACnE,MAAM,CAAC,MAAM,UAAU,GAAG,GAAG,CAAA;AAE7B,+FAA+F;AAC/F,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,CAAA;AAEtC,6FAA6F;AAC7F,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,CAAA;AAExC,gGAAgG;AAChG,MAAM,CAAC,MAAM,YAAY,GAAG,KAAK,CAAA;AAEjC,6CAA6C;AAC7C,MAAM,CAAC,MAAM,aAAa,GAAG,EAAE,CAAA;AAE/B,6EAA6E;AAC7E,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,CAAA"}

package/build/resource.d.ts

@@ -1,4 +1,13 @@
-import type { ResourceMaker, ResourceRecord } from '@owlmeans/resource';
+import { type ResourceRecord } from '@owlmeans/resource';
 import type { RedisResource } from './types.js';
-export declare const makeRedisResource: <R extends ResourceRecord, T extends RedisResource<R> = RedisResource<R>>(alias: string, dbAlias?: string, serviceAlias?: string, makeCustomResource?: ResourceMaker<R, T>) => T;
+/**
+ * A `Resource` over plain redis strings: one JSON document per namespaced key.
+ *
+ * Reads by id are O(1) GETs. Everything else — a criteria read, a listing, a count, a purge —
+ * walks this resource's OWN namespace with SCAN and evaluates the criteria in memory, because
+ * redis has no index to ask. That is affordable for a small namespaced set (a session cache, an
+ * adapter store) and wrong for anything unbounded or hot; a resource that needs real queries
+ * belongs in mongo or postgres.
+ */
+export declare const makeRedisResource: <R extends ResourceRecord, T extends RedisResource<R> = RedisResource<R>>(alias: string, dbAlias?: string, serviceAlias?: string) => T;
 //# sourceMappingURL=resource.d.ts.map

package/build/resource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../src/resource.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAEvE,OAAO,KAAK,EAA+B,aAAa,EAAE,MAAM,YAAY,CAAA;AAW5E,eAAO,MAAM,iBAAiB,GAC5B,CAAC,SAAS,cAAc,EAAE,CAAC,SAAS,aAAa,CAAC,CAAC,CAAC,4BAE7C,MAAM,gEACQ,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,KACvC,CA0WF,CAAA"}
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../src/resource.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuE,KAAK,cAAc,EAAwK,MAAM,oBAAoB,CAAA;AAGnS,OAAO,KAAK,EAAkB,aAAa,EAAE,MAAM,YAAY,CAAA;AAY/D;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,GAC5B,CAAC,SAAS,cAAc,EAAE,CAAC,SAAS,aAAa,CAAC,CAAC,CAAC,4BAE7C,MAAM,8CACZ,CAgaF,CAAA"}