@gravito/stasis 3.1.0 → 3.2.0

package/dist/CacheRepository.d.ts

@@ -0,0 +1,495 @@
+import { type CacheEventMode, type CacheEvents } from './cache-events';
+import type { CacheStore } from './store';
+import { type CacheKey, type CacheTtl, type CompressionOptions } from './types';
+export type { CacheEventMode, CacheEvents };
+/**
+ * Options for configuring the `CacheRepository`.
+ *
+ * Controls behavior such as key prefixing, event emission, and background
+ * refresh strategies for flexible caching.
+ *
+ * @public
+ * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const options: CacheRepositoryOptions = {
+ *   prefix: 'v1:',
+ *   defaultTtl: 3600,
+ *   eventsMode: 'async'
+ * };
+ * ```
+ */
+export type CacheRepositoryOptions = {
+    /** Optional prefix for all cache keys. */
+    prefix?: string;
+    /** Default time-to-live for cache entries. */
+    defaultTtl?: CacheTtl;
+    /** Event handlers for cache operations. */
+    events?: CacheEvents;
+    /** Mode for emitting events (sync, async, or off). */
+    eventsMode?: CacheEventMode;
+    /** Whether to throw an error if an event handler fails. @defaultValue false */
+    throwOnEventError?: boolean;
+    /** Callback triggered when an event handler encounters an error. */
+    onEventError?: (error: unknown, event: keyof CacheEvents, payload: {
+        key?: string;
+    }) => void;
+    /** Timeout for background flexible refresh in milliseconds. @defaultValue 30000 */
+    refreshTimeout?: number;
+    /**
+     * Maximum number of retries for the background flexible refresh callback.
+     * @defaultValue 0
+     */
+    maxRetries?: number;
+    /**
+     * Delay between retries for flexible refresh in milliseconds.
+     * @defaultValue 50
+     */
+    retryDelay?: number;
+    /**
+     * Compression settings for cached values.
+     *
+     * @since 3.1.0
+     */
+    compression?: CompressionOptions;
+};
+/**
+ * Statistics for flexible cache operations.
+ *
+ * Tracks the performance and reliability of background refresh operations
+ * used in stale-while-revalidate patterns.
+ *
+ * @public
+ * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const stats: FlexibleStats = {
+ *   refreshCount: 10,
+ *   refreshFailures: 0,
+ *   avgRefreshTime: 15.5
+ * };
+ * ```
+ */
+export type FlexibleStats = {
+    /** Total number of successful background refreshes. */
+    refreshCount: number;
+    /** Total number of background refresh failures (after all retries). */
+    refreshFailures: number;
+    /** Average time taken for a successful refresh in milliseconds. */
+    avgRefreshTime: number;
+};
+/**
+ * High-level API for cache operations.
+ *
+ * Wraps a low-level `CacheStore` to provide developer-friendly features like
+ * key prefixing, event emission, and advanced patterns like `remember` and `flexible`.
+ *
+ * @example
+ * ```typescript
+ * const cache = new CacheRepository(redisStore, { prefix: 'app:' });
+ * const user = await cache.remember('user:1', 3600, () => fetchUser(1));
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
+export declare class CacheRepository {
+    protected readonly store: CacheStore;
+    protected readonly options: CacheRepositoryOptions;
+    private refreshSemaphore;
+    private coalesceSemaphore;
+    private flexibleStats;
+    private eventEmitterConfig;
+    constructor(store: CacheStore, options?: CacheRepositoryOptions);
+    /**
+     * Retrieve statistics about flexible cache operations.
+     *
+     * Useful for monitoring the health and performance of background refreshes.
+     *
+     * @returns Current statistics for background refresh operations.
+     *
+     * @example
+     * ```typescript
+     * const stats = cache.getFlexibleStats();
+     * console.log(`Refreshed ${stats.refreshCount} times`);
+     * ```
+     */
+    getFlexibleStats(): FlexibleStats;
+    private emit;
+    protected key(key: CacheKey): string;
+    protected flexibleFreshUntilKey(fullKey: string): string;
+    protected putMetaKey(metaKey: string, value: unknown, ttl: CacheTtl): Promise<void>;
+    protected forgetMetaKey(metaKey: string): Promise<void>;
+    /**
+     * Retrieve an item from the cache by its key.
+     *
+     * Fetches the value from the underlying store. If not found, returns the
+     * provided default value or executes the factory function.
+     *
+     * @param key - The unique cache key.
+     * @param defaultValue - A default value or factory function to use if the key is not found.
+     * @returns The cached value, or the default value if not found.
+     * @throws {Error} If the underlying store fails to retrieve the value.
+     *
+     * @example
+     * ```typescript
+     * const user = await cache.get('user:1', { name: 'Guest' });
+     * const settings = await cache.get('settings', () => fetchSettings());
+     * ```
+     */
+    get<T = unknown>(key: CacheKey, defaultValue?: T | (() => T | Promise<T>)): Promise<T | null>;
+    /**
+     * Determine if an item exists in the cache.
+     *
+     * Checks for the presence of a key without necessarily returning its value.
+     *
+     * @param key - The cache key.
+     * @returns True if the item exists, false otherwise.
+     * @throws {Error} If the underlying store fails to check existence.
+     *
+     * @example
+     * ```typescript
+     * if (await cache.has('session:active')) {
+     *   // ...
+     * }
+     * ```
+     */
+    has(key: CacheKey): Promise<boolean>;
+    /**
+     * Determine if an item is missing from the cache.
+     *
+     * Inverse of `has()`, used for cleaner conditional logic.
+     *
+     * @param key - The cache key.
+     * @returns True if the item is missing, false otherwise.
+     * @throws {Error} If the underlying store fails to check existence.
+     *
+     * @example
+     * ```typescript
+     * if (await cache.missing('config:loaded')) {
+     *   await loadConfig();
+     * }
+     * ```
+     */
+    missing(key: CacheKey): Promise<boolean>;
+    /**
+     * Store an item in the cache for a specific duration.
+     *
+     * Persists the value in the underlying store with the given TTL.
+     *
+     * @param key - Unique cache key.
+     * @param value - Value to store.
+     * @param ttl - Expiration duration.
+     * @throws {Error} If the underlying store fails to persist the value or serialization fails.
+     *
+     * @example
+     * ```typescript
+     * await cache.put('token', 'xyz123', 3600);
+     * ```
+     */
+    put(key: CacheKey, value: unknown, ttl: CacheTtl): Promise<void>;
+    /**
+     * Store an item in the cache for a specific duration.
+     *
+     * Uses the repository's default TTL if none is provided.
+     *
+     * @param key - The unique cache key.
+     * @param value - The value to store.
+     * @param ttl - Optional time-to-live.
+     * @throws {Error} If the underlying store fails to persist the value.
+     *
+     * @example
+     * ```typescript
+     * await cache.set('theme', 'dark');
+     * ```
+     */
+    set(key: CacheKey, value: unknown, ttl?: CacheTtl): Promise<void>;
+    /**
+     * Store an item in the cache only if the key does not already exist.
+     *
+     * Atomic operation to prevent overwriting existing data.
+     *
+     * @param key - The unique cache key.
+     * @param value - The value to store.
+     * @param ttl - Optional time-to-live.
+     * @returns True if the item was added, false otherwise.
+     * @throws {Error} If the underlying store fails the atomic operation.
+     *
+     * @example
+     * ```typescript
+     * const added = await cache.add('lock:process', true, 60);
+     * ```
+     */
+    add(key: CacheKey, value: unknown, ttl?: CacheTtl): Promise<boolean>;
+    /**
+     * Store an item in the cache indefinitely.
+     *
+     * Sets the TTL to null, indicating the value should not expire automatically.
+     *
+     * @param key - The unique cache key.
+     * @param value - The value to store.
+     * @throws {Error} If the underlying store fails to persist the value.
+     *
+     * @example
+     * ```typescript
+     * await cache.forever('system:id', 'node-01');
+     * ```
+     */
+    forever(key: CacheKey, value: unknown): Promise<void>;
+    /**
+     * Get an item from the cache, or execute the given callback and store the result.
+     *
+     * Implements the "Cache-Aside" pattern, ensuring the callback is only executed
+     * on a cache miss.
+     *
+     * @param key - The unique cache key.
+     * @param ttl - Time-to-live.
+     * @param callback - The callback to execute if the key is not found.
+     * @returns The cached value or the result of the callback.
+     * @throws {Error} If the callback or the underlying store fails.
+     *
+     * @example
+     * ```typescript
+     * const data = await cache.remember('users:all', 300, () => db.users.findMany());
+     * ```
+     */
+    remember<T = unknown>(key: CacheKey, ttl: CacheTtl, callback: () => Promise<T> | T): Promise<T>;
+    /**
+     * Get an item from the cache, or execute the given callback and store the result indefinitely.
+     *
+     * Similar to `remember()`, but the value is stored without an expiration time.
+     *
+     * @param key - The unique cache key.
+     * @param callback - The callback to execute if the key is not found.
+     * @returns The cached value or the result of the callback.
+     * @throws {Error} If the callback or the underlying store fails.
+     *
+     * @example
+     * ```typescript
+     * const config = await cache.rememberForever('app:config', () => loadConfig());
+     * ```
+     */
+    rememberForever<T = unknown>(key: CacheKey, callback: () => Promise<T> | T): Promise<T>;
+    /**
+     * Retrieve multiple items from the cache by their keys.
+     *
+     * Efficiently fetches multiple values, returning a map of keys to values.
+     *
+     * @param keys - An array of unique cache keys.
+     * @returns An object where keys are the original keys and values are the cached values.
+     * @throws {Error} If the underlying store fails to retrieve values.
+     *
+     * @example
+     * ```typescript
+     * const results = await cache.many(['user:1', 'user:2']);
+     * ```
+     */
+    many<T = unknown>(keys: readonly CacheKey[]): Promise<Record<string, T | null>>;
+    /**
+     * Store multiple items in the cache for a specific duration.
+     *
+     * Persists multiple key-value pairs in a single operation if supported by the store.
+     *
+     * @param values - An object where keys are the unique cache keys and values are the values to store.
+     * @param ttl - Time-to-live.
+     * @throws {Error} If the underlying store fails to persist values.
+     *
+     * @example
+     * ```typescript
+     * await cache.putMany({ 'a': 1, 'b': 2 }, 60);
+     * ```
+     */
+    putMany(values: Record<string, unknown>, ttl: CacheTtl): Promise<void>;
+    /**
+     * Laravel-like flexible cache (stale-while-revalidate).
+     *
+     * Serves stale content while revalidating the cache in the background. This
+     * minimizes latency for users by avoiding synchronous revalidation.
+     *
+     * @param key - The unique cache key.
+     * @param ttlSeconds - How long the value is considered fresh.
+     * @param staleSeconds - How long the stale value may be served while a refresh happens.
+     * @param callback - The callback to execute to refresh the cache.
+     * @returns The fresh or stale cached value.
+     * @throws {Error} If the callback fails on a cache miss.
+     *
+     * @example
+     * ```typescript
+     * const value = await cache.flexible('stats', 60, 30, () => fetchStats());
+     * ```
+     */
+    flexible<T = unknown>(key: CacheKey, ttlSeconds: number, staleSeconds: number, callback: () => Promise<T> | T): Promise<T>;
+    private refreshFlexible;
+    private doRefresh;
+    /**
+     * Retrieve an item from the cache and delete it.
+     *
+     * Atomic-like operation to fetch and immediately remove a value, often used
+     * for one-time tokens or flash messages.
+     *
+     * @param key - The unique cache key.
+     * @param defaultValue - A default value to use if the key is not found.
+     * @returns The cached value, or the default value if not found.
+     * @throws {Error} If the underlying store fails to retrieve or forget the value.
+     *
+     * @example
+     * ```typescript
+     * const message = await cache.pull('flash:status');
+     * ```
+     */
+    pull<T = unknown>(key: CacheKey, defaultValue?: T): Promise<T | null>;
+    /**
+     * Remove an item from the cache by its key.
+     *
+     * Deletes the value and any associated metadata from the underlying store.
+     *
+     * @param key - The cache key to remove.
+     * @returns True if the item existed and was removed.
+     * @throws {Error} If the underlying store fails to remove the value.
+     *
+     * @example
+     * ```typescript
+     * const deleted = await cache.forget('user:session');
+     * ```
+     */
+    forget(key: CacheKey): Promise<boolean>;
+    /**
+     * Alias for `forget`.
+     *
+     * Provides compatibility with standard `Map`-like or `Storage` APIs.
+     *
+     * @param key - The cache key to remove.
+     * @returns True if the item existed and was removed.
+     * @throws {Error} If the underlying store fails to remove the value.
+     *
+     * @example
+     * ```typescript
+     * await cache.delete('temp:data');
+     * ```
+     */
+    delete(key: CacheKey): Promise<boolean>;
+    /**
+     * Remove all items from the cache storage.
+     *
+     * Clears the entire underlying store. Use with caution as this affects all
+     * keys regardless of prefix.
+     *
+     * @throws {Error} If the underlying store fails to flush.
+     *
+     * @example
+     * ```typescript
+     * await cache.flush();
+     * ```
+     */
+    flush(): Promise<void>;
+    /**
+     * Alias for `flush`.
+     *
+     * Provides compatibility with standard `Map`-like or `Storage` APIs.
+     *
+     * @throws {Error} If the underlying store fails to clear.
+     *
+     * @example
+     * ```typescript
+     * await cache.clear();
+     * ```
+     */
+    clear(): Promise<void>;
+    /**
+     * Increment the value of a numeric item in the cache.
+     *
+     * Atomically increases the value of a key. If the key does not exist, it is
+     * typically initialized to 0 before incrementing.
+     *
+     * @param key - The cache key.
+     * @param value - The amount to increment by.
+     * @returns The new value.
+     * @throws {Error} If the underlying store fails the atomic increment.
+     *
+     * @example
+     * ```typescript
+     * const count = await cache.increment('page:views');
+     * ```
+     */
+    increment(key: string, value?: number): Promise<number>;
+    /**
+     * Decrement the value of a numeric item in the cache.
+     *
+     * Atomically decreases the value of a key.
+     *
+     * @param key - The cache key.
+     * @param value - The amount to decrement by.
+     * @returns The new value.
+     * @throws {Error} If the underlying store fails the atomic decrement.
+     *
+     * @example
+     * ```typescript
+     * const remaining = await cache.decrement('stock:count');
+     * ```
+     */
+    decrement(key: string, value?: number): Promise<number>;
+    /**
+     * Get a distributed lock instance for the given name.
+     *
+     * Provides a mechanism for exclusive access to resources across multiple
+     * processes or servers.
+     *
+     * @param name - The lock name.
+     * @param seconds - Optional default duration for the lock in seconds.
+     * @returns A `CacheLock` instance if supported, otherwise undefined.
+     *
+     * @example
+     * ```typescript
+     * const lock = cache.lock('process:heavy', 10);
+     * if (await lock.acquire()) {
+     *   try {
+     *     // ...
+     *   } finally {
+     *     await lock.release();
+     *   }
+     * }
+     * ```
+     */
+    lock(name: string, seconds?: number): import("./locks").CacheLock;
+    /**
+     * Create a new repository instance with the given tags.
+     *
+     * Enables grouping of cache entries for collective operations like flushing
+     * all keys associated with specific tags.
+     *
+     * @param tags - An array of tag names.
+     * @returns A new `CacheRepository` instance that uses the given tags.
+     * @throws {Error} If the underlying store does not support tagging.
+     *
+     * @example
+     * ```typescript
+     * await cache.tags(['users', 'profiles']).put('user:1', data, 3600);
+     * await cache.tags(['users']).flush();
+     * ```
+     */
+    tags(tags: readonly string[]): CacheRepository;
+    /**
+     * Retrieve the underlying cache store.
+     *
+     * Provides direct access to the low-level store implementation for advanced
+     * use cases or debugging.
+     *
+     * @returns The low-level cache store instance.
+     *
+     * @example
+     * ```typescript
+     * const store = cache.getStore();
+     * ```
+     */
+    getStore(): CacheStore;
+    /**
+     * Compress a value before storage if compression is enabled and thresholds are met.
+     */
+    private compress;
+    /**
+     * Decompress a value after retrieval if it was previously compressed.
+     */
+    private decompress;
+}

