@gravito/stasis 3.1.1 → 3.2.0

package/dist/locks.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Error thrown when a lock cannot be acquired within the specified timeout.
+ *
+ * This error indicates that the maximum waiting time for a distributed lock
+ * has been exceeded without successfully gaining ownership.
+ *
+ * @public
+ * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await cache.lock('resource', 10).block(5, async () => {
+ *     // ...
+ *   });
+ * } catch (error) {
+ *   if (error instanceof LockTimeoutError) {
+ *     console.error('Failed to acquire lock within 5 seconds');
+ *   }
+ * }
+ * ```
+ */
+export declare class LockTimeoutError extends Error {
+    name: string;
+}
+/**
+ * Interface for a cache-backed distributed lock.
+ *
+ * A distributed lock ensures mutual exclusion across multiple processes or
+ * instances by using a shared cache as the synchronization primitive.
+ *
+ * @public
+ * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const lock = cache.lock('process', 60);
+ * const result = await lock.block(10, async () => {
+ *   // Exclusive work
+ *   return 42;
+ * });
+ * ```
+ */
+export interface CacheLock {
+    /**
+     * Attempt to acquire the lock immediately.
+     *
+     * Uses an atomic "set if not exists" operation in the underlying cache
+     * to ensure only one owner can hold the lock at a time.
+     *
+     * @returns `true` if the lock was successfully acquired, `false` if it is already held.
+     * @throws {Error} If the underlying cache store fails.
+     *
+     * @example
+     * ```typescript
+     * const acquired = await lock.acquire();
+     * if (acquired) {
+     *   try {
+     *     // Critical section
+     *   } finally {
+     *     await lock.release();
+     *   }
+     * }
+     * ```
+     */
+    acquire(): Promise<boolean>;
+    /**
+     * Release the lock.
+     *
+     * Removes the lock entry from the cache, allowing other processes to acquire it.
+     * Should typically be called in a `finally` block to ensure the lock is not leaked.
+     *
+     * @returns A promise that resolves when the lock is released.
+     * @throws {Error} If the underlying cache store fails.
+     *
+     * @example
+     * ```typescript
+     * await lock.release();
+     * ```
+     */
+    release(): Promise<void>;
+    /**
+     * Extend the lock's time-to-live (TTL).
+     *
+     * Increases the expiration time of the lock to prevent it from being
+     * automatically released while a long-running task is still in progress.
+     *
+     * @param seconds - Duration in seconds to add to the current TTL.
+     * @returns `true` if the lock was extended (still owned by this process), `false` otherwise.
+     * @throws {Error} If the underlying cache store fails.
+     *
+     * @example
+     * ```typescript
+     * const extended = await lock.extend(30);
+     * if (!extended) {
+     *   throw new Error('Lock lost or expired before extension');
+     * }
+     * ```
+     */
+    extend?(seconds: number): Promise<boolean>;
+    /**
+     * Get the remaining time-to-live for the lock.
+     *
+     * Useful for monitoring or determining if a lock extension is necessary.
+     *
+     * @returns Remaining TTL in seconds. Returns -1 if the lock doesn't exist, or -2 if it has no TTL.
+     * @throws {Error} If the underlying cache store fails.
+     *
+     * @example
+     * ```typescript
+     * const ttl = await lock.getRemainingTime();
+     * if (ttl > 0 && ttl < 5) {
+     *   await lock.extend(10);
+     * }
+     * ```
+     */
+    getRemainingTime?(): Promise<number>;
+    /**
+     * Attempt to acquire the lock and execute a callback with automatic retry.
+     *
+     * If the lock is currently held, this method will poll the cache at regular
+     * intervals until the lock is acquired or the timeout is reached.
+     *
+     * @param seconds - Maximum duration to wait for the lock in seconds.
+     * @param callback - Logic to execute once the lock is successfully acquired.
+     * @param options - Configuration for polling and retry behavior.
+     * @returns The value returned by the callback.
+     * @throws {LockTimeoutError} If the lock cannot be acquired within the specified timeout.
+     * @throws {Error} If the callback throws or the cache store fails.
+     *
+     * @example
+     * ```typescript
+     * const result = await lock.block(10, async () => {
+     *   return await performAtomicOperation();
+     * });
+     * ```
+     */
+    block<T>(seconds: number, callback: () => Promise<T> | T, options?: BlockOptions): Promise<T>;
+}
+/**
+ * Configuration for the `block()` method's retry logic.
+ *
+ * Defines how the lock acquisition should behave when the lock is already held,
+ * including polling intervals and cancellation support.
+ *
+ * @public
+ * @since 3.1.0
+ *
+ * @example
+ * ```typescript
+ * const options: BlockOptions = {
+ *   retryInterval: 250,
+ *   maxRetries: 10
+ * };
+ * ```
+ */
+export interface BlockOptions {
+    /**
+     * Delay between consecutive acquisition attempts.
+     * @defaultValue 100
+     */
+    retryInterval?: number;
+    /**
+     * Maximum number of times to attempt acquisition before failing.
+     * @defaultValue Infinity
+     */
+    maxRetries?: number;
+    /**
+     * Signal to allow external cancellation of the waiting process.
+     *
+     * @example
+     * ```typescript
+     * const controller = new AbortController();
+     * setTimeout(() => controller.abort(), 2000);
+     * await lock.block(10, task, { signal: controller.signal });
+     * ```
+     */
+    signal?: AbortSignal;
+    /**
+     * @deprecated Use `retryInterval` instead.
+     */
+    sleepMillis?: number;
+}
+/**
+ * Pause execution for a specified duration.
+ *
+ * Internal utility used for implementing polling delays in lock acquisition.
+ *
+ * @param ms - Duration to pause in milliseconds.
+ * @returns A promise that resolves after the delay.
+ * @internal
+ */
+export declare function sleep(ms: number): Promise<void>;

