@gravito/stasis 2.0.0 → 3.0.1

package/dist/index.d.cts

@@ -1,67 +1,295 @@
 import { PlanetCore, GravitoOrbit } from '@gravito/core';
 
+/**
+ * Error thrown when a lock cannot be acquired within the specified timeout.
+ *
+ * @public
+ * @since 3.0.0
+ */
 declare class LockTimeoutError extends Error {
     name: string;
 }
+/**
+ * Interface for a cache-backed distributed lock.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface CacheLock {
+    /**
+     * Attempt to acquire the lock.
+     *
+     * @returns `true` if acquired, `false` otherwise.
+     */
     acquire(): Promise<boolean>;
+    /**
+     * Release the lock.
+     */
     release(): Promise<void>;
+    /**
+     * Attempt to acquire the lock and execute a callback.
+     * If the lock is held by someone else, it will wait (poll) until the timeout.
+     *
+     * @param seconds - Maximum time to wait for the lock in seconds.
+     * @param callback - Function to execute once the lock is acquired.
+     * @param options - Polling options.
+     * @returns The result of the callback.
+     * @throws {LockTimeoutError} If the lock could not be acquired within the timeout.
+     */
     block<T>(seconds: number, callback: () => Promise<T> | T, options?: {
         sleepMillis?: number;
     }): Promise<T>;
 }
+/**
+ * Pause execution for a specified number of milliseconds.
+ *
+ * @param ms - Milliseconds to sleep.
+ * @internal
+ */
 declare function sleep(ms: number): Promise<void>;
 
+/**
+ * Represents a unique identifier for a cached item.
+ *
+ * @public
+ * @since 3.0.0
+ */
 type CacheKey = string;
 /**
- * Laravel-like TTL:
- * - `number` = seconds from now
- * - `Date` = absolute expiry time
- * - `null` = forever
- * - `undefined` = store default / repository default (when applicable)
+ * Time-to-live (TTL) configuration for cache entries.
+ *
+ * - `number`: Seconds from now.
+ * - `Date`: Absolute expiry time.
+ * - `null`: Cache forever.
+ * - `undefined`: Use the store/repository default.
+ *
+ * @public
+ * @since 3.0.0
  */
 type CacheTtl = number | Date | null | undefined;
+/**
+ * Result of a cache retrieval.
+ * Returns the value of type `T` or `null` if not found or expired.
+ *
+ * @public
+ * @since 3.0.0
+ */
 type CacheValue<T = unknown> = T | null;
+/**
+ * Normalize a cache key to ensure it is valid.
+ *
+ * @param key - The raw cache key.
+ * @returns The normalized cache key.
+ * @throws {Error} If the key is empty.
+ *
+ * @public
+ * @since 3.0.0
+ */
 declare function normalizeCacheKey(key: string): string;
+/**
+ * Convert a CacheTtl value to an absolute epoch timestamp.
+ *
+ * @param ttl - The TTL value to convert.
+ * @param now - Optional current timestamp in milliseconds.
+ * @returns The expiration timestamp in milliseconds, null for forever, or undefined.
+ *
+ * @public
+ * @since 3.0.0
+ */
 declare function ttlToExpiresAt(ttl: CacheTtl, now?: number): number | null | undefined;
+/**
+ * Determine if a specific expiration timestamp has passed.
+ *
+ * @param expiresAt - The expiration timestamp in milliseconds (or null for forever).
+ * @param now - Optional current timestamp in milliseconds.
+ * @returns `true` if expired, `false` otherwise.
+ *
+ * @public
+ * @since 3.0.0
+ */
 declare function isExpired(expiresAt: number | null | undefined, now?: number): boolean;
 
+/**
+ * Interface for a low-level cache storage backend.
+ *
+ * All cache drivers (Memory, Redis, etc.) must implement this interface.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface CacheStore {
+    /**
+     * Retrieve an item from the cache by its key.
+     *
+     * @param key - The unique cache key.
+     * @returns A promise that resolves to the cached value, or null if not found or expired.
+     */
     get<T = unknown>(key: CacheKey): Promise<CacheValue<T>>;
