@vouchington/rate-limit 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonathan Ong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,51 @@
+# @vouchington/rate-limit
+
+Generic [Valkey](https://valkey.io/) rate-limiting primitives backed by
+[Valkyries](https://www.npmjs.com/package/valkyries). Applications provide their own keys,
+thresholds, windows, clients, and response policy.
+
+## Install
+
+```sh
+pnpm add @vouchington/rate-limit
+```
+
+## Rate limiting
+
+`RateLimiter` records and counts caller-provided identifiers. Construct it with an application
+prefix and TTL, then choose the identifiers and threshold at each call site.
+
+```ts
+import { RateLimiter } from '@vouchington/rate-limit'
+
+const limiter = new RateLimiter({ prefix: 'api', ttlSeconds: 60 })
+const { limited } = await limiter.addAndCheck(['account:123'], 100)
+```
+
+`RateLimiter.addAndCheckWindows` supports atomic multi-window checks. `RateLimiterOptions`,
+`RateLimiterWindow`, and `RateLimiterAddAndCheckWindowsOptions` describe the available options.
+Pass a caller-managed client when the application owns connection lifecycle. Importing the package
+also initializes Valkyries-managed lazy clients for the default-client path. Applications must call
+`closeManagedValkeyClients()` during shutdown; it closes every package-managed Valkyries client in
+the process, while caller-injected clients remain caller-owned.
+
+```ts
+import { closeManagedValkeyClients } from '@vouchington/rate-limit'
+
+await closeManagedValkeyClients()
+```
+
+## Saturation retries
+
+`retryRateLimiterSaturation` retries only Valkey client inflight-saturation rejections. Callers can
+set the attempt count and minimum delay; otherwise Valkyries defaults apply. The helper does not
+choose key formats, thresholds, or how an application responds to a limit.
+
+```ts
+import { retryRateLimiterSaturation } from '@vouchington/rate-limit'
+
+const result = await retryRateLimiterSaturation(() => client.invokeScript(script, options), {
+  attempts: 3,
+  delayMs: 100,
+})
+```

package/dist/index.d.mts

@@ -0,0 +1,2 @@
+export { closeValkeyClients as closeManagedValkeyClients, retrySaturationError as retryRateLimiterSaturation, type RateLimiterAddAndCheckWindowsOptions, type RateLimiterOptions, type RateLimiterWindow, type RetrySaturationErrorOptions as RetryRateLimiterSaturationOptions, } from 'valkyries';
+export { RateLimiter } from 'valkyries/rate-limiter';

package/dist/index.mjs

@@ -0,0 +1,2 @@
+export { closeValkeyClients as closeManagedValkeyClients, retrySaturationError as retryRateLimiterSaturation, } from 'valkyries';
+export { RateLimiter } from 'valkyries/rate-limiter';

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@vouchington/rate-limit",
+  "version": "0.0.0",
+  "description": "Valkey rate-limiting primitives.",
+  "homepage": "https://github.com/vouchington/vouchington-platform/tree/main/packages/rate-limit#readme",
+  "bugs": {
+    "url": "https://github.com/vouchington/vouchington-platform/issues"
+  },
+  "license": "MIT",
+  "author": "Jonathan Ong",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vouchington/vouchington-platform.git",
+    "directory": "packages/rate-limit"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "prepack": "pnpm run build"
+  },
+  "dependencies": {
+    "valkyries": "^0.8.0"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  }
+}