package/dist/RateLimiter.d.ts

@@ -0,0 +1,152 @@
+import type { CacheStore } from './store';
+/**
+ * Represents the response from a rate limiting attempt.
+ *
+ * This interface provides the necessary metadata to determine if a request
+ * should be throttled and when the client can safely retry.
+ *
+ * @public
+ * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const res: RateLimiterResponse = { allowed: true, remaining: 4, reset: 1622548800 };
+ * ```
+ */
+export interface RateLimiterResponse {
+    /** Whether the request is allowed based on current usage and limits. */
+    allowed: boolean;
+    /** Number of attempts remaining within the current time window. */
+    remaining: number;
+    /** Epoch timestamp in seconds when the rate limit window will reset. */
+    reset: number;
+    /** Seconds until the rate limit resets, typically used for the `Retry-After` header. */
+    retryAfter?: number;
+}
+/**
+ * Detailed information about the current rate limit status.
+ *
+ * Used for inspecting the state of a limiter without necessarily
+ * consuming an attempt or triggering a state change.
+ *
+ * @public
+ * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const info: RateLimitInfo = { limit: 10, remaining: 5, reset: 1622548800 };
+ * ```
+ */
+export interface RateLimitInfo {
+    /** Maximum number of attempts allowed within the configured window. */
+    limit: number;
+    /** Number of attempts remaining before the limit is reached. */
+    remaining: number;
+    /** Epoch timestamp in seconds when the rate limit window will reset. */
+    reset: number;
+    /** Seconds until the rate limit resets, only present when the limit has been exceeded. */
+    retryAfter?: number;
+}
+/**
+ * RateLimiter provides a simple mechanism for limiting request frequency.
+ *
+ * It uses a `CacheStore` backend to track attempt counts and handle
+ * expiration. This allows for distributed rate limiting when using
+ * shared stores like Redis, or local limiting with memory stores.
+ *
+ * @example
+ * ```typescript
+ * const limiter = new RateLimiter(cacheStore);
+ * const status = await limiter.attempt('login:127.0.0.1', 5, 60);
+ *
+ * if (!status.allowed) {
+ *   console.log(`Too many attempts. Retry after ${status.retryAfter}s`);
+ * }
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
+export declare class RateLimiter {
+    private store;
+    /**
+     * Creates a new RateLimiter instance.
+     *
+     * @param store - Cache backend used to persist attempt counts.
+     *
+     * @example
+     * ```typescript
+     * const limiter = new RateLimiter(new MemoryStore());
+     * ```
+     */
+    constructor(store: CacheStore);
+    /**
+     * Attempt to consume a slot in the rate limit window.
+     *
+     * This method checks the current attempt count for the given key. If the
+     * count is below the limit, it increments the count and allows the request.
+     * Otherwise, it returns a rejected status with retry information.
+     *
+     * @param key - The unique identifier for the rate limit (e.g., IP address or user ID).
+     * @param maxAttempts - Maximum number of attempts allowed within the decay period.
+     * @param decaySeconds - Duration of the rate limit window in seconds.
+     * @returns A response indicating if the attempt was successful and the remaining capacity.
+     * @throws {Error} If the underlying cache store fails to read or write data.
+     *
+     * @example
+     * ```typescript
+     * const response = await limiter.attempt('api-client:123', 100, 3600);
+     * if (response.allowed) {
+     *   // Proceed with request
+     * }
+     * ```
+     */
+    attempt(key: string, maxAttempts: number, decaySeconds: number): Promise<RateLimiterResponse>;
+    /**
+     * Calculate the number of seconds until the rate limit resets.
+     *
+     * This helper method attempts to retrieve the TTL from the store. If the
+     * store does not support TTL inspection, it falls back to the provided
+     * decay period.
+     *
+     * @param key - Unique identifier for the rate limit.
+     * @param decaySeconds - Default decay period to use as a fallback.
+     * @returns Number of seconds until the key expires.
+     * @throws {Error} If the store fails to retrieve TTL metadata.
+     */
+    availableIn(key: string, decaySeconds: number): Promise<number>;
+    /**
+     * Get detailed information about the current rate limit status without consuming an attempt.
+     *
+     * Useful for returning rate limit headers (e.g., X-RateLimit-Limit) in
+     * middleware or for pre-flight checks.
+     *
+     * @param key - The unique identifier for the rate limit.
+     * @param maxAttempts - Maximum number of attempts allowed.
+     * @param decaySeconds - Duration of the rate limit window in seconds.
+     * @returns Current status including limit, remaining attempts, and reset time.
+     * @throws {Error} If the underlying cache store fails to retrieve data.
+     *
+     * @example
+     * ```typescript
+     * const info = await limiter.getInfo('user:42', 60, 60);
+     * console.log(`Remaining: ${info.remaining}/${info.limit}`);
+     * ```
+     */
+    getInfo(key: string, maxAttempts: number, decaySeconds: number): Promise<RateLimitInfo>;
+    /**
+     * Reset the rate limit counter for a specific key.
+     *
+     * Use this to manually clear a block, for example after a successful
+     * login or when an administrator manually unblocks a user.
+     *
+     * @param key - The unique identifier to clear.
+     * @throws {Error} If the store fails to delete the key.
+     *
+     * @example
+     * ```typescript
+     * await limiter.clear('login-attempts:user@example.com');
+     * ```
+     */
+    clear(key: string): Promise<void>;
+}

package/dist/cache-events.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Cache event system types and dispatcher.
+ *
+ * Provides event mode definitions, event handler contracts,
+ * and the core emit logic for cache lifecycle events.
+ *
+ * @public
+ * @since 3.0.0
+ */
+/**
+ * Supported modes for emitting cache events.
+ *
+ * @public
+ * @since 3.0.0
+ */
+export type CacheEventMode = 'sync' | 'async' | 'off';
+/**
+ * Event handlers for cache lifecycle events.
+ *
+ * @public
+ * @since 3.0.0
+ */
+export type CacheEvents = {
+    /** Triggered on a cache hit. */
+    hit?: (key: string) => void | Promise<void>;
+    /** Triggered on a cache miss. */
+    miss?: (key: string) => void | Promise<void>;
+    /** Triggered when a value is written to the cache. */
+    write?: (key: string) => void | Promise<void>;
+    /** Triggered when a value is removed from the cache. */
+    forget?: (key: string) => void | Promise<void>;
+    /** Triggered when the entire cache is flushed. */
+    flush?: () => void | Promise<void>;
+};
+/**
+ * Configuration for the cache event emitter.
+ *
+ * @internal
+ */
+export type CacheEventEmitterConfig = {
+    mode: CacheEventMode;
+    throwOnError?: boolean;
+    onError?: (error: unknown, event: keyof CacheEvents, payload: {
+        key?: string;
+    }) => void;
+};
+/**
+ * Emit a cache lifecycle event according to the configured mode.
+ *
+ * @param event - The cache event name
+ * @param payload - Event payload
+ * @param events - Event handler map
+ * @param config - Emitter configuration
+ * @internal
+ */
+export declare function emitCacheEvent(event: keyof CacheEvents, payload: {
+    key?: string;
+}, events: CacheEvents | undefined, config: CacheEventEmitterConfig): void | Promise<void>;