valkyries 0.1.7 → 0.3.0

package/docs/idempotency-key.md

@@ -0,0 +1,102 @@
+# Idempotency Keys
+
+Generic Valkey primitives for consume-once values and token-fenced idempotency keys.
+
+## `getAndDelete(key, options?)`
+
+```ts
+getAndDelete(key: string, options?: { client?: GlideClient }): Promise<string | null>
+```
+
+Atomically reads and deletes a key using native `GETDEL`.
+
+- Returns the stored string value.
+- Returns `null` when the key does not exist.
+- Throws Valkey/client errors.
+- Requires Valkey support for `GETDEL`.
+
+## `reserveIdempotencyKey(key, ttlSeconds, options?)`
+
+```ts
+reserveIdempotencyKey(
+  key: string,
+  ttlSeconds: number,
+  options?: {
+    client?: GlideClient;
+    processingPrefix?: string;
+    completedValue?: string;
+    token?: string;
+  },
+): Promise<
+  | { state: "reserved"; token: string }
+  | { state: "processing" | "completed" }
+>
+```
+
+Atomically reserves a key when it is absent by storing `processing:<token>` with `EX ttlSeconds`.
+
+- Generates a random token by default.
+- Returns `processing` when another reservation is active.
+- Returns `completed` when the dedup key has already completed.
+- The caller owns key naming and Redis Cluster hash tags.
+
+## `completeIdempotencyKey(key, token, ttlSeconds, options?)`
+
+```ts
+completeIdempotencyKey(
+  key: string,
+  token: string,
+  ttlSeconds: number,
+  options?: IdempotencyKeyOptions,
+): Promise<"completed" | "missing" | "changed">
+```
+
+Atomically changes `processing:<token>` to `completed` with `EX ttlSeconds`.
+
+- `completed`: the caller still owned the reservation and completion was recorded.
+- `missing`: the key was absent.
+- `changed`: the key existed but did not match the caller's token.
+
+## `releaseIdempotencyKey(key, token, options?)`
+
+```ts
+releaseIdempotencyKey(
+  key: string,
+  token: string,
+  options?: IdempotencyKeyOptions,
+): Promise<boolean>
+```
+
+Atomically deletes the key only when it still contains `processing:<token>`.
+
+- Returns `true` when released.
+- Returns `false` when the key is missing or owned by another token.
+
+## Example
+
+```ts
+const key = `webhook:{${event.id}}`;
+const reservation = await reserveIdempotencyKey(key, 60);
+
+if (reservation.state === "completed") return;
+if (reservation.state === "processing") throw new Error("event is already processing");
+
+try {
+  await processEvent(event);
+  await completeIdempotencyKey(key, reservation.token, 24 * 60 * 60);
+} catch (error) {
+  await releaseIdempotencyKey(key, reservation.token);
+  throw error;
+}
+```
+
+## Validation
+
+- `key`, `token`, `processingPrefix`, and `completedValue` must be non-empty.
+- `ttlSeconds` must be greater than `0`.
+- `processingPrefix` must not equal `completedValue`.
+- `processingPrefix` and `completedValue` must not equal script result sentinels:
+  `reserved`, `missing`, or `changed`.
+- `completedValue` must not be inside the processing namespace
+  (`${processingPrefix}:...`).
+- Valkey/client errors throw instead of failing open.

package/docs/lua-scripts.md

@@ -45,8 +45,15 @@ Dynamic config scripts:
 
 - `dynamic-config-set-fields.lua`
 
+Idempotency key scripts:
+
+- `idempotency-key-complete-if-current.lua`
+- `idempotency-key-release-if-current.lua`
+- `idempotency-key-reserve.lua`
+
 Rate limiter scripts:
 
 - `rate-limiter-add.lua`
 - `rate-limiter-add-and-check.lua`
+- `rate-limiter-add-and-check-windows.lua`
 - `rate-limiter-get.lua`

package/docs/rate-limiter.md

@@ -5,7 +5,7 @@
 Key format:
 
 ```txt
-rate-limiter:{prefix}:{id}
+rate-limiter:<prefix>:{<id>}
 ```
 
 Use `addAndCheck(ids, threshold)` for request paths. It atomically adds an event, removes expired events, counts the current window, and returns:
@@ -16,6 +16,8 @@ Use `addAndCheck(ids, threshold)` for request paths. It atomically adds an event
 
 A threshold of `N` blocks the Nth request because the count is checked after incrementing.
 