+    /**
+     * Store an item in the cache for a specific duration.
+     *
+     * @param key - The unique cache key.
+     * @param value - The value to store.
+     * @param ttl - Time-to-live.
+     */
     put(key: CacheKey, value: unknown, ttl: CacheTtl): Promise<void>;
+    /**
+     * Store an item in the cache only if the key does not already exist.
+     *
+     * @param key - The unique cache key.
+     * @param value - The value to store.
+     * @param ttl - Time-to-live.
+     * @returns A promise that resolves to true if the item was added, false otherwise.
+     */
     add(key: CacheKey, value: unknown, ttl: CacheTtl): Promise<boolean>;
+    /**
+     * Remove an item from the cache by its key.
+     *
+     * @param key - The cache key to remove.
+     * @returns A promise that resolves to true if the item existed and was removed.
+     */
     forget(key: CacheKey): Promise<boolean>;
+    /**
+     * Remove all items from the cache storage.
+     */
     flush(): Promise<void>;
+    /**
+     * Increment the value of a numeric item in the cache.
+     *
+     * @param key - The cache key.
+     * @param value - The amount to increment by.
+     * @returns The new value.
+     */
     increment(key: CacheKey, value?: number): Promise<number>;
+    /**
+     * Decrement the value of a numeric item in the cache.
+     *
+     * @param key - The cache key.
+     * @param value - The amount to decrement by.
+     * @returns The new value.
+     */
     decrement(key: CacheKey, value?: number): Promise<number>;
+    /**
+     * Get a distributed lock instance for the given name.
+     *
+     * @param name - The lock name.
+     * @param seconds - Optional default duration for the lock.
+     * @returns A `CacheLock` instance if supported, otherwise undefined.
+     */
     lock?(name: string, seconds?: number): CacheLock | undefined;
 }
+/**
+ * Interface for cache stores that support grouping entries by tags.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface TaggableStore {
+    /**
+     * Remove all items associated with the given tags.
+     *
+     * @param tags - An array of tag names.
+     */
     flushTags(tags: readonly string[]): Promise<void>;
+    /**
+     * Generate a tagged key for storage based on the provided tags.
+     *
+     * @param key - The original cache key.
+     * @param tags - An array of tag names.
+     * @returns The tagged key string.
+     */
     tagKey(key: string, tags: readonly string[]): string;
+    /**
+     * Add a key to the index for specific tags.
+     *
+     * @param tags - An array of tag names.
+     * @param taggedKey - The key to associate with the tags.
+     */
     tagIndexAdd(tags: readonly string[], taggedKey: string): void;
+    /**
+     * Remove a key from the tag index.
+     *
+     * @param taggedKey - The key to remove from all tag indexes.
+     */
     tagIndexRemove(taggedKey: string): void;
 }
+/**
+ * Type guard to check if a cache store supports tagging.
+ *
+ * @param store - The cache store instance to check.
+ * @returns `true` if the store implements `TaggableStore`.
+ *
+ * @public
+ * @since 3.0.0
+ */
 declare function isTaggableStore(store: CacheStore): store is CacheStore & TaggableStore;
 
+/**
+ * Supported modes for emitting cache events.
+ *
+ * @public
+ * @since 3.0.0
+ */
 type CacheEventMode = 'sync' | 'async' | 'off';
+/**
+ * Event handlers for cache lifecycle events.
+ *
+ * @public
+ * @since 3.0.0
+ */
 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>;
 };
+/**
+ * Options for configuring the `CacheRepository`.
+ *
+ * @public
+ * @since 3.0.0
+ */
 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). @default 'async' */
     eventsMode?: CacheEventMode;
+    /** Whether to throw an error if an event handler fails. @default false */
     throwOnEventError?: boolean;
