valkyries 0.1.0 → 0.1.2

package/docs/rate-limiter.md

@@ -15,3 +15,139 @@ 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.
+
+## Import
+
+```ts
+import { RateLimiter } from "valkyries";
+```
+
+or:
+
+```ts
+import { RateLimiter } from "valkyries/rate-limiter";
+```
+
+## Constructor
+
+```ts
+const limiter = new RateLimiter({
+  prefix: "login",
+  ttlSeconds: 60,
+});
+```
+
+```ts
+type RateLimiterOptions = {
+  prefix: string;
+  ttlSeconds: number;
+  client?: GlideClient;
+};
+```
+
+- `prefix`: namespace for this limiter.
+- `ttlSeconds`: sliding-window size in seconds.
+- `client`: optional `@valkey/valkey-glide` client. Defaults to the package rate-limiter client.
+
+The limiter reads from the primary Valkey client to avoid replica lag in request-path checks.
+
+## `add(ids)`
+
+```ts
+limiter.add(ids: string[]): Promise<void>
+```
+
+Records events for all truthy IDs. Falsy IDs are ignored.
+
+This method writes without checking a threshold. Use it when you want to count activity separately from request admission.
+
+## `addAndCheck(ids, threshold, ttlSeconds?)`
+
+```ts
+limiter.addAndCheck(
+  ids: string[],
+  threshold: number,
+  ttlSeconds?: number,
+): Promise<{ counts: number[]; limited: boolean }>
+```
+
+Atomically records events and returns the current counts.
+
+- `counts` aligns with the filtered truthy IDs, not the original input.
+- `limited` is `true` when any post-add count is greater than or equal to `threshold`.
+- Empty or all-falsy input returns `{ counts: [], limited: false }`.
+- `ttlSeconds` overrides the instance TTL for this check.
+- Unexpected Valkey response types fail open with zero counts.
+
+Example:
+
+```ts
+const { counts, limited } = await limiter.addAndCheck(["ip:127.0.0.1"], 10);
+```
+
+## `isRateLimited(ids, threshold, ttlSeconds?)`
+
+```ts
+limiter.isRateLimited(
+  ids: string[],
+  threshold: number,
+  ttlSeconds?: number,
+): Promise<boolean>
+```
+
+Reads current counts without adding a new event. Returns `true` when any ID count is greater than or equal to `threshold` within the TTL window.
+
+## `get(ids, ttlSeconds?)`
+
+```ts
+limiter.get(ids: string[], ttlSeconds?: number): Promise<number[]>
+```
+
+Returns current counts for truthy IDs. Empty or all-falsy input returns `[]`.
+
+The returned array aligns with the filtered truthy IDs.
+
+## `delete(...ids)`
+
+```ts
+limiter.delete(...ids: string[]): Promise<number>
+```
+
+Deletes limiter keys for truthy IDs and returns the Valkey unlink count.
+
+## `getKey(key)`
+
+```ts
+limiter.getKey(key: string): string
+```
+
+Returns the Valkey sorted-set key for an ID:
+
+```txt
+rate-limiter:{prefix}:{id}
+```
+
+## `invalidate()`
+
+```ts
+limiter.invalidate(): Promise<void>
+```
+
+Deletes every limiter key for this instance prefix.
+
+## `RateLimiter.invalidate(prefix, client?)`
+
+```ts
+RateLimiter.invalidate(prefix: string, client?: GlideClient): Promise<void>
+```
+
+Deletes every limiter key for `prefix`. Passing an empty prefix invalidates all limiter namespaces visible to the client.
+
+## Events
+
+The rate limiter emits:
+
+- `rate-limiter:add` with `{ prefix, ids }`
+- `rate-limiter:get` with `{ prefix, ids, counts }`
+- `rate-limiter:delete` with `{ prefix, ids }`
+- `rate-limiter:invalidate` with `{ prefix }`

package/docs/utilities.md