+Use `RateLimiter.addAndCheckWindows(windows)` when one logical request must be checked against multiple TTL/threshold windows in one Valkey round trip. All windows in that call must share one Redis Cluster hash tag.
+
 ## Import
 
 ```ts
@@ -79,12 +81,90 @@ Atomically records events and returns the current counts.
 - `ttlSeconds` overrides the instance TTL for this check.
 - Unexpected Valkey response types fail open with zero counts.
 
+## `RateLimiter.addAndCheckWindows(windows, options?)`
+
+```ts
+RateLimiter.addAndCheckWindows(
+  [
+    { prefix: "web-risk-minute", id: "global", hashTag: "2026-06", ttlSeconds: 60, threshold: 5001 },
+    { prefix: "web-risk-month", id: "global", hashTag: "2026-06", ttlSeconds: 31 * 24 * 60 * 60, threshold: 90001 },
+  ],
+  { mode: "stop-on-limited" },
+): Promise<{ counts: number[]; limited: boolean }>
+```
+
+Records and checks heterogeneous windows in one Lua script call.
+
+- `counts` aligns with `windows`.
+- `limited` is `true` when any post-add count is greater than or equal to its window threshold.
+- `mode: "record-all"` records every window and is the default.
+- `mode: "stop-on-limited"` stops recording later windows after an earlier window is limited.
+- `skipWriteWhenLimited: true` on a window trims expired entries and checks the current count before writing. If the window is already at or above its threshold, that window returns its current count and does not add another sorted-set member.
+- The request that reaches the threshold is still recorded and returns the post-add count.
+- All windows must share the same effective hash tag: `hashTag ?? id`.
+- Window prefixes must not contain Redis hash tag braces, and generated Valkey keys must be unique.
+- Unexpected Valkey response types fail open with zero counts.
+
 Example:
 
 ```ts
 const { counts, limited } = await limiter.addAndCheck(["ip:127.0.0.1"], 10);
 ```
 
+Scarce provider quota windows can avoid member churn after a long-window quota is capped:
+
+```ts
+const month = "2026-06";
+
+const result = await RateLimiter.addAndCheckWindows(
+  [
+    {
+      prefix: "web-risk-minute",
+      id: "global",
+      hashTag: month,
+      ttlSeconds: 60,
+      threshold: 5001,
+    },
+    {
+      prefix: "web-risk-month",
+      id: "",
+      hashTag: month,
+      ttlSeconds: 31 * 24 * 60 * 60,
+      threshold: 90001,
+      skipWriteWhenLimited: true,
+    },
+  ],
+  { mode: "stop-on-limited" },
+);
+```
+
+## `RateLimiter.getWindowKey(window)`
+
+```ts
+RateLimiter.getWindowKey(window: RateLimiterWindow): string
+```
+
+Returns the Valkey sorted-set key for a multi-window definition. Use this to assert Redis Cluster compatibility and stable quota bucket shapes without duplicating key logic.
+
+```ts
+RateLimiter.getWindowKey({
+  prefix: "web-risk-month",
+  id: "",
+  hashTag: "2026-06",
+  ttlSeconds: 31 * 24 * 60 * 60,
+  threshold: 90001,
+});
+// "rate-limiter:web-risk-month:{2026-06}"
+```
+
+Key shapes:
+
+```txt
+rate-limiter:<prefix>:{<id>}
+rate-limiter:<prefix>:{<hashTag>}:<id>
+rate-limiter:<prefix>:{<hashTag>}
+```
+
 ## `isRateLimited(ids, threshold, ttlSeconds?)`
 
 ```ts
@@ -124,7 +204,7 @@ limiter.getKey(key: string): string
 Returns the Valkey sorted-set key for an ID:
 
 ```txt
-rate-limiter:{prefix}:{id}
+rate-limiter:<prefix>:{<id>}
 ```
 
 ## `invalidate()`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "valkyries",
-  "version": "0.1.7",
+  "version": "0.3.0",
   "description": "Valkey utilities for caches, bloom filters, dynamic configuration, and rate limiting.",
   "homepage": "https://github.com/jonathanong/valkyries#readme",
   "bugs": {
@@ -42,6 +42,11 @@
       "import": "./dist/dynamic-config.mjs",
       "default": "./dist/dynamic-config.mjs"
     },
+    "./idempotency-key": {
+      "types": "./dist/idempotency-key.d.mts",
+      "import": "./dist/idempotency-key.mjs",
+      "default": "./dist/idempotency-key.mjs"
+    },
     "./rate-limiter": {
       "types": "./dist/rate-limiter.d.mts",
       "import": "./dist/rate-limiter.mjs",
@@ -55,7 +60,7 @@
     "@types/node": "^25.8.0",
     "@vitest/coverage-v8": "^4.1.6",
     "github-actionlint": "^1.7.12",
-    "oxfmt": "^0.51.0",
+    "oxfmt": "^0.52.0",
     "oxlint": "^1.65.0",
     "oxlint-tsgolint": "^0.23.0",
     "tsx": "^4.22.1",