+    /** Callback triggered when an event handler encounters an error. */
     onEventError?: (error: unknown, event: keyof CacheEvents, payload: {
         key?: string;
     }) => void;
 };
+/**
+ * CacheRepository provides a high-level, developer-friendly API for cache operations.
+ *
+ * It wraps a low-level `CacheStore` and adds features like:
+ * - Key prefixing.
+ * - Event emission (hit, miss, write, etc.).
+ * - Automatic serialization/deserialization.
+ * - Higher-level helpers like `remember`, `flexible`, and `pull`.
+ * - Support for tagged cache entries (if the store supports it).
+ *
+ * @example
+ * ```typescript
+ * const cache = new CacheRepository(redisStore, { prefix: 'app:' });
+ * const user = await cache.remember('user:1', 3600, () => fetchUser(1));
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
 declare class CacheRepository {
     protected readonly store: CacheStore;
     protected readonly options: CacheRepositoryOptions;
@@ -105,11 +333,38 @@ declare class CacheRepository {
     getStore(): CacheStore;
 }
 
+/**
+ * Represents the response from a rate limiting attempt.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface RateLimiterResponse {
+    /** Whether the request is allowed. */
     allowed: boolean;
+    /** Number of attempts remaining within the current window. */
     remaining: number;
+    /** Epoch timestamp in seconds when the rate limit will reset. */
     reset: number;
 }
+/**
+ * RateLimiter provides a simple mechanism for limiting request frequency.
+ *
+ * It uses a `CacheStore` backend to track attempt counts and handle
+ * expiration (sliding or fixed window depending on store capability).
+ *
+ * @example
+ * ```typescript
+ * const limiter = new RateLimiter(cacheStore);
+ * const status = await limiter.attempt('login:127.0.0.1', 5, 60);
+ * if (!status.allowed) {
+ *   throw new Error('Too many attempts');
+ * }
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
 declare class RateLimiter {
     private store;
     constructor(store: CacheStore);
@@ -126,6 +381,12 @@ declare class RateLimiter {
     clear(key: string): Promise<void>;
 }
 
+/**
+ * Configuration for a specific cache store.
+ *
+ * @public
+ * @since 3.0.0
+ */
 type StoreConfig = {
     driver: 'memory';
     maxItems?: number;
@@ -141,14 +402,47 @@ type StoreConfig = {
 } | {
     driver: 'provider';
 };
+/**
+ * Global cache configuration for multiple stores.
+ *
+ * @public
+ * @since 3.0.0
+ */
 type CacheConfig = {
+    /** The name of the default store to use. @default 'memory' */
     default?: string;
+    /** Global prefix for all cache keys across all stores. */
     prefix?: string;
+    /** Global default time-to-live for cache entries. */
     defaultTtl?: CacheTtl;
+    /** Map of named store configurations. */
     stores?: Record<string, StoreConfig & {
         provider?: CacheStore;
     }>;
 };
+/**
+ * CacheManager orchestrates multiple cache stores and provides a unified API.
+ *
+ * It supports various drivers (Memory, File, Redis) and provides both
+ * a multi-store API (`cache.store('redis').get(...)`) and a default store
+ * proxy API (`cache.get(...)`).
+ *
+ * @example
+ * ```typescript
+ * const cache = new CacheManager(factory, {
+ *   default: 'redis',
+ *   stores: {
+ *     redis: { driver: 'redis', prefix: 'myapp:' }
+ *   }
+ * });
+ *
+ * await cache.set('key', 'value', 3600);
+ * const val = await cache.get('key');
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
 declare class CacheManager {
     private readonly storeFactory;
     private readonly config;
@@ -295,9 +589,26 @@ declare class CacheManager {
     tags(tags: readonly string[]): CacheRepository;
 }
 
+/**
+ * Options for configuring the `FileStore`.
+ *
+ * @public
+ * @since 3.0.0
+ */
 type FileStoreOptions = {
+    /** The directory where cache files will be stored. */
     directory: string;
 };
+/**
+ * FileStore implements the `CacheStore` interface using the local file system.
+ *
+ * It stores cache entries as individual JSON files in the specified directory.
+ * While not as fast as memory or Redis, it provides persistent caching across
+ * application restarts without external dependencies.
+ *
+ * @public
+ * @since 3.0.0
+ */
 declare class FileStore implements CacheStore {
     private options;
     constructor(options: FileStoreOptions);
@@ -313,9 +624,25 @@ declare class FileStore implements CacheStore {
     lock(name: string, seconds?: number): CacheLock;
 }
 
+/**
+ * Options for configuring the `MemoryStore`.
+ *
+ * @public
+ * @since 3.0.0
+ */
 type MemoryStoreOptions = {
+    /** Maximum number of items to keep in memory. Uses LRU eviction. */
     maxItems?: number;
 };
+/**
+ * MemoryStore implements the `CacheStore` interface using a Map.
+ *
+ * It provides a fast, non-persistent cache backend with support for
+ * TTL expiration, basic tagging, and local locking.
+ *
+ * @public
+ * @since 3.0.0
+ */
 declare class MemoryStore implements CacheStore, TaggableStore {
     private options;
     private entries;
@@ -340,6 +667,16 @@ declare class MemoryStore implements CacheStore, TaggableStore {
     flushTags(tags: readonly string[]): Promise<void>;
 }
 
+/**
+ * NullStore is a black-hole cache implementation.
+ *
+ * It implements the `CacheStore` interface but does not actually store or
+ * retrieve any data. This is useful for disabling caching entirely or for
+ * testing.
+ *
+ * @public
+ * @since 3.0.0
+ */
 declare class NullStore implements CacheStore {
     get<T = unknown>(_key: CacheKey): Promise<CacheValue<T>>;
     put(_key: CacheKey, _value: unknown, _ttl: CacheTtl): Promise<void>;
@@ -350,10 +687,27 @@ declare class NullStore implements CacheStore {
     decrement(_key: CacheKey, _value?: number): Promise<number>;
 }
 
+/**
+ * Options for configuring the `RedisStore`.
+ *
+ * @public
+ * @since 3.0.0
+ */
 type RedisStoreOptions = {
+    /** The name of the Redis connection to use. */
     connection?: string;
+    /** Optional Redis-level prefix for keys. */
     prefix?: string;
 };
+/**
+ * RedisStore implements the `CacheStore` interface using Redis.
+ *
+ * It provides a distributed, persistent cache backend with support for
+ * atomic increments/decrements, tagging, and distributed locking.
+ *
+ * @public
+ * @since 3.0.0
+ */
 declare class RedisStore implements CacheStore, TaggableStore {
     private connectionName?;
     constructor(options?: RedisStoreOptions);
@@ -372,63 +726,223 @@ declare class RedisStore implements CacheStore, TaggableStore {
     lock(name: string, seconds?: number): CacheLock;
 }
 
-interface CacheProvider {
+/**
+ * Interface for a low-level cache storage provider.
+ *
+ * Use this to implement custom storage backends that can be plugged into Stasis.
+ *
+ * @public
+ * @since 3.0.0
+ */
+interface CacheStorageProvider {
+    /**
+     * Retrieve an item from the cache.
+     *
+     * @param key - The unique cache key.
+     * @returns The cached value, or null if not found.
+     */
     get<T = unknown>(key: string): Promise<T | null>;
+    /**
+     * Store an item in the cache.
+     *
+     * @param key - The unique cache key.
+     * @param value - The value to store.
+     * @param ttl - Time-to-live in seconds.
+     */
     set(key: string, value: unknown, ttl?: number): Promise<void>;
+    /**
+     * Delete an item from the cache.
+     *
+     * @param key - The cache key to remove.
+     */
     delete(key: string): Promise<void>;
+    /**
+     * Clear all items from the cache storage.
+     */
     clear(): Promise<void>;
 }
+/** @deprecated Use CacheStorageProvider instead */
+type CacheProvider = CacheStorageProvider;
+/**
+ * High-level application contract for caching operations.
+ *
+ * This is the public API exposed to the rest of the application via
+ * the request context or service container.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface CacheService {
+    /**
+     * Retrieve an item from the cache.
+     *
+     * @param key - The unique cache key.
+     * @returns The cached value, or null if not found or expired.
+     */
     get<T = unknown>(key: string): Promise<T | null>;
+    /**
+     * Store an item in the cache with an optional TTL.
+     *
+     * @param key - The unique cache key.
+     * @param value - The value to store.
+     * @param ttl - Time-to-live in seconds or an absolute Date.
+     */
     set(key: string, value: unknown, ttl?: CacheTtl): Promise<void>;
+    /**
+     * Determine if an item exists in the cache and is not expired.
+     *
+     * @param key - The cache key to check.
+     * @returns True if the item exists and is valid.
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Store an item in the cache only if it doesn't already exist.
+     *
+     * @param key - The unique cache key.
+     * @param value - The value to store.
+     * @param ttl - Time-to-live.
+     * @returns True if the item was added, false otherwise.
+     */
+    add(key: string, value: unknown, ttl?: CacheTtl): Promise<boolean>;
+    /**
+     * Remove an item from the cache.
+     *
+     * @param key - The cache key to remove.
+     * @returns True if the item existed and was removed.
+     */
     delete(key: string): Promise<boolean>;
-    clear(): Promise<void>;
+    /**
+     * Retrieve an item from the cache and then delete it.
+     *
+     * @param key - The cache key.
+     * @param defaultValue - Optional value to return if not found.
+     * @returns The cached value or the default.
+     */
+    pull<T = unknown>(key: string, defaultValue?: T): Promise<T | null>;
+    /**
+     * Get an item from the cache, or execute the given callback and store the result.
+     *
+     * @param key - The cache key.
+     * @param ttl - Time-to-live if the item needs to be fetched.
+     * @param callback - Closure to execute if the item is missing.
+     * @returns The cached or fetched value.
+     */
     remember<T>(key: string, ttl: CacheTtl, callback: () => Promise<T> | T): Promise<T>;
+    /**
+     * Store an item in the cache indefinitely.
+     *
+     * @param key - The unique cache key.
+     * @param callback - Closure to execute if the item is missing.
+     * @returns The cached or fetched value.
+     */
+    rememberForever<T>(key: string, callback: () => Promise<T> | T): Promise<T>;
+    /**
+     * Clear the entire cache.
+     */
+    clear(): Promise<void>;
 }
-declare class MemoryCacheProvider implements CacheProvider {
+/**
+ * A standard in-memory implementation of `CacheStorageProvider`.
+ *
+ * @public
+ * @since 3.0.0
+ */
+declare class MemoryCacheProvider implements CacheStorageProvider {
     private store;
     get<T = unknown>(key: string): Promise<T | null>;
     set(key: string, value: unknown, ttl?: number): Promise<void>;
     delete(key: string): Promise<void>;
     clear(): Promise<void>;
 }
-type OrbitCacheStoreConfig = {
+/**
+ * Configuration for an individual cache store instance.
+ *
+ * @public
+ * @since 3.0.0
+ */
+type OrbitCacheStoreConfig = 
+/** Simple in-memory cache using a Map. */
+{
     driver: 'memory';
     maxItems?: number;
-} | {
+}
+/** Local file system based cache. */
+ | {
     driver: 'file';
     directory: string;
-} | {
+}
+/** Redis-backed distributed cache. */
+ | {
     driver: 'redis';
     connection?: string;
     prefix?: string;
-} | {
+}
+/** No-op cache that stores nothing. */
+ | {
     driver: 'null';
-} | {
+}
+/** Use a custom implementation of the low-level `CacheStore` interface. */
+ | {
     driver: 'custom';
     store: CacheStore;
-} | {
+}
+/** Use an implementation of the `CacheStorageProvider` interface. */
+ | {
     driver: 'provider';
-    provider: CacheProvider;
+    provider: CacheStorageProvider;
 };
+/**
+ * Options for configuring the `OrbitStasis` cache orbit.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface OrbitCacheOptions {
+    /** The key used to expose the cache manager in the request context. @default 'cache' */
     exposeAs?: string;
+    /** The name of the default store to use for proxy methods. @default 'memory' */
     default?: string;
+    /** Global prefix for all cache keys across all stores. */
     prefix?: string;
+    /** Default time-to-live for cache entries if not specified. @default 60 */
     defaultTtl?: CacheTtl;
+    /** Map of named cache stores and their configurations. */
     stores?: Record<string, OrbitCacheStoreConfig>;
+    /** How to handle cache events (hit/miss/etc) */
     eventsMode?: CacheEventMode;
+    /** Whether to throw if an event listener fails. @default false */
     throwOnEventError?: boolean;
+    /** Custom error handler for cache events. */
     onEventError?: (error: unknown, event: keyof CacheEvents, payload: {
         key?: string;
     }) => void;
-    provider?: CacheProvider;
+    /** @deprecated Use stores mapping with 'provider' driver. */
+    provider?: CacheStorageProvider;
+    /** @deprecated Use defaultTtl. */
     defaultTTL?: number;
 }
 /**
- * OrbitStasis - Cache Orbit
+ * OrbitStasis is the core caching module for Gravito.
+ *
+ * It provides a robust, multi-store cache management system with support for:
+ * - Pluggable backends (Memory, File, Redis).
+ * - Advanced features like tags, distributed locks, and atomic increments.
+ * - Stale-while-revalidate (flexible) caching strategy.
+ * - Integrated rate limiting.
+ *
+ * @example
+ * ```typescript
+ * const stasis = new OrbitStasis({
+ *   default: 'redis',
+ *   stores: {
+ *     redis: { driver: 'redis', connection: 'default' }
+ *   }
+ * });
+ * core.addOrbit(stasis);
+ * ```
  *
- * Provides caching functionality for Gravito applications.
+ * @public
+ * @since 3.0.0
  */
 declare class OrbitStasis implements GravitoOrbit {
     private options?;
@@ -447,4 +961,4 @@ declare module '@gravito/core' {
     }
 }
 
-export { type CacheConfig, type CacheEventMode, type CacheEvents, type CacheKey, type CacheLock, CacheManager, type CacheProvider, CacheRepository, type CacheRepositoryOptions, type CacheService, type CacheStore, type CacheTtl, type CacheValue, FileStore, type FileStoreOptions, LockTimeoutError, MemoryCacheProvider, MemoryStore, type MemoryStoreOptions, NullStore, OrbitCache, type OrbitCacheOptions, type OrbitCacheStoreConfig, OrbitStasis, RateLimiter, type RateLimiterResponse, RedisStore, type RedisStoreOptions, type StoreConfig, type TaggableStore, orbitCache as default, isExpired, isTaggableStore, normalizeCacheKey, sleep, ttlToExpiresAt };
+export { type CacheConfig, type CacheEventMode, type CacheEvents, type CacheKey, type CacheLock, CacheManager, type CacheProvider, CacheRepository, type CacheRepositoryOptions, type CacheService, type CacheStorageProvider, type CacheStore, type CacheTtl, type CacheValue, FileStore, type FileStoreOptions, LockTimeoutError, MemoryCacheProvider, MemoryStore, type MemoryStoreOptions, NullStore, OrbitCache, type OrbitCacheOptions, type OrbitCacheStoreConfig, OrbitStasis, RateLimiter, type RateLimiterResponse, RedisStore, type RedisStoreOptions, type StoreConfig, type TaggableStore, orbitCache as default, isExpired, isTaggableStore, normalizeCacheKey, sleep, ttlToExpiresAt };