valkyries 0.1.0 → 0.1.3

package/docs/bloom-filters.md

@@ -10,3 +10,222 @@ Important behavior:
 - `rebuildFromStream()` builds under `bloom-filter:{name}:building` and renames it over the live key.
 
 Large Lua-backed calls are clamped to `LUA_UNPACK_BATCH_SIZE` to avoid Valkey Lua argument limits.
+
+## Import
+
+```ts
+import { ValkeyBloomFilter } from "valkyries";
+```
+
+or:
+
+```ts
+import { ValkeyBloomFilter } from "valkyries/bloom-filter";
+```
+
+## Constructor
+
+```ts
+const filter = new ValkeyBloomFilter({
+  name: "users",
+  capacity: 1_000_000,
+  errorRate: 0.01,
+});
+```
+
+```ts
+type ValkeyBloomFilterOptions = {
+  name: string;
+  capacity: number;
+  errorRate: number;
+  batchSize?: number;
+  expansionRate?: number;
+  client?: GlideClient;
+};
+```
+
+- `name`: filter namespace. The live key is `bloom-filter:${name}`.
+- `capacity`: expected item count.
+- `errorRate`: target false-positive rate between `0` and `1`.
+- `batchSize`: write/read chunk size. Defaults to `10_000`; Lua paths clamp large chunks internally.
+- `expansionRate`: Bloom filter expansion rate. Defaults to `2`.
+- `client`: optional `@valkey/valkey-glide` client. Defaults to the package cache client.
+
+The constructor throws when `name` is empty, `capacity` is not positive, `errorRate` is not between `0` and `1`, `expansionRate` is not positive, or `batchSize` is not positive.
+
+## `ensureExists(capacity?)`
+
+```ts
+filter.ensureExists(capacity?: number): Promise<void>
+```
+
+Creates the live Bloom filter when it does not already exist. `capacity` overrides the configured capacity for this call.
+
+## `exists(item)`
+
+```ts
+filter.exists(item: string): Promise<boolean | null>
+```
+
+Checks one item.
+
+- `true`: the item may exist.
+- `false`: the item definitely does not exist.
+- `null`: the filter is missing; callers should fall back to the authoritative store.
+
+## `mexists(items)`
+
+```ts
+filter.mexists(items: string[]): Promise<Array<boolean | null>>
+```
+
+Checks multiple items. Output order and length match input.
+
+## `existsIfReady(readyKey, item)`
+
+```ts
+filter.existsIfReady(readyKey: string, item: string): Promise<boolean | null>
+```
+
+Checks one item only when both the ready marker and live filter exist. Returns `null` when either key is absent.
+
+## `mexistsIfReady(readyKey, items)`
+
+```ts
+filter.mexistsIfReady(
+  readyKey: string,
+  items: string[],
+): Promise<Array<boolean | null>>
+```
+
+Batch version of `existsIfReady`.
+
+## `add(items)`
+
+```ts
+filter.add(items: string[]): Promise<void>
+```
+
+Adds items in chunks. Errors are routed to the configured Valkey error handler.
+
+If neither the live key nor the building key exists, this is a no-op to avoid auto-creating an undersized filter.
+
+## `addOrThrow(items)`
+
+```ts
+filter.addOrThrow(items: string[]): Promise<void>
+```
+
+Same write path as `add()`, but propagates write errors.
+
+## `addStream(batches)`
+
+```ts
+filter.addStream(batches: AsyncIterable<string[]>): Promise<void>
+```
+
+Adds streamed batches and propagates errors.
+
+## `rebuild(items)`
+
+```ts
+filter.rebuild(items: string[]): Promise<void>
+```
+
+Rebuilds from a complete list using a building key and atomic rename.
+
+## `rebuildFromStream(batches, capacityOverride?)`
+
+```ts
+filter.rebuildFromStream(
+  batches: AsyncIterable<string[]>,
+  capacityOverride?: number,
+): Promise<void>
+```
+
+Rebuilds from streamed batches. `capacityOverride` is useful when the live row count is known at rebuild time.
+
+## `delete()`
+
+```ts
+filter.delete(): Promise<void>
+```
+
+Deletes the live and building keys.
+
+## `deleteWithAdditionalKeys(additionalKeys)`
+
+```ts
+filter.deleteWithAdditionalKeys(additionalKeys: string[]): Promise<void>
+```
+
+Deletes the live key, building key, and additional caller-owned keys such as readiness markers.
+
+## `keyExists()`
+
+```ts
+filter.keyExists(): Promise<boolean>
+```
+
+Returns whether the live filter key exists.
+
+## `isReady(readyKey)`
+
+```ts
+filter.isReady(readyKey: string): Promise<boolean>
+```
+
+Returns `true` only when both the live filter key and `readyKey` exist.
+
+## `getKey()`
+
+```ts
+filter.getKey(): string
+```
+
+Returns the live filter key.
+
+## `getBuildingKey()`
+
+```ts
+filter.getBuildingKey(): string
+```
+
+Returns the staging key used by rebuilds.
+
+## `getConfig()`
+
+```ts
+filter.getConfig(): {
+  name: string;
+  capacity: number;
+  errorRate: number;
+  batchSize: number;
+  liveKey: string;
+  buildingKey: string;
+}
+```
+
+Returns runtime configuration values.
+
+## Helper Exports
+
+```ts
+import {
+  LUA_UNPACK_BATCH_SIZE,
+  isBloomMissingKeyError,
+  normalizeBloomCheckResult,
+} from "valkyries";
+```
+
+- `LUA_UNPACK_BATCH_SIZE`: maximum Lua unpack batch size used internally.
+- `isBloomMissingKeyError(error)`: detects missing Bloom filter errors.
+- `normalizeBloomCheckResult(result)`: normalizes Valkey Bloom return values to booleans.
+
+## Events
+
+The Bloom filter emits:
+
+- `bloom-filter:exists` with `{ name, item, result }`.
+- `bloom-filter:mexists` with `{ name, items, results }`.
+- `bloom-filter:add` with `{ name, items }`.

package/docs/cache.md

@@ -17,3 +17,194 @@ Values larger than 2 KiB are gzip-compressed. Null results are cached with `null
 `cacheGetByAny()` and `cacheGetByAnyBatch()` protect against stale miss writes by setting short-lived invalidation markers during delete operations.
 
 Optional Bloom filter integration can skip authoritative-store calls for definite misses. If the Bloom filter is unavailable or not ready, cache reads fall back to the normal miss path.
+
+## Import
+
+```ts
+import { ValkeyCache } from "valkyries";
+```
+
+or:
+
+```ts
+import { ValkeyCache } from "valkyries/cache";
+```
+
+## Constructor
+
+```ts
+const cache = new ValkeyCache({ prefix: "users", ttlSeconds: 300 });
+```
+
+```ts
+type ValkeyCacheOptions<K = string> = {
+  prefix: string;
+  ttlSeconds: number;
+  nullTtlSeconds?: number;
+  mode?: "json" | "text" | "buffer";
+  staleTtlAge?: number;
+  bloomFilter?: ValkeyBloomFilter;
+  bloomFilterEnabled?: () => boolean;
+  client?: GlideClient;
+  keySerializer?: (key: K) => string;
+};
+```
+
+For non-string keys, `keySerializer` is required.
+
+- `prefix`: namespace for this cache.
+- `ttlSeconds`: TTL for non-null values.
+- `nullTtlSeconds`: TTL for cached nulls. Defaults to `Math.max(1, Math.floor(ttlSeconds / 60))`.
+- `mode`: serialization mode. Defaults to `json`.
+- `staleTtlAge`: refresh-ahead threshold from `0` to `1`. Defaults to `0.9`.
+- `bloomFilter`: optional negative-lookup Bloom filter.
+- `bloomFilterEnabled`: optional per-call gate for Bloom filter checks.
+- `client`: optional `@valkey/valkey-glide` client. Defaults to the package cache client.
+- `keySerializer`: converts keys to strings before trimming and lowercasing.
+
+The constructor throws when `prefix` is empty, `ttlSeconds` is not positive, or `staleTtlAge` is outside `0..1`.
+
+## `cacheGetByAny(fn)`
+
+```ts
+cache.cacheGetByAny<T>(
+  fn: (key: K) => Promise<T | null | undefined>,
+): (key: K) => Promise<T | null>
+```
+
+Returns a read-through single-key cache wrapper.
+
+Behavior:
+
+- Invalid, null, undefined, or empty serialized keys return `null`.
+- Cache hits return the decoded value.
+- Cached nulls return `null` without calling `fn`.
+- Misses call `fn(key)`.
+- `undefined` from `fn` is normalized to `null`.
+- Miss results are written asynchronously when no invalidation marker is present.
+- Stale hits can trigger asynchronous refresh-ahead.
+
+## `cacheGetByAnyBatch(batchFn)`
+
+```ts
+cache.cacheGetByAnyBatch<T>(
+  batchFn: (keys: K[]) => Promise<Array<T | null | undefined>>,
+): (keys: K[]) => Promise<Array<T | null>>
+```
+
+Returns a read-through batch cache wrapper.
+
+Behavior:
+
+- Input order and length are preserved.
+- Invalid keys return `null` in their original output positions.
+- Duplicate serialized keys are fetched once and scattered back to every duplicate position.
+- `batchFn` is called only for real misses.
+- `batchFn` must return an array with exactly the same length as its input.
+- `undefined` values are normalized to `null`.
+- Fetched values are written asynchronously when no invalidation marker is present.
+- Stale hits can trigger asynchronous batch refresh-ahead.
+
+## `get(key)`
+
+```ts
+cache.get(key: K): Promise<string | Buffer | Record<string, unknown> | null>
+```
+
+Reads a cache entry directly without calling a fallback function. Returns `null` for misses, invalid keys, cached nulls, and Bloom-filter negative lookups.
+
+## `getBatch(keys)`
+
+```ts
+cache.getBatch(keys: K[]): Promise<Array<string | Buffer | Record<string, unknown> | null>>
+```
+
+Reads multiple cache entries directly. Output order and length match the input.
+
+## `set(key, value, ttl?)`
+
+```ts
+cache.set(key: K, value: unknown, ttl?: number): Promise<void>
+```
+
+Writes a value directly.
+
+- Positive `ttl` overrides the cache TTL for this entry.
+- `null` and `undefined` values use `nullTtlSeconds`.
+- Invalid keys are ignored.
+- In `text` mode, `value` must be a string.
+- In `buffer` mode, `value` must be a `Buffer`.
+
+## `setBatch(entries)`
+
+```ts
+cache.setBatch(
+  entries: Array<{ key: K; value: unknown; ttl?: number }>,
+): Promise<void>
+```
+
+Writes multiple values directly using a Valkey batch.
+
+## `refreshById(aliases, fetchByKey)`
+
+```ts
+cache.refreshById<T>(
+  aliases: K[],
+  fetchByKey: (key: K) => Promise<T | null | undefined>,
+): Promise<T | null>
+```
+
+Fetches fresh data once using the first valid alias, then writes the result to every valid alias. Use this when one entity can be addressed by several cache keys.
+
+## `delete(...keys)`
+
+```ts
+cache.delete(...keys: K[]): Promise<number>
+```
+
+Deletes cache entries and writes short-lived invalidation markers so in-flight read-through writes do not repopulate stale data.
+
+## `invalidateCacheGetByAny(...keys)`
+
+```ts
+cache.invalidateCacheGetByAny(...keys: K[]): Promise<number>
+```
+
+Alias for `delete(...keys)`.
+
+## `invalidate()`
+
+```ts
+cache.invalidate(): Promise<void>
+```
+
+Deletes every cache key for this cache prefix.
+
+## `ValkeyCache.invalidate(prefix, client?)`
+
+```ts
+ValkeyCache.invalidate(prefix: string, client?: GlideClient): Promise<void>
+```
+
+Deletes every cache key for `prefix`. Passing an empty prefix invalidates all cache namespaces visible to the client.
+
+## `getKey(key)`
+
+```ts
+cache.getKey(key: K): string
+```
+
+Returns the Valkey cache key for a logical key. Throws when the logical key serializes to an invalid cache key.
+
+## Events
+
+The cache emits:
+
+- `cache:call` with cache name, batch flag, hit/miss/bloom-miss counts, and duration.
+- `cache:hit` with `{ cacheName, keys, count }`.
+- `cache:miss` with `{ cacheName, keys, count }`.
+- `cache:bloom-miss` with `{ cacheName, keys, count }`.
+- `cache:set` with `{ cacheName, keys }`.
+- `cache:set-skipped` with `{ cacheName, keys }`.
+- `cache:delete` with `{ cacheName, keys }`.
+- `cache:invalidate` with `{ cacheName }`.

package/docs/clients.md

@@ -11,3 +11,101 @@ Connections are deduplicated by URL, read preference, and lazy-connect setting t
 For libraries, tests, and multi-tenant services, pass a `GlideClient` directly to `ValkeyCache`, `ValkeyBloomFilter`, `DynamicConfig`, or `RateLimiter`.
 
 Use `closeValkeyClients()` or `onGracefulShutdown()` to close package-managed clients and the dynamic-config pub/sub connection.
+
+## Default Clients
+
+```ts
+import { cacheValkeyClient, rateLimiterValkeyClient, dynamicConfigValkeyClient } from "valkyries";
+```
+
+Default clients are created at module load:
+
+- `cacheValkeyClient`: uses `VALKEY_CACHE_URL` or `VALKEY_URL`, reads from replicas when possible.
+- `rateLimiterValkeyClient`: uses `VALKEY_RATE_LIMITER_URL`, `VALKEY_CACHE_URL`, or `VALKEY_URL`, and reads from primary.
+- `dynamicConfigValkeyClient`: uses `VALKEY_DYNAMIC_CONFIG_URL` or `VALKEY_URL`, reads from replicas when possible.
+
+## `ValkeyClientOptions`
+
+```ts
+type ValkeyClientOptions = {
+  readFrom?: "primary" | "preferReplica";
+  lazyConnect?: boolean;
+};
+```
+
+- `readFrom`: Glide read preference.
+- `lazyConnect`: whether Glide should connect lazily. Defaults to `true`.
+
+## `urlsToClients`
+
+```ts
+const urlsToClients: Map<string, GlideClient>;
+```
+
+Registry of package-managed clients keyed by URL, read preference, and lazy-connect setting.
+
+## `upsertValkeyClientByUrl(url, options?)`
+
+```ts
+upsertValkeyClientByUrl(
+  url: string,
+  options?: ValkeyClientOptions,
+): Promise<GlideClient>
+```
+
+Returns an existing matching client or creates and stores a new one.
+
+## `glideConfigFromUrl(url, options?)`
+
+```ts
+glideConfigFromUrl(url: string, options?: ValkeyClientOptions)
+```
+
+Builds a Glide client configuration from `redis://` or `rediss://` URLs.
+
+Supported URL fields:
+
+- host
+- port
+- username
+- password
+- TLS through `rediss://`
+
+Throws `Invalid Valkey URL` for malformed URLs.
+
+## Dynamic Config Pub/Sub Client
+
+```ts
+ensureDynamicConfigValkeySubscriptionClient(): Promise<GlideClient>
+closeDynamicConfigValkeySubscriptionClient(): Promise<void>
+```
+
+`ensureDynamicConfigValkeySubscriptionClient()` creates or returns the shared pub/sub client subscribed to `dynamic-config:*`.
+
+`closeDynamicConfigValkeySubscriptionClient()` unsubscribes and closes the shared pub/sub client.
+
+## Pub/Sub Handlers
+
+```ts
+addPubSubMessageHandler(handler: (msg: PubSubMsg) => void): void
+removePubSubMessageHandler(handler: (msg: PubSubMsg) => void): void
+```
+
+Registers or removes handlers that receive dynamic-config pub/sub messages.
+
+## Shutdown
+
+```ts
+closeValkeyClients(): Promise<void>
+onGracefulShutdown(): Promise<void>
+```
+
+Both exports point to the same idempotent shutdown function. It closes all live dynamic configs, package-managed clients, and the dynamic-config subscription client.
+
+## `deleteKeysWithPrefix(client, pattern)`
+
+```ts
+deleteKeysWithPrefix(client: GlideClient, pattern: string): Promise<void>
+```
+
+Scans keys matching `pattern` and unlinks them in batches. This helper is used by cache and rate-limiter invalidation APIs.

package/docs/dynamic-config.md

@@ -11,3 +11,135 @@ Fields are declared with `fieldTypes` and initialized from `defaultFields`. Miss
 Use `setField()` or `setFields()` to update values. Updates are written with a Lua script that performs `HSET` and `PUBLISH` in one roundtrip.
 
 Each instance subscribes to `dynamic-config:*` and applies matching field updates from pub/sub. Call `close()` in tests and shutdown paths to remove handlers and clear refresh timers.
+
+## Import
+
+```ts
+import { DynamicConfig } from "valkyries";
+```
+
+or:
+
+```ts
+import { DynamicConfig } from "valkyries/dynamic-config";
+```
+
+## Constructor
+
+```ts
+const flags = new DynamicConfig({
+  key: "feature-flags",
+  fieldTypes: { enabled: "boolean", sampleRate: "number" },
+  defaultFields: { enabled: false, sampleRate: 0 },
+});
+```
+
+```ts
+type DynamicConfigOptions = {
+  staleTtlSeconds?: number | null;
+  key: string;
+  fieldTypes: Record<string, "string" | "number" | "boolean">;
+  defaultFields: Record<string, string | number | boolean>;
+  client?: GlideClient;
+};
+```
+
+- `staleTtlSeconds`: refresh interval for local fields. Defaults to `60`.
+- `key`: logical config name. The hash key is `dynamic-config:${key}`.
+- `fieldTypes`: allowed fields and primitive types.
+- `defaultFields`: default values written when fields are missing.
+- `client`: optional `@valkey/valkey-glide` client. Defaults to the package dynamic-config client.
+
+The constructor starts initialization immediately. Call `waitForInitialization()` before reading fields during startup.
+
+Outside `NODE_ENV=test`, constructing multiple `DynamicConfig` instances with the same key throws.
+
+## Public Properties
+
+- `staleTtl`: refresh interval in seconds.
+- `key`: Valkey hash key.
+- `fields`: local field map.
+- `fieldTypes`: field schema.
+- `defaultFields`: default values.
+- `initialization`: initialization promise.
+
+## `waitForInitialization()`
+
+```ts
+config.waitForInitialization(): Promise<void>
+```
+
+Waits for field validation, default writes, initial field loading, pub/sub subscription, and timer creation.
+
+## `getFields()`
+
+```ts
+config.getFields(): Record<string, string | number | boolean>
+```
+
+Returns a plain object snapshot of local fields.
+
+## `setField(name, value)`
+
+```ts
+config.setField(name: string, value: string | number | boolean): Promise<void>
+```
+
+Writes one field and publishes the update atomically. Throws for unknown fields or invalid values for the field type.
+
+## `setFields(fields)`
+
+```ts
+config.setFields(fields: Record<string, string | number | boolean>): Promise<void>
+```
+
+Writes multiple fields and publishes updates atomically. Local state is updated only after the Valkey write succeeds.
+
+## `refresh()`
+
+```ts
+config.refresh(): Promise<void>
+```
+
+Refreshes local fields from Valkey when the stale TTL has elapsed. Concurrent refreshes are coalesced by an optimistic timestamp update.
+
+## `subscribe()`
+
+```ts
+config.subscribe(): Promise<void>
+```
+
+Ensures the shared dynamic-config subscription client exists and registers this config's message handler.
+
+## `unsubscribe()`
+
+```ts
+config.unsubscribe(): void
+```
+
+Removes this config's message handler from the shared pub/sub dispatcher.
+
+## `close()`
+
+```ts
+config.close(): Promise<void>
+```
+
+Marks the config closed, unsubscribes, clears the refresh timer, and removes it from the global dynamic config registry.
+
+## `stringifyField` and `parseField`
+
+```ts
+config.stringifyField(type, value): string;
+config.parseField(type, value): string | number | boolean;
+```
+
+Helpers used internally for Valkey storage and pub/sub messages.
+
+## `dynamicConfigs`
+
+```ts
+import { dynamicConfigs } from "valkyries";
+```
+
+Array of live `DynamicConfig` instances. It is used by `closeValkeyClients()` to close configs during shutdown.