@alxia/redis 0.1.3 → 0.3.0

package/README.md

@@ -1,17 +1,19 @@
 # @alxia/redis
 
 Redis for [alxia](https://www.npmjs.com/package/@alxia/core), on
-[`@nxgt/redis`](https://www.npmjs.com/package/@nxgt/redis) and
-[`@nxgt/redis-guard`](https://www.npmjs.com/package/@nxgt/redis-guard) —
+[`@nxgt/redis`](https://www.npmjs.com/package/@nxgt/redis) —
 Bun's own Redis client, no driver, no dependency:
 
 - `redisStore`: a rate-limit store every process shares;
-- `idempotency`: routes that run once per `Idempotency-Key`;
+- `idempotency`: a middleware, so routes run once per `Idempotency-Key`;
 - `redisCacheStore`: an `@alxia/cache` store every process shares;
-- `redis`: the client, typed caches and a lock in the context.
+- `redis`: the client, typed caches and a lock in the context;
+- `redisCheck`: a readiness check for core's `health()`.
+
+Each takes Bun's `RedisClient`, or an [`@nxgt/redis`](https://www.npmjs.com/package/@nxgt/redis) handle: see [With @nxgt/redis](#with-nxgtredis).
 
 ```sh
-bun add @alxia/redis @nxgt/redis @nxgt/redis-guard zod @alxia/core
+bun add @alxia/redis @nxgt/redis zod @alxia/core
 bun add -d typescript
 ```
 
@@ -68,7 +70,7 @@ the response: the route runs, and the error is logged.
 ## Idempotent routes
 
 ```ts
-import { alxia } from '@alxia/core';
+import { alxia, validate } from '@alxia/core';
 import { idempotency } from '@alxia/redis';
 import { connectRedis } from '@nxgt/redis';
 import { z } from 'zod';
@@ -78,7 +80,7 @@ const Payment = z.object({ amount: z.number().int().positive() });
 
 const app = alxia()
 	.use(idempotency(connection.client, { name: 'payments', required: true }))
-	.post('/payments', { body: Payment }, ({ body, reply }) =>
+	.post('/payments', validate({ body: Payment }), ({ body, reply }) =>
 		reply(201, { id: crypto.randomUUID(), amount: body.amount }),
 	);
 ```
@@ -95,12 +97,16 @@ the first response back — status, headers, body — with
 | no key, with `required` | `400 { error: 'idempotency_key_missing' }` |
 | the route answers a 5xx, or streams | answered, not kept: the key is free again |
 
-Every one is part of the guarded routes' types. Keys are scoped by the
+Only the routes after the middleware answer them; a request no route matches
+is not guarded: there is no route to scope its key by. What is kept is what the
+route answers, an error's answer included. Keys are scoped by the
 route and by `scope(ctx)` — the client's address by default, a user id
 when there is one — so two clients choosing the same key never see each
-other's response. A replay never repeats `Set-Cookie`. Every response
+other's response. A request with no scope — no address, no `scope` — runs
+unguarded, nothing stored or replayed, and the middleware warns once. A replay never repeats `Set-Cookie`. Every response
 below 500 is kept, a 4xx included: declare a rate limit or an auth check
-**before** `idempotency`, or its refusal is replayed.
+**before** `idempotency`, or its refusal is replayed (`app.use` in
+declaration order: the guard first, then `idempotency`).
 
 | option | default | |
 | --- | --- | --- |
@@ -111,7 +117,7 @@ below 500 is kept, a 4xx included: declare a rate limit or an auth check
 | `methods` | `POST`, `PATCH` | |
 | `header` | `Idempotency-Key` | |
 | `required` | `false` | |
-| `scope` | the client's address | `(ctx) => string` |
+| `scope` | the client's address | `(ctx) => string \| undefined`; `undefined` runs the request unguarded |
 
 ## Caches and locks in the context
 
@@ -128,7 +134,7 @@ const loadUser = async (id: string) => ({ id, name: 'Ada' });   // your database
 const touch = async (user: z.infer<typeof User>) => user;
 
 const app = alxia()
-	.use(redis(connection.client, { caches: { users } }))
+	.plugin(redis(connection.client, { caches: { users } }))
 	.get('/users/:id', async ({ caches, lock, params, reply }) => {
 		const user = await caches.users.remember(params.id, () => loadUser(params.id)); // typed by User
 		await lock(`user:${params.id}`, () => touch(user));
@@ -140,6 +146,71 @@ const app = alxia()
 for everything else. It sits beside `@alxia/cache`'s `ctx.cache` — the
 response cache's `{ tag, skip }` — without touching it, in either order.
 
+## With @nxgt/redis
+
+Open the Redis once with `@nxgt/redis`'s `openRedis(defineRedis({ … }))` and
+hand the handle to every export that takes a client: one `prefix` is in front
+of every key of the deployment, and the handle closes with the app.
+
+```ts
+import { alxia, health } from '@alxia/core';
+import { redis, redisCheck, redisStore } from '@alxia/redis';
+import { rateLimit } from '@alxia/rate-limit';
+import { defineCache, defineRedis, openRedis } from '@nxgt/redis';
+import { z } from 'zod';
+
+const users = defineCache({ name: 'user', key: (id: string) => id, ttl: 300, schema: z.object({ id: z.string(), name: z.string() }) });
+const handle = await openRedis(defineRedis({ uri: Bun.env['REDIS_URL']!, prefix: 'shop', caches: { users } }));
+
+const app = alxia()
+	.use(rateLimit({ limit: 100, windowMs: 60_000, store: redisStore(handle, { name: 'api' }) })) // shop:api:…
+	.plugin(redis(handle))                                   // caches typed from handle.cache; handle.close() in onStop
+	.plugin(health({ checks: { redis: redisCheck(handle) } }))
+	.get('/users/:id', async ({ caches, lock, params, reply }) =>
+		reply.ok(await lock(params.id, () => caches.users.remember(params.id, () => ({ id: params.id, name: 'Ada' })))), // shop:user:…, lock:shop:…
+	);
+```
+
+`redisStore`, `redisCacheStore` and `idempotency` take the handle where they
+take a client, and put its `prefix` in front of their `name`: the keys are
+`shop:api:…`, `shop:pages:response:…`, `shop:orders:…`. `redis(handle)` puts
+`caches` (the handle's own bound caches), `lock` (under the prefix), `redis`
+(the client) and `prefix` in the context, and closes the handle once when the
+app stops, after the requests in flight finished: `redis(handle, { close: false })`
+when something else closes it. The handle must wire one Redis instance.
+The bare `RedisClient` forms are unchanged and add no prefix.
+
+### Defined once, in `defineRedis`
+
+With `@nxgt/redis` 0.6 the rate limit and the idempotency are wired by
+`defineRedis` too (`limits`, `idempotency`), and `redisStore` and `idempotency`
+take the wired entry, so the definition lives in one place and its types flow
+through:
+
+```ts
+import { idempotency, idempotencyResult, redisStore } from '@alxia/redis';
+import { defineIdempotency, defineRateLimit, defineRedis, openRedis } from '@nxgt/redis';
+
+const api = defineRateLimit({ name: 'api', key: (ip: string) => ip, limit: 100, per: 60_000 });
+const orders = defineIdempotency({ name: 'orders', key: (id: string) => id, ttl: 86_400, schema: idempotencyResult });
+const wired = await openRedis(defineRedis({ uri: Bun.env['REDIS_URL']!, prefix: 'shop', limits: { api }, idempotency: { orders } }));
+
+alxia()
+	.use(rateLimit({ limit: 100, windowMs: 60_000, store: redisStore(wired.limits.api) })) // shop:api:<address>
+	.use(idempotency(wired.idempotency.orders, { required: true }))                       // shop:orders:<route>:<scope>:<key>
+	.post('/orders', ({ reply }) => reply(201, { id: crypto.randomUUID() }));
+```
+
+The keys are those `@nxgt/redis` writes, `<prefix>:<name>:<key>`, so another
+consumer calling `wired.limits.api.consume(address)` shares the count. The
+rate, `ttl` and `lease` are the definition's: `rateLimit`'s `limit` and
+`windowMs` only write its headers, so repeat the definition's numbers, and the
+wired `idempotency` takes no `name`, `ttl` or `lease`. The limit's key takes a
+string, and the idempotency's `schema` is `idempotencyResult`: another is a
+compile error. A rate limit moved from `redisStore(handle, { name })` starts
+its counts again, the layouts differing; an idempotency keeps its keys. Both
+older forms stay. [More](docs/guide/connecting.md#defined-once-in-defineredis).
+
 ## Testing
 
 The package's specs run against `$REDIS_URL`, or a `redis-server` on
@@ -149,11 +220,18 @@ The package's specs run against `$REDIS_URL`, or a `redis-server` on
 
 | export | |
 | --- | --- |
-| `redisStore(client, { name })`, `RedisStoreOptions` | an `@alxia/rate-limit` store |
-| `redisCacheStore(client, { name })`, `RedisCacheStoreOptions` | an `@alxia/cache` store |
-| `idempotency(client, options)` | the plugin |
-| `redis(client, { caches? })`, `RedisContextOptions` | the plugin: `redis`, `caches`, `lock` in the context |
+| `redisStore(client \| handle, { name })`, `RedisStoreOptions` | an `@alxia/rate-limit` store |
+| `redisStore(handle.limits.api)` | the same for a rate limit wired by `defineRedis` (`@nxgt/redis` 0.6): the definition holds the name and the rate, the keys are `<prefix>:<name>:<key>` |
+| `redisCacheStore(client \| handle, { name })`, `RedisCacheStoreOptions` | an `@alxia/cache` store |
+| `idempotency(client \| handle, options)` | the middleware, given to `app.use` |
+| `idempotency(handle.idempotency.orders, options?)`, `WiredIdempotency`, `WiredIdempotencyOptions` | the same for an idempotency wired by `defineRedis`: its definition holds the `name`, `ttl` and `lease`, so the options take none of them |
+| `idempotencyResult`, `IdempotencyResult` | the `schema` a wired idempotency given to `idempotency()` must have: the response it keeps |
+| `redis(client, { caches? })`, `RedisContextOptions` | a plugin, given to `app.plugin`: `redis`, `caches`, `lock` in the context |
+| `redis(handle, { close? })`, `RedisHandleOptions`, `RedisHandleContext` | the same from an `@nxgt/redis` handle: its typed caches, a prefixed `lock`, `prefix`; closes the handle in `onStop` unless `close: false` |
+| `redisCheck(client \| handle, { timeout? })`, `RedisCheckOptions` | a check for core's `health({ checks })`: down when a Redis instance does not answer a `PING`; `timeout` bounds a handle's ping, a client's is bounded by `health({ timeout })` |
+| `RedisTarget` | a client or a handle: what the factories above take |
 | `IdempotencyOptions`, `IdempotencyErrorBody`, `RedisContext`, `BoundCaches` | its types |
+| `IdempotencyMiddleware` | what `idempotency()` returns: a middleware that adds nothing, and may answer a 400, a 409 or a 422 |
 | `AnyCache` | any cache definition: the constraint of a function generic over the caches it hands to `redis()` |
 
 ## Documentation
@@ -161,3 +239,4 @@ The package's specs run against `$REDIS_URL`, or a `redis-server` on
 - [Guide](https://github.com/softistx/alxia/tree/develop/packages/redis/docs): a page per area — connecting, rate limits, the response cache, idempotency, caches and locks, and testing against a real Redis.
 - [Troubleshooting](https://github.com/softistx/alxia/blob/develop/packages/redis/docs/troubleshooting.md): an error message, a refusal a client got, or a limit, cache or replay that does not behave as expected, and what to do about it.
 - [Roadmap](https://github.com/softistx/alxia/blob/develop/packages/redis/docs/roadmap.md): what is coming, and what is not planned.
+- [Recipes](https://github.com/softistx/alxia/blob/develop/docs/recipes/README.md): [Caching and rate limiting with Redis](https://github.com/softistx/alxia/blob/develop/docs/recipes/caching-and-rate-limiting.md), [Test an alxia app](https://github.com/softistx/alxia/blob/develop/docs/recipes/testing.md), [Health checks and graceful shutdown](https://github.com/softistx/alxia/blob/develop/docs/recipes/health-and-shutdown.md).

package/dist/cache-store.d.ts

@@ -1,7 +1,7 @@
 import type { CacheStore } from '@alxia/cache';
-import type { RedisClient } from 'bun';
+import { type RedisTarget } from './handle';
 export interface RedisCacheStoreOptions {
-    /** Prepended to every key it writes: one name per app or deployment. */
+    /** Prepended to every key it writes: one name per app or deployment. Under a handle's prefix, when it is given one. */
     readonly name: string;
 }
 /**
@@ -13,6 +13,9 @@ export interface RedisCacheStoreOptions {
  * ```ts
  * app.use(cache({ ttl: 60, store: redisCacheStore(connection.client, { name: 'shop' }) }));
  * ```
+ *
+ * Given an `@nxgt/redis` handle instead of a client, every key, the tag sets
+ * included, is under the handle's `prefix`.
  */
-export declare function redisCacheStore(client: RedisClient, options: RedisCacheStoreOptions): CacheStore;
+export declare function redisCacheStore(target: RedisTarget, options: RedisCacheStoreOptions): CacheStore;
 //# sourceMappingURL=cache-store.d.ts.map

package/dist/cache-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache-store.d.ts","sourceRoot":"","sources":["../src/cache-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AAGvC,MAAM,WAAW,sBAAsB;IACtC,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAeD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC9B,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,sBAAsB,GAC7B,UAAU,CA4EZ"}
+{"version":3,"file":"cache-store.d.ts","sourceRoot":"","sources":["../src/cache-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,UAAU,EAAE,MAAM,cAAc,CAAC;AAG/D,OAAO,EAAa,KAAK,WAAW,EAAE,MAAM,UAAU,CAAC;AAEvD,MAAM,WAAW,sBAAsB;IACtC,uHAAuH;IACvH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AA4CD;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC9B,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,sBAAsB,GAC7B,UAAU,CAwDZ"}

package/dist/check.d.ts

@@ -0,0 +1,19 @@
+import type { RedisTarget } from './handle';
+export interface RedisCheckOptions {
+    /**
+     * Milliseconds a handle's ping waits for each instance, as
+     * `health({ timeout })` names its own: `@nxgt/redis`'s 2 s by default.
+     */
+    readonly timeout?: number;
+}
+/**
+ * A readiness check for core's `health({ checks })`: it passes when every
+ * Redis instance of the handle answers a `PING`, and is down when one does
+ * not, or when the call fails. Given a client, it sends the `PING` itself.
+ *
+ * ```ts
+ * app.plugin(health({ checks: { redis: redisCheck(handle) } }));
+ * ```
+ */
+export declare function redisCheck(target: RedisTarget, options?: RedisCheckOptions): () => Promise<boolean>;
+//# sourceMappingURL=check.d.ts.map

package/dist/check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../src/check.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAG5C,MAAM,WAAW,iBAAiB;IACjC;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CACzB,MAAM,EAAE,WAAW,EACnB,OAAO,GAAE,iBAAsB,GAC7B,MAAM,OAAO,CAAC,OAAO,CAAC,CAaxB"}

package/dist/context.d.ts

@@ -1,4 +1,4 @@
-import { type BoundCache, type CacheDefinition, type LockOptions } from '@nxgt/redis';
+import { type BoundCache, type CacheDefinition, type LockOptions, type Redis, type SoleInstance } from '@nxgt/redis';
 import type { RedisClient } from 'bun';
 import type { z } from 'zod';
 /**
@@ -8,7 +8,7 @@ import type { z } from 'zod';
  *
  * ```ts
  * function withCaches<const Caches extends Record<string, AnyCache>>(caches: Caches) {
- *   return alxia().use(redis(client, { caches }));
+ *   return alxia().plugin(redis(client, { caches }));
  * }
  * ```
  */
@@ -30,15 +30,46 @@ export interface RedisContext<Caches extends Record<string, AnyCache>> {
     /** `work` under a lock every process sharing the Redis respects: `@nxgt/redis`'s `withLock`. */
     lock<T>(key: string, work: () => Promise<T> | T, options?: LockOptions): Promise<T>;
 }
+export interface RedisHandleOptions {
+    /**
+     * Whether the handle is closed when the app stops: once, after the drain,
+     * in `onStop`. On by default; `false` when something else closes it.
+     */
+    readonly close?: boolean;
+}
+/** What routes after `redis(handle)` read. */
+export interface RedisHandleContext<C> {
+    /** Bun's own client, untouched: the handle's one instance. */
+    readonly redis: RedisClient;
+    /** The handle's caches, typed by their schemas, the prefix already in front of every key. */
+    readonly caches: SoleInstance<C>['cache'];
+    /** `work` under a lock every process sharing the Redis respects, under the handle's prefix. */
+    readonly lock: SoleInstance<C>['lock'];
+    /** What goes in front of every key, or `undefined`. */
+    readonly prefix: string | undefined;
+}
+declare function fromClient<const Caches extends Record<string, AnyCache> = Record<never, never>>(client: RedisClient, options?: RedisContextOptions<Caches>): import("@alxia/core").Alxia<import("@alxia/core").Empty & RedisContext<Caches>, "">;
+declare function fromHandle<C>(handle: Redis<C>, options?: RedisHandleOptions): import("@alxia/core").Alxia<import("@alxia/core").Empty & RedisHandleContext<C>, "">;
 /**
  * Redis in the context, as a plugin: the client, the caches bound once, and
  * a lock — typed, for every route declared after it.
  *
  * ```ts
  * const users = defineCache({ name: 'user', key: (id: string) => id, ttl: 300, schema: User });
- * app.use(redis(connection.client, { caches: { users } }))
+ * app.plugin(redis(connection.client, { caches: { users } }))
  *    .get('/users/:id', async ({ caches, params, reply }) => reply.ok(await caches.users.remember(params.id, load)));
  * ```
+ *
+ * Given an `@nxgt/redis` handle, the caches are the handle's own, the
+ * prefix is in front of every key and lock, and the handle is closed when
+ * the app stops, after the drain (`{ close: false }` to close it yourself):
+ *
+ * ```ts
+ * const handle = await openRedis(defineRedis({ uri, prefix: 'shop', caches }));
+ * app.plugin(redis(handle)).get('/u/:id', ({ caches, params }) => caches.users.get(params.id));
+ * ```
  */
-export declare function redis<const Caches extends Record<string, AnyCache> = Record<never, never>>(client: RedisClient, options?: RedisContextOptions<Caches>): import("@alxia/core").Alxia<import("@alxia/core").Empty & RedisContext<Caches>, import("@alxia/core").Empty, "", never>;
+export declare function redis<const Caches extends Record<string, AnyCache> = Record<never, never>>(client: RedisClient, options?: RedisContextOptions<Caches>): ReturnType<typeof fromClient<Caches>>;
+export declare function redis<C>(handle: Redis<C>, options?: RedisHandleOptions): ReturnType<typeof fromHandle<C>>;
+export {};
 //# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AACA,OAAO,EACN,KAAK,UAAU,EAEf,KAAK,eAAe,EACpB,KAAK,WAAW,EAEhB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AACvC,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B;;;;;;;;;;GAUG;AACH,MAAM,MAAM,QAAQ,GAAG,eAAe,CAAC,GAAG,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;AAEvD,wDAAwD;AACxD,MAAM,MAAM,WAAW,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI;IAClE,QAAQ,EAAE,IAAI,IAAI,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,eAAe,CACpE,MAAM,MAAM,EACZ,MAAM,MAAM,CACZ,GACE,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,GACrD,KAAK;CACR,CAAC;AAEF,MAAM,WAAW,mBAAmB,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC3E,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,wCAAwC;AACxC,MAAM,WAAW,YAAY,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC;IACpE,mCAAmC;IACnC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACrC,gGAAgG;IAChG,IAAI,CAAC,CAAC,EACL,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EAC1B,OAAO,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,CAAC,CAAC,CAAC;CACd;AAED;;;;;;;;;GASG;AACH,wBAAgB,KAAK,CACpB,KAAK,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EACnE,MAAM,EAAE,WAAW,EAAE,OAAO,GAAE,mBAAmB,CAAC,MAAM,CAAM,2HAa/D"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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"}

package/dist/handle.d.ts

@@ -0,0 +1,31 @@
+import type { BoundIdempotency, BoundRateLimit, Redis } from '@nxgt/redis';
+import type { RedisClient } from 'bun';
+/**
+ * What the factories take: Bun's own client, or the handle `@nxgt/redis`'s
+ * `openRedis(defineRedis({ … }))` gives back.
+ */
+export type RedisTarget = RedisClient | Redis<any>;
+/** The one instance of a handle, resolved: its client and the prefix in front of its keys. */
+export interface ResolvedTarget {
+    readonly client: RedisClient;
+    /** `undefined` when nothing goes in front of the keys, and always for a bare client. */
+    readonly prefix: string | undefined;
+}
+/** A handle has `instances` and `close`; Bun's `RedisClient` has neither. */
+export declare function isHandle(target: RedisTarget): target is Redis<any>;
+/**
+ * The client and prefix of a target. A handle must wire exactly one Redis
+ * instance: with several, which one an app's keys live on is for the app to
+ * say, with the bare client of `handle.clients.<name>`.
+ */
+export declare function resolve(target: RedisTarget): ResolvedTarget;
+/** `name`, with the handle's prefix in front when there is one: the one name a deployment's keys share. */
+export declare function nameUnder(target: RedisTarget, name: string): {
+    readonly client: RedisClient;
+    readonly name: string;
+};
+/** A rate limit bound by `@nxgt/redis`, wired or by hand: `consume`, `peek`, `reset` and `keyFor`. */
+export declare function isWiredLimit(value: object): value is BoundRateLimit<string>;
+/** An idempotency bound by `@nxgt/redis`, wired or by hand: `run`, `forget` and `keyFor`. */
+export declare function isWiredIdempotency(value: object): value is BoundIdempotency<string, any, any>;
+//# sourceMappingURL=handle.d.ts.map

package/dist/handle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle.d.ts","sourceRoot":"","sources":["../src/handle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAC3E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AAEvC;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;AAEnD,8FAA8F;AAC9F,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,wFAAwF;IACxF,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC;AAED,6EAA6E;AAC7E,wBAAgB,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,IAAI,KAAK,CAAC,GAAG,CAAC,CAMlE;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,WAAW,GAAG,cAAc,CAc3D;AAED,2GAA2G;AAC3G,wBAAgB,SAAS,CACxB,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,MAAM,GACV;IACF,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB,CAGA;AAED,sGAAsG;AACtG,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,cAAc,CAAC,MAAM,CAAC,CAQ3E;AAED,6FAA6F;AAC7F,wBAAgB,kBAAkB,CACjC,KAAK,EAAE,MAAM,GACX,KAAK,IAAI,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,CAAC,CAO7C"}

package/dist/idempotency-response.d.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+/**
+ * What `idempotency()` keeps under a key: the response, as the route
+ * answered it. The `schema` of a wired `defineIdempotency` that
+ * `idempotency(handle.idempotency.orders)` is given:
+ *
+ * ```ts
+ * export const orders = defineIdempotency({ name: 'orders', key: (id: string) => id, ttl: 86_400, schema: idempotencyResult });
+ * ```
+ */
+export declare const idempotencyResult: z.ZodObject<{
+    status: z.ZodNumber;
+    headers: z.ZodArray<z.ZodTuple<[z.ZodString, z.ZodString], null>>;
+    body: z.ZodString;
+}, z.core.$strip>;
+export type IdempotencyResult = z.infer<typeof idempotencyResult>;
+/** A response that is answered and not kept: a 5xx, a stream. */
+export declare class Unstored extends Error {
+    readonly response: Response;
+    constructor(response: Response);
+}
+/** What a key is bound to: the method, the path and query, the body. */
+export declare function fingerprintOf(request: Request, url: URL): Promise<Uint8Array>;
+export declare function store(response: Response): Promise<IdempotencyResult>;
+export declare function restore(stored: IdempotencyResult, replayed: boolean): Response;
+//# sourceMappingURL=idempotency-response.d.ts.map

package/dist/idempotency-response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency-response.d.ts","sourceRoot":"","sources":["../src/idempotency-response.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB;;;;iBAI5B,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAKlE,iEAAiE;AACjE,qBAAa,QAAS,SAAQ,KAAK;IAClC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;gBAChB,QAAQ,EAAE,QAAQ;CAI9B;AAED,wEAAwE;AACxE,wBAAsB,aAAa,CAClC,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,GAAG,GACN,OAAO,CAAC,UAAU,CAAC,CASrB;AAED,wBAAsB,KAAK,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAiB1E;AAED,wBAAgB,OAAO,CACtB,MAAM,EAAE,iBAAiB,EACzB,QAAQ,EAAE,OAAO,GACf,QAAQ,CAQV"}

package/dist/idempotency.d.ts

@@ -1,11 +1,13 @@
-import { type BaseContext } from '@alxia/core';
-import type { RedisClient } from 'bun';
+import { type BaseContext, type Empty, type Middleware, type Reply } from '@alxia/core';
+import { type BoundIdempotency } from '@nxgt/redis';
+import { type RedisTarget } from './handle';
+import { type IdempotencyResult } from './idempotency-response';
 export interface IdempotencyOptions {
-    /** Names the keys it stores. */
+    /** Names the keys it stores, under a handle's prefix when it is given one. */
     readonly name: string;
     /** Seconds a finished response is kept and replayed. A day by default. */
     readonly ttl?: number;
-    /** Milliseconds a running request holds its key unless renewed. `@nxgt/redis-guard`'s 10 s by default. */
+    /** Milliseconds a running request holds its key unless renewed. `@nxgt/redis`'s 10 s by default. */
     readonly lease?: number;
     /** Milliseconds a repeat waits for the first to finish before a 409. None by default. */
     readonly wait?: number;
@@ -18,7 +20,9 @@ export interface IdempotencyOptions {
     /**
      * Whose key it is: keys are scoped by the route and by this, so two
      * clients choosing the same key never see each other's response. The
-     * client's address by default; a user id when there is one.
+     * client's address by default; a user id when there is one. A request
+     * it gives no scope for runs unguarded — nothing stored, nothing
+     * replayed — with a warning, once.
      */
     readonly scope?: (ctx: BaseContext) => string | undefined;
 }
@@ -29,10 +33,26 @@ export interface IdempotencyErrorBody {
     readonly retryAfter?: number;
 }
 /**
- * Idempotent routes, as a plugin, with `@nxgt/redis-guard`: a `POST` or
+ * What `idempotency()` makes: a middleware that adds nothing to the
+ * context, and may answer a 400, a 409 or a 422.
+ */
+export type IdempotencyMiddleware = Middleware<Empty, Promise<Response | Reply<400, IdempotencyErrorBody> | Reply<409, IdempotencyErrorBody> | Reply<422, IdempotencyErrorBody>>>;
+/**
+ * An idempotency wired by `defineRedis` — `handle.idempotency.orders` — whose
+ * definition holds `idempotencyResult` as its schema and a key taken as a
+ * string.
+ */
+export type WiredIdempotency = BoundIdempotency<string, IdempotencyResult, IdempotencyResult>;
+/** What a wired idempotency leaves to the middleware: its name, `ttl` and `lease` are the definition's. */
+export type WiredIdempotencyOptions = Omit<IdempotencyOptions, 'name' | 'ttl' | 'lease'>;
+/**
+ * Idempotent routes, as a middleware, with `@nxgt/redis`: a `POST` or
  * `PATCH` carrying an `Idempotency-Key` runs once per key, and every repeat
  * gets the first response back, marked `Idempotent-Replayed: true` — across
- * every process sharing the Redis. Routes declared after it are guarded.
+ * every process sharing the Redis. Routes declared after it are guarded; a
+ * request no route matches is not: there is no route to scope its key by.
+ * What is kept is the response the route answers, an error's answer
+ * included.
  *
  * A repeat while the first still runs is a 409, and the same key with
  * another request — method, path or body — a 422: both are part of every
@@ -42,6 +62,18 @@ export interface IdempotencyErrorBody {
  * ```ts
  * app.use(idempotency(redis.client, { name: 'payments' })).post('/payments', ...);
  * ```
+ *
+ * Given an `@nxgt/redis` handle instead of a client, the keys are under the
+ * handle's `prefix`: `idempotency(handle, { name: 'payments' })`.
+ *
+ * Given an idempotency wired by `defineRedis`, the definition — name, `ttl`,
+ * `lease` — is the one place, and the keys are those `@nxgt/redis` writes,
+ * `<prefix>:<name>:<route>:<scope>:<key>`:
+ *
+ * ```ts
+ * app.use(idempotency(handle.idempotency.orders, { required: true })).post('/orders', ...);
+ * ```
  */
-export declare function idempotency(client: RedisClient, options: IdempotencyOptions): import("@alxia/core").Alxia<import("@alxia/core").Empty, import("@alxia/core").Empty, "", import("@alxia/core").Reply<400, IdempotencyErrorBody> | import("@alxia/core").Reply<409, IdempotencyErrorBody> | import("@alxia/core").Reply<422, IdempotencyErrorBody>>;
+export declare function idempotency(target: RedisTarget, options: IdempotencyOptions): IdempotencyMiddleware;
+export declare function idempotency(wired: WiredIdempotency, options?: WiredIdempotencyOptions): IdempotencyMiddleware;
 //# sourceMappingURL=idempotency.d.ts.map

package/dist/idempotency.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"idempotency.d.ts","sourceRoot":"","sources":["../src/idempotency.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAMtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AAGvC,MAAM,WAAW,kBAAkB;IAClC,gCAAgC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,0GAA0G;IAC1G,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,yFAAyF;IACzF,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,+FAA+F;IAC/F,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,sFAAsF;IACtF,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,MAAM,GAAG,SAAS,CAAC;CAC1D;AAED,6BAA6B;AAC7B,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,KAAK,EACX,yBAAyB,GACzB,yBAAyB,GACzB,yBAAyB,GACzB,wBAAwB,CAAC;IAC5B,sFAAsF;IACtF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC7B;AAuBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,kBAAkB,uQAsE3E"}
+{"version":3,"file":"idempotency.d.ts","sourceRoot":"","sources":["../src/idempotency.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,WAAW,EAEhB,KAAK,KAAK,EACV,KAAK,UAAU,EAEf,KAAK,KAAK,EAEV,MAAM,aAAa,CAAC;AACrB,OAAO,EACN,KAAK,gBAAgB,EAIrB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAiC,KAAK,WAAW,EAAE,MAAM,UAAU,CAAC;AAC3E,OAAO,EAEN,KAAK,iBAAiB,EAKtB,MAAM,wBAAwB,CAAC;AAEhC,MAAM,WAAW,kBAAkB;IAClC,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,oGAAoG;IACpG,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,yFAAyF;IACzF,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,+FAA+F;IAC/F,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,sFAAsF;IACtF,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,MAAM,GAAG,SAAS,CAAC;CAC1D;AAED,6BAA6B;AAC7B,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,KAAK,EACX,yBAAyB,GACzB,yBAAyB,GACzB,yBAAyB,GACzB,wBAAwB,CAAC;IAC5B,sFAAsF;IACtF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG,UAAU,CAC7C,KAAK,EACL,OAAO,CACJ,QAAQ,GACR,KAAK,CAAC,GAAG,EAAE,oBAAoB,CAAC,GAChC,KAAK,CAAC,GAAG,EAAE,oBAAoB,CAAC,GAChC,KAAK,CAAC,GAAG,EAAE,oBAAoB,CAAC,CAClC,CACD,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,gBAAgB,CAC9C,MAAM,EACN,iBAAiB,EACjB,iBAAiB,CACjB,CAAC;AAEF,2GAA2G;AAC3G,MAAM,MAAM,uBAAuB,GAAG,IAAI,CACzC,kBAAkB,EAClB,MAAM,GAAG,KAAK,GAAG,OAAO,CACxB,CAAC;AAIF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,WAAW,CAC1B,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,kBAAkB,GACzB,qBAAqB,CAAC;AACzB,wBAAgB,WAAW,CAC1B,KAAK,EAAE,gBAAgB,EACvB,OAAO,CAAC,EAAE,uBAAuB,GAC/B,qBAAqB,CAAC"}

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 export { type RedisCacheStoreOptions, redisCacheStore } from './cache-store';
-export { type AnyCache, type BoundCaches, type RedisContext, type RedisContextOptions, redis, } from './context';
-export { type IdempotencyErrorBody, type IdempotencyOptions, idempotency, } from './idempotency';
+export { type RedisCheckOptions, redisCheck } from './check';
+export { type AnyCache, type BoundCaches, type RedisContext, type RedisContextOptions, type RedisHandleContext, type RedisHandleOptions, redis, } from './context';
+export type { RedisTarget } from './handle';
+export { type IdempotencyErrorBody, type IdempotencyMiddleware, type IdempotencyOptions, idempotency, type WiredIdempotency, type WiredIdempotencyOptions, } from './idempotency';
+export { type IdempotencyResult, idempotencyResult, } from './idempotency-response';
 export { type RedisStoreOptions, redisStore } from './store';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,sBAAsB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC7E,OAAO,EACN,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,GACL,MAAM,WAAW,CAAC;AACnB,OAAO,EACN,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACvB,WAAW,GACX,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,KAAK,iBAAiB,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,sBAAsB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC7E,OAAO,EAAE,KAAK,iBAAiB,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC7D,OAAO,EACN,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,GACL,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,EACN,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,WAAW,EACX,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,GAC5B,MAAM,eAAe,CAAC;AACvB,OAAO,EACN,KAAK,iBAAiB,EACtB,iBAAiB,GACjB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,KAAK,iBAAiB,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC"}