@@ -0,0 +1,65 @@
+# Utilities
+
+These helpers are exported from the package root for applications that need the same normalization and serialization behavior as the built-in classes.
+
+## `normalizeKey(key)`
+
+```ts
+normalizeKey(key: string): string
+```
+
+Trims and lowercases cache keys.
+
+## `normalizeTtlResult(value)`
+
+```ts
+normalizeTtlResult(value: unknown): number | null
+```
+
+Normalizes Valkey millisecond TTL values to seconds. Preserves `-2` and `-1` sentinel values.
+
+## `normalizeCountResult(value)`
+
+```ts
+normalizeCountResult(value: unknown): number
+```
+
+Normalizes numeric or bigint Valkey counts. Returns `0` for unexpected values.
+
+## `ValkeyCacheTypeError`
+
+```ts
+class ValkeyCacheTypeError extends TypeError
+```
+
+Thrown when a cache value does not match the configured mode.
+
+## `serializeValue(value, mode)`
+
+```ts
+serializeValue(
+  value: unknown,
+  mode: "json" | "text" | "buffer",
+): Promise<string | Buffer>
+```
+
+Serializes values for cache storage and gzip-compresses payloads larger than 2 KiB.
+
+## `decodeValue(result, mode)`
+
+```ts
+decodeValue(
+  result: GlideString | null,
+  mode: "json" | "text" | "buffer",
+): Promise<string | Buffer | Record<string, unknown> | null>
+```
+
+Decodes and decompresses cache values. Returns `null` for Valkey misses.
+
+## `durationInMilliseconds(start)`
+
+```ts
+durationInMilliseconds(start: bigint): number
+```
+
+Converts a `process.hrtime.bigint()` start timestamp to elapsed milliseconds.

package/package.json

@@ -1,9 +1,17 @@
 {
   "name": "valkyries",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Valkey utilities for caches, bloom filters, dynamic configuration, and rate limiting.",
+  "homepage": "https://github.com/jonathanong/valkyries#readme",
+  "bugs": {
+    "url": "https://github.com/jonathanong/valkyries/issues"
+  },
   "license": "MIT",
   "author": "",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jonathanong/valkyries"
+  },
   "files": [
     "dist",
     "README.md",
@@ -40,26 +48,13 @@
       "default": "./dist/rate-limiter.mjs"
     }
   },
-  "scripts": {
-    "build": "tsc --project tsconfig.build.json && pnpm run copy:scripts",
-    "copy:scripts": "tsx build-scripts/copy-lua-scripts.mts",
-    "typecheck": "tsc --noEmit --project tsconfig.json",
-    "test": "vitest run",
-    "test:coverage": "vitest run --coverage",
-    "lint": "pnpm run oxlint && pnpm run oxfmt:check",
-    "oxlint": "oxlint --type-aware --deny-warnings",
-    "oxlint:fix": "oxlint --type-aware --fix --deny-warnings",
-    "oxfmt": "oxfmt",
-    "oxfmt:check": "oxfmt --check",
-    "actionlint": "actionlint"
-  },
   "dependencies": {
     "@valkey/valkey-glide": "^2.4.0"
   },
   "devDependencies": {
     "@types/node": "^25.8.0",
     "@vitest/coverage-v8": "^4.1.6",
-    "actionlint": "^2.0.6",
+    "github-actionlint": "^1.7.12",
     "oxfmt": "^0.50.0",
     "oxlint": "^1.65.0",
     "oxlint-tsgolint": "^0.22.1",
@@ -70,11 +65,17 @@
   "engines": {
     "node": ">=24.0.0"
   },
-  "packageManager": "pnpm@11.1.2",
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "esbuild",
-      "protobufjs"
-    ]
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json && pnpm run copy:scripts",
+    "copy:scripts": "tsx build-scripts/copy-lua-scripts.mts",
+    "typecheck": "tsc --noEmit --project tsconfig.json",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "lint": "pnpm run oxlint && pnpm run oxfmt:check",
+    "oxlint": "oxlint --type-aware --deny-warnings",
+    "oxlint:fix": "oxlint --type-aware --fix --deny-warnings",
+    "oxfmt": "oxfmt",
+    "oxfmt:check": "oxfmt --check",
+    "actionlint": "github-actionlint"
   }
-}
+}