package/dist/prediction/AccessPredictor.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Contract for a mechanism that predicts future cache key accesses.
+ *
+ * Implementations observe sequential access patterns to predict which keys
+ * are likely to be requested next, enabling prefetching strategies.
+ *
+ * @public
+ * @since 3.2.0
+ */
+export interface AccessPredictor {
+    /**
+     * Record a cache key access to learn temporal patterns.
+     *
+     * @param key - Cache key currently being accessed.
+     */
+    record(key: string): void;
+    /**
+     * Predict potential future keys based on learned access history.
+     *
+     * @param key - Current cache key acting as the trigger for prediction.
+     * @returns Array of predicted keys, ordered by likelihood.
+     */
+    predict(key: string): string[];
+    /**
+     * Reset all learned transition probabilities and state.
+     */
+    reset(): void;
+}
+/**
+ * A simple Markov Chain predictor (Order-1).
+ *
+ * Records transitions (A -> B) between sequential accesses and predicts
+ * B when A is next encountered. This is particularly effective for
+ * predictable resource loading sequences.
+ *
+ * @public
+ * @since 3.2.0
+ *
+ * @example
+ * ```typescript
+ * const predictor = new MarkovPredictor();
+ * predictor.record('user:1');
+ * predictor.record('user:1:profile');
+ * const next = predictor.predict('user:1'); // ['user:1:profile']
+ * ```
+ */
+export declare class MarkovPredictor implements AccessPredictor {
+    private transitions;
+    private lastKey;
+    private readonly maxNodes;
+    private readonly maxEdgesPerNode;
+    /**
+     * Initialize a new MarkovPredictor.
+     *
+     * @param options - Limits for internal transition graph to manage memory.
+     */
+    constructor(options?: {
+        maxNodes?: number;
+        maxEdgesPerNode?: number;
+    });
+    record(key: string): void;
+    predict(key: string): string[];
+    reset(): void;
+}

package/dist/store.d.ts

