valkyries 0.1.0 → 0.1.2

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.

package/docs/events-and-metrics.md

@@ -13,3 +13,102 @@ setValkeyErrorHandler((error) => {
   logger.error(error);
 });
 ```
+
+## `valkeyEvents`
+
+```ts
+import { valkeyEvents } from "valkyries";
+```
+
+`valkeyEvents` is a typed `EventEmitter`.
+
+Example:
+
+```ts
+valkeyEvents.on("cache:call", (event) => {
+  metrics.histogram("cache.call.duration", event.durationMs, {
+    cache: event.cacheName,
+    batch: String(event.batch),
+  });
+});
+```
+
+## `emitValkeyEvent(event, payload)`
+
+```ts
+emitValkeyEvent<K extends keyof ValkeyEventMap>(
+  event: K,
+  ...args: ValkeyEventMap[K]
+): void
+```
+
+Emits an event and routes listener errors to the configured Valkey error handler.
+
+## Event Payloads
+
+Cache events:
+
+```ts
+"cache:call": [{
+  cacheName: string;
+  batch: boolean;
+  hits: number;
+  misses: number;
+  bloomMisses: number;
+  durationMs: number;
+}];
+"cache:hit": [{ cacheName: string; keys: string[]; count: number }];
+"cache:miss": [{ cacheName: string; keys: string[]; count: number }];
+"cache:bloom-miss": [{ cacheName: string; keys: string[]; count: number }];
+"cache:set": [{ cacheName: string; keys: string[] }];
+"cache:set-skipped": [{ cacheName: string; keys: string[] }];
+"cache:delete": [{ cacheName: string; keys: string[] }];
+"cache:invalidate": [{ cacheName: string }];
+```
+
+Bloom filter events:
+
+```ts
+"bloom-filter:exists": [{ name: string; item: string; result: boolean | null }];
+"bloom-filter:mexists": [{
+  name: string;
+  items: string[];
+  results: Array<boolean | null>;
+}];
+"bloom-filter:add": [{ name: string; items: string[] }];
+```
+
+Rate limiter events:
+
+```ts
+"rate-limiter:add": [{ prefix: string; ids: string[] }];
+"rate-limiter:get": [{ prefix: string; ids: string[]; counts: number[] }];
+"rate-limiter:delete": [{ prefix: string; ids: string[] }];
+"rate-limiter:invalidate": [{ prefix: string }];
+```
+
+## `trackCacheCall(metric)`
+
+```ts
+trackCacheCall(metric: {
+  cacheName: string;
+  batch: boolean;
+  hits: number;
+  misses: number;
+  bloomMisses: number;
+  duration: number;
+}): void
+```
+
+Emits `cache:call` with `duration` renamed to `durationMs`.
+
+## Error Handling
+
+```ts
+setValkeyErrorHandler(handler: (error: Error) => void): void
+handleValkeyError(error: unknown): void
+```
+
+`setValkeyErrorHandler()` installs the process-wide handler used for asynchronous write failures, event listener failures, background refresh failures, and other non-fatal Valkey errors.
+
+`handleValkeyError()` normalizes any thrown value to an `Error` and passes it to the configured handler.

package/docs/lua-scripts.md

@@ -5,3 +5,48 @@ Lua scripts live in `scripts/` and are copied to `dist/scripts/` during build.
 Use `loadScript()` and `registerScript()` for package scripts. Registered scripts are released on process exit.
 
 Scripts are used when operations must be atomic or when combining multiple Valkey commands into one roundtrip.
+
+## `loadScript(relativePath, baseUrl)`
+
+```ts
+loadScript(relativePath: string, baseUrl: string | URL): string
+```
+
+Loads a Lua script from `scripts/` relative to `baseUrl`.
+
+## `registerScript(code)`
+
+```ts
+registerScript(code: string): Script
+```
+
+Creates a Glide `Script`, registers it for process-exit release, and returns it.
+
+## Packaged Scripts
+
+Cache scripts:
+
+- `cache-delete-with-invalidation.lua`
+- `cache-set-if-not-invalidated.lua`
+- `get-value-with-ttl.lua`
+- `get-values-with-ttl.lua`
+
+Bloom filter scripts:
+
+- `bloom-filter-add.lua`
+- `bloom-filter-ensure-exists.lua`
+- `bloom-filter-exists.lua`
+- `bloom-filter-exists-if-ready.lua`
+- `bloom-filter-mexists.lua`
+- `bloom-filter-mexists-if-ready.lua`
+- `bloom-filter-reserve.lua`
+
+Dynamic config scripts:
+
+- `dynamic-config-set-fields.lua`
+
+Rate limiter scripts:
+
+- `rate-limiter-add.lua`
+- `rate-limiter-add-and-check.lua`
+- `rate-limiter-get.lua`