@@ -0,0 +1,200 @@
+import type { CacheLock } from './locks';
+import type { CacheKey, CacheTtl, CacheValue } from './types';
+/**
+ * Low-level cache storage contract.
+ *
+ * Defines the essential operations for cache backends. Implementations of this interface
+ * (e.g., Memory, Redis, File) provide the actual persistence logic for the cache system.
+ *
+ * @public
+ * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * class MyStore implements CacheStore {
+ *   async get(key) { ... }
+ *   async put(key, value, ttl) { ... }
+ *   // ... other methods
+ * }
+ * ```
+ */
+export interface CacheStore {
+    /**
+     * Retrieve an item from the cache.
+     *
+     * Fetches the value associated with the given key. If the item has expired or does not exist,
+     * the implementation should return null.
+     *
+     * @param key - Unique identifier for the cached item.
+     * @returns The cached value or null if missing/expired.
+     * @throws {Error} If the storage backend is unreachable or encounters a read failure.
+     */
+    get<T = unknown>(key: CacheKey): Promise<CacheValue<T>>;
+    /**
+     * Store an item in the cache.
+     *
+     * Persists a value with a specific expiration time. Overwrites any existing value for the same key.
+     *
+     * @param key - Unique identifier for the cached item.
+     * @param value - Data to be persisted.
+     * @param ttl - Duration in seconds until the item expires.
+     * @returns Resolves when the write operation completes.
+     * @throws {Error} If the storage backend is full or encounters a write failure.
+     */
+    put(key: CacheKey, value: unknown, ttl: CacheTtl): Promise<void>;
+    /**
+     * Store an item if it does not already exist.
+     *
+     * Atomic operation to ensure a value is only stored if the key is currently vacant.
+     *
+     * @param key - Unique identifier for the cached item.
+     * @param value - Data to be persisted.
+     * @param ttl - Duration in seconds until the item expires.
+     * @returns True if the item was successfully added, false if it already existed.
+     * @throws {Error} If the storage backend encounters a concurrency or write failure.
+     */
+    add(key: CacheKey, value: unknown, ttl: CacheTtl): Promise<boolean>;
+    /**
+     * Remove an item from the cache.
+     *
+     * Deletes the entry associated with the specified key.
+     *
+     * @param key - Identifier of the item to be removed.
+     * @returns True if the item existed and was removed, false otherwise.
+     * @throws {Error} If the storage backend encounters a deletion failure.
+     */
+    forget(key: CacheKey): Promise<boolean>;
+    /**
+     * Wipe all items from the cache storage.
+     *
+     * Clears the entire cache backend. Use with caution as this operation is destructive.
+     *
+     * @returns Resolves when the flush operation completes.
+     * @throws {Error} If the storage backend fails to clear the data.
+     */
+    flush(): Promise<void>;
+    /**
+     * Increment a numeric value in the cache.
+     *
+     * Atomically increases the value of a numeric item. If the key does not exist,
+     * it is typically initialized to zero before incrementing.
+     *
+     * @param key - Identifier of the numeric item.
+     * @param value - Amount to add to the current value.
+     * @returns The updated numeric value.
+     * @throws {TypeError} If the existing value is not numeric.
+     * @throws {Error} If the storage backend encounters an atomic update failure.
+     */
+    increment(key: CacheKey, value?: number): Promise<number>;
+    /**
+     * Decrement a numeric value in the cache.
+     *
+     * Atomically decreases the value of a numeric item. If the key does not exist,
+     * it is typically initialized to zero before decrementing.
+     *
+     * @param key - Identifier of the numeric item.
+     * @param value - Amount to subtract from the current value.
+     * @returns The updated numeric value.
+     * @throws {TypeError} If the existing value is not numeric.
+     * @throws {Error} If the storage backend encounters an atomic update failure.
+     */
+    decrement(key: CacheKey, value?: number): Promise<number>;
+    /**
+     * Create a distributed lock instance.
+     *
+     * Provides a mechanism for mutual exclusion across multiple processes or servers
+     * using the cache backend as the synchronization provider.
+     *
+     * @param name - Unique name for the lock.
+     * @param seconds - Default duration for which the lock should be held.
+     * @returns A lock instance if supported by the driver, otherwise undefined.
+     */
+    lock?(name: string, seconds?: number): CacheLock | undefined;
+    /**
+     * Get the remaining lifetime of a cached item.
+     *
+     * Calculates how many seconds are left before the item expires.
+     *
+     * @param key - Identifier of the cached item.
+     * @returns Seconds remaining until expiration, or null if the key has no TTL or does not exist.
+     * @throws {Error} If the storage backend encounters a read failure.
+     */
+    ttl?(key: CacheKey): Promise<number | null>;
+}
+/**
+ * Contract for cache stores supporting tag-based invalidation.
+ *
+ * Allows grouping cache entries under one or more tags, enabling bulk invalidation
+ * of related items without knowing their individual keys.
+ *
+ * @public
+ * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * if (isTaggableStore(store)) {
+ *   await store.flushTags(['users']);
+ * }
+ * ```
+ */
+export interface TaggableStore {
+    /**
+     * Invalidate all items associated with specific tags.
+     *
+     * Effectively clears all cache entries that were stored with any of the provided tags.
+     *
+     * @param tags - List of tags to be flushed.
+     * @returns Resolves when the tag invalidation completes.
+     * @throws {Error} If the storage backend fails to process the tag flush.
+     */
+    flushTags(tags: readonly string[]): Promise<void>;
+    /**
+     * Compute a namespaced key based on tags.
+     *
+     * Generates a unique internal key that incorporates tag versioning to ensure
+     * proper isolation and invalidation.
+     *
+     * @param key - Original user-provided cache key.
+     * @param tags - Tags to associate with the key.
+     * @returns A derived key string used for actual storage.
+     */
+    tagKey(key: string, tags: readonly string[]): string;
+    /**
+     * Register a key in the tag index.
+     *
+     * Maintains the relationship between tags and their associated keys for tracking.
+     *
+     * @param tags - Tags to index the key under.
+     * @param taggedKey - The derived key to be indexed.
+     * @returns Resolves when the indexing completes.
+     */
+    tagIndexAdd(tags: readonly string[], taggedKey: string): void | Promise<void>;
+    /**
+     * Unregister a key from all tag indexes.
+     *
+     * Removes the tracking information for a specific derived key.
+     *
+     * @param taggedKey - The derived key to remove from indexes.
+     * @returns Resolves when the removal completes.
+     */
+    tagIndexRemove(taggedKey: string): void | Promise<void>;
+}
+/**
+ * Validates if a cache store supports tagging operations.
+ *
+ * Performs a runtime check to determine if the provided store implements the `TaggableStore` interface.
+ *
+ * @param store - The cache store instance to evaluate.
+ * @returns True if the store supports tagging, false otherwise.
+ *
+ * @example
+ * ```typescript
+ * if (isTaggableStore(myStore)) {
+ *   await myStore.flushTags(['users', 'posts']);
+ * }
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
+export declare function isTaggableStore(store: CacheStore): store is CacheStore & TaggableStore;

package/dist/stores/CircuitBreakerStore.d.ts

@@ -0,0 +1,78 @@
+import type { CacheStore } from '../store';
+import type { CacheKey, CacheTtl } from '../types';
+export type CircuitState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+/**
+ * Options for the CircuitBreakerStore.
+ *
+ * @public
+ * @since 3.2.0
+ *
+ * @example
+ * ```typescript
+ * const options: CircuitBreakerOptions = {
+ *   maxFailures: 3,
+ *   resetTimeout: 30000,
+ *   fallback: new MemoryStore()
+ * };
+ * ```
+ */
+export type CircuitBreakerOptions = {
+    /**
+     * Number of consecutive failures before opening the circuit.
+     * @defaultValue 5
+     */
+    maxFailures?: number;
+    /**
+     * Time in milliseconds to stay in OPEN state before transitioning to HALF_OPEN.
+     * @defaultValue 60000
+     */
+    resetTimeout?: number;
+    /**
+     * Optional fallback store to use when the primary store is unavailable.
+     */
+    fallback?: CacheStore;
+};
+/**
+ * A protective wrapper for cache stores that prevents cascading failures
+ * through circuit-breaking logic.
+ *
+ * When the primary store encounters repeated failures, the circuit opens,
+ * temporarily bypassing the primary store and optionally using a fallback.
+ *
+ * @public
+ * @since 3.2.0
+ */
+export declare class CircuitBreakerStore implements CacheStore {
+    private readonly primary;
+    private state;
+    private failures;
+    private lastErrorTime;
+    private options;
+    constructor(primary: CacheStore, options?: CircuitBreakerOptions);
+    private execute;
+    private onSuccess;
+    private onFailure;
+    private handleFallback;
+    get<T = unknown>(key: CacheKey): Promise<T | null>;
+    put(key: CacheKey, value: unknown, ttl: CacheTtl): Promise<void>;
+    add(key: CacheKey, value: unknown, ttl: CacheTtl): Promise<boolean>;
+    forget(key: CacheKey): Promise<boolean>;
+    flush(): Promise<void>;
+    increment(key: CacheKey, value?: number): Promise<number>;
+    decrement(key: CacheKey, value?: number): Promise<number>;
+    ttl(key: CacheKey): Promise<number | null>;
+    /**
+     * Returns current state for monitoring.
+     *
+     * @returns Current state of the circuit breaker.
+     *
+     * @example
+     * ```typescript
+     * const state = store.getState();
+     * if (state === 'OPEN') {
+     *   console.warn('Primary cache is unavailable');
+     * }
+     * ```
+     */
+    getState(): CircuitState;
+}

package/dist/stores/FileStore.d.ts

@@ -0,0 +1,36 @@
+import { type CacheLock } from '../locks';
+import type { CacheStore } from '../store';
+import { type CacheKey, type CacheTtl, type CacheValue } from '../types';
+/**
+ * Configuration options for the `FileStore` implementation.
+ */
+export type FileStoreOptions = {
+    directory: string;
+    enableCleanup?: boolean;
+    cleanupInterval?: number;
+    maxFiles?: number;
+    useSubdirectories?: boolean;
+};
+/**
+ * A persistent filesystem-based implementation of the `CacheStore` interface.
+ */
+export declare class FileStore implements CacheStore {
+    private options;
+    private cleanupTimer;
+    private runtime;
+    constructor(options: FileStoreOptions);
+    private startCleanupDaemon;
+    cleanExpiredFiles(): Promise<number>;
+    destroy(): Promise<void>;
+    private ensureDir;
+    private filePathForKey;
+    get<T = unknown>(key: CacheKey): Promise<CacheValue<T>>;
+    put(key: CacheKey, value: unknown, ttl: CacheTtl): Promise<void>;
+    add(key: CacheKey, value: unknown, ttl: CacheTtl): Promise<boolean>;
+    forget(key: CacheKey): Promise<boolean>;
+    flush(): Promise<void>;
+    increment(key: CacheKey, value?: number): Promise<number>;
+    decrement(key: CacheKey, value?: number): Promise<number>;
+    ttl(key: CacheKey): Promise<number | null>;
+    lock(name: string, seconds?: number): CacheLock;
+}