@gravito/stasis 3.1.1 → 3.2.0

package/dist/stores/MemoryStore.d.ts

@@ -0,0 +1,261 @@
+import { type CacheLock } from '../locks';
+import type { CacheStore, TaggableStore } from '../store';
+import { type CacheKey, type CacheTtl, type CacheValue } from '../types';
+/**
+ * Configuration options for the `MemoryStore`.
+ *
+ * Used to define the behavior of the in-memory cache, such as eviction policies.
+ *
+ * @public
+ * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const options: MemoryStoreOptions = { maxItems: 500 };
+ * ```
+ */
+export type MemoryStoreOptions = {
+    /**
+     * Maximum number of items to keep in memory.
+     *
+     * When the limit is reached, the Least Recently Used (LRU) item is evicted.
+     * Set to 0 or undefined for unlimited capacity (not recommended for production).
+     */
+    maxItems?: number;
+};
+/**
+ * Performance and usage statistics for the `MemoryStore`.
+ *
+ * Provides insights into cache efficiency and capacity management.
+ *
+ * @public
+ * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const stats: MemoryCacheStats = {
+ *   hits: 100,
+ *   misses: 20,
+ *   hitRate: 0.83,
+ *   size: 500,
+ *   evictions: 5
+ * };
+ * ```
+ */
+export type MemoryCacheStats = {
+    /** Total number of successful cache lookups. */
+    hits: number;
+    /** Total number of failed cache lookups (key not found or expired). */
+    misses: number;
+    /**
+     * The efficiency ratio of the cache.
+     *
+     * Calculated as hits / (hits + misses). Ranges from 0.0 to 1.0.
+     */
+    hitRate: number;
+    /** Current number of active items stored in the cache. */
+    size: number;
+    /** Total number of items removed to make room for new entries. */
+    evictions: number;
+};
+/**
+ * Fast, non-persistent in-memory cache implementation.
+ *
+ * `MemoryStore` provides a high-performance backend for the `CacheStore` interface.
+ * It supports TTL-based expiration, LRU eviction, basic tagging for bulk invalidation,
+ * and local mutex locking for atomic operations.
+ *
+ * @public
+ * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const store = new MemoryStore({ maxItems: 1000 });
+ * await store.put('user:1', { name: 'Alice' }, 3600);
+ * const user = await store.get('user:1');
+ * ```
+ */
+export declare class MemoryStore implements CacheStore, TaggableStore {
+    private entries;
+    private locks;
+    private stats;
+    private tagToKeys;
+    private keyToTags;
+    /**
+     * Creates a new MemoryStore instance.
+     *
+     * @param options - Configuration for capacity and eviction.
+     */
+    constructor(options?: MemoryStoreOptions);
+    /**
+     * Retrieves current performance metrics.
+     *
+     * @returns A snapshot of hits, misses, size, and eviction counts.
+     *
+     * @example
+     * ```typescript
+     * const stats = store.getStats();
+     * console.log(`Cache hit rate: ${stats.hitRate * 100}%`);
+     * ```
+     */
+    getStats(): MemoryCacheStats;
+    private cleanupExpired;
+    /**
+     * Retrieves an item from the cache by its key.
+     *
+     * If the item is expired, it will be automatically removed and `null` will be returned.
+     *
+     * @param key - The unique identifier for the cached item.
+     * @returns The cached value, or `null` if not found or expired.
+     *
+     * @example
+     * ```typescript
+     * const value = await store.get('my-key');
+     * ```
+     */
+    get<T = unknown>(key: CacheKey): Promise<CacheValue<T>>;
+    /**
+     * Stores an item in the cache with a specific TTL.
+     *
+     * If the key already exists, it will be overwritten.
+     *
+     * @param key - The unique identifier for the item.
+     * @param value - The data to store.
+     * @param ttl - Time-to-live in seconds, or a Date object for absolute expiration.
+     *
+     * @example
+     * ```typescript
+     * await store.put('settings', { theme: 'dark' }, 3600);
+     * ```
+     */
+    put(key: CacheKey, value: unknown, ttl: CacheTtl): Promise<void>;
+    /**
+     * Stores an item only if it does not already exist in the cache.
+     *
+     * @param key - The unique identifier for the item.
+     * @param value - The data to store.
+     * @param ttl - Time-to-live in seconds or absolute expiration.
+     * @returns `true` if the item was added, `false` if it already existed.
+     *
+     * @example
+     * ```typescript
+     * const added = await store.add('unique-task', data, 60);
+     * ```
+     */
+    add(key: CacheKey, value: unknown, ttl: CacheTtl): Promise<boolean>;
+    /**
+     * Removes an item from the cache.
+     *
+     * @param key - The unique identifier for the item to remove.
+     * @returns `true` if the item existed and was removed, `false` otherwise.
+     *
+     * @example
+     * ```typescript
+     * await store.forget('user:session');
+     * ```
+     */
+    forget(key: CacheKey): Promise<boolean>;
+    /**
+     * Removes all items from the cache and resets all internal indexes.
+     *
+     * @example
+     * ```typescript
+     * await store.flush();
+     * ```
+     */
+    flush(): Promise<void>;
+    /**
+     * Increments the value of an item in the cache.
+     *
+     * If the key does not exist, it starts from 0.
+     *
+     * @param key - The identifier for the numeric value.
+     * @param value - The amount to increment by (defaults to 1).
+     * @returns The new incremented value.
+     *
+     * @example
+     * ```typescript
+     * const count = await store.increment('page_views');
+     * ```
+     */
+    increment(key: CacheKey, value?: number): Promise<number>;
+    /**
+     * Decrements the value of an item in the cache.
+     *
+     * @param key - The identifier for the numeric value.
+     * @param value - The amount to decrement by (defaults to 1).
+     * @returns The new decremented value.
+     *
+     * @example
+     * ```typescript
+     * const remaining = await store.decrement('stock_count', 5);
+     * ```
+     */
+    decrement(key: CacheKey, value?: number): Promise<number>;
+    /**
+     * Gets the remaining time-to-live for a cached item.
+     *
+     * @param key - The identifier for the cached item.
+     * @returns Remaining seconds, or `null` if the item has no expiration or does not exist.
+     *
+     * @example
+     * ```typescript
+     * const secondsLeft = await store.ttl('token');
+     * ```
+     */
+    ttl(key: CacheKey): Promise<number | null>;
+    /**
+     * Creates a lock instance for managing exclusive access to a resource.
+     *
+     * @param name - The name of the lock.
+     * @param seconds - The duration the lock should be held (defaults to 10).
+     * @returns A `CacheLock` instance.
+     *
+     * @example
+     * ```typescript
+     * const lock = store.lock('process-report', 30);
+     * if (await lock.acquire()) {
+     *   try {
+     *     // Critical section
+     *   } finally {
+     *     await lock.release();
+     *   }
+     * }
+     * ```
+     */
+    lock(name: string, seconds?: number): CacheLock;
+    /**
+     * Generates a tagged key for storage.
+     *
+     * Used internally to prefix keys with their associated tags.
+     *
+     * @param key - The original cache key.
+     * @param tags - List of tags to associate with the key.
+     * @returns A formatted string containing tags and the key.
+     */
+    tagKey(key: string, tags: readonly string[]): string;
+    /**
+     * Indexes a tagged key for bulk invalidation.
+     *
+     * @param tags - The tags to index.
+     * @param taggedKey - The full key (including tag prefix) to store.
+     */
+    tagIndexAdd(tags: readonly string[], taggedKey: string): void;
+    /**
+     * Removes a key from the tag indexes.
+     *
+     * @param taggedKey - The key to remove from all tag sets.
+     */
+    tagIndexRemove(taggedKey: string): void;
+    /**
+     * Invalidates all cache entries associated with any of the given tags.
+     *
+     * @param tags - The tags to flush.
+     *
+     * @example
+     * ```typescript
+     * await store.flushTags(['users', 'profiles']);
+     * ```
+     */
+    flushTags(tags: readonly string[]): Promise<void>;
+}

package/dist/stores/NullStore.d.ts

@@ -0,0 +1,115 @@
+import type { CacheStore } from '../store';
+import type { CacheKey, CacheTtl, CacheValue } from '../types';
+/**
+ * A "black-hole" cache implementation that discards all data.
+ *
+ * NullStore implements the `CacheStore` interface but performs no actual storage
+ * or retrieval operations. It is primarily used to disable caching globally
+ * without changing application logic, or as a mock in testing environments.
+ *
+ * @example
+ * ```typescript
+ * const store = new NullStore();
+ * await store.put('key', 'value', 60);
+ * const value = await store.get('key'); // always returns null
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
+export declare class NullStore implements CacheStore {
+    /**
+     * Simulates a cache miss for any given key.
+     *
+     * @param _key - Identifier for the cached item.
+     * @returns Always `null` regardless of requested key.
+     *
+     * @example
+     * ```typescript
+     * const value = await store.get('my-key');
+     * ```
+     */
+    get<T = unknown>(_key: CacheKey): Promise<CacheValue<T>>;
+    /**
+     * Discards the provided value instead of storing it.
+     *
+     * @param _key - The identifier for the item.
+     * @param _value - The data to be cached.
+     * @param _ttl - Time-to-live in seconds.
+     * @returns Resolves immediately after discarding the data.
+     *
+     * @example
+     * ```typescript
+     * await store.put('user:1', { id: 1 }, 3600);
+     * ```
+     */
+    put(_key: CacheKey, _value: unknown, _ttl: CacheTtl): Promise<void>;
+    /**
+     * Simulates a failed attempt to add an item to the cache.
+     *
+     * Since NullStore does not store data, this method always indicates that
+     * the item was not added.
+     *
+     * @param _key - The identifier for the item.
+     * @param _value - The data to be cached.
+     * @param _ttl - Time-to-live in seconds.
+     * @returns Always returns `false`.
+     *
+     * @example
+     * ```typescript
+     * const added = await store.add('key', 'value', 60); // false
+     * ```
+     */
+    add(_key: CacheKey, _value: unknown, _ttl: CacheTtl): Promise<boolean>;
+    /**
+     * Simulates a failed attempt to remove an item from the cache.
+     *
+     * Since no data is ever stored, there is nothing to remove.
+     *
+     * @param _key - The identifier for the item to remove.
+     * @returns Always returns `false`.
+     *
+     * @example
+     * ```typescript
+     * const forgotten = await store.forget('key'); // false
+     * ```
+     */
+    forget(_key: CacheKey): Promise<boolean>;
+    /**
+     * Performs a no-op flush operation.
+     *
+     * @returns Resolves immediately as there is no data to clear.
+     *
+     * @example
+     * ```typescript
+     * await store.flush();
+     * ```
+     */
+    flush(): Promise<void>;
+    /**
+     * Simulates an increment operation on a non-existent key.
+     *
+     * @param _key - The identifier for the numeric item.
+     * @param _value - The amount to increment by.
+     * @returns Always returns `0`.
+     *
+     * @example
+     * ```typescript
+     * const newValue = await store.increment('counter', 1); // 0
+     * ```
+     */
+    increment(_key: CacheKey, _value?: number): Promise<number>;
+    /**
+     * Simulates a decrement operation on a non-existent key.
+     *
+     * @param _key - The identifier for the numeric item.
+     * @param _value - The amount to decrement by.
+     * @returns Always returns `0`.
+     *
+     * @example
+     * ```typescript
+     * const newValue = await store.decrement('counter', 1); // 0
+     * ```
+     */
+    decrement(_key: CacheKey, _value?: number): Promise<number>;
+}

package/dist/stores/PredictiveStore.d.ts

@@ -0,0 +1,40 @@
+import type { CacheLock } from '../locks';
+import { type AccessPredictor } from '../prediction/AccessPredictor';
+import type { CacheStore } from '../store';
+import type { CacheKey, CacheTtl, CacheValue } from '../types';
+/**
+ * A CacheStore wrapper that predicts usage patterns and prefetches data.
+ *
+ * This store observes access patterns (A -> B) and when A is requested,
+ * automatically attempts to 'touch' B in the underlying store.
+ *
+ * If the underlying store is a TieredStore, this effectively promotes B
+ * from the remote core (e.g. Redis) to the local cache (e.g. Memory)
+ * before it is explicitly requested, reducing latency.
+ *
+ * @public
+ * @since 3.2.0
+ *
+ * @example
+ * ```typescript
+ * const store = new PredictiveStore(new TieredStore(l1, l2));
+ * // Accessing 'a' will prefetch 'b' if a -> b pattern is detected
+ * await store.get('a');
+ * ```
+ */
+export declare class PredictiveStore implements CacheStore {
+    private store;
+    private predictor;
+    constructor(store: CacheStore, options?: {
+        predictor?: AccessPredictor;
+    });
+    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>;
+    lock(name: string, seconds?: number): CacheLock | undefined;
+    ttl(key: CacheKey): Promise<number | null>;
+}

package/dist/stores/RedisStore.d.ts

@@ -0,0 +1,83 @@
+import { type CacheLock } from '../locks';
+import type { CacheStore, TaggableStore } from '../store';
+import { type CacheKey, type CacheTtl, type CacheValue } from '../types';
+/**
+ * Options for configuring the `RedisStore`.
+ *
+ * @public
+ * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const options: RedisStoreOptions = {
+ *   connection: 'primary',
+ *   prefix: 'cache:'
+ * };
+ * ```
+ */
+export 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
+ */
+export declare class RedisStore implements CacheStore, TaggableStore {
+    private connectionName?;
+    /**
+     * Initialize a new RedisStore instance.
+     *
+     * @param options - Redis connection and prefix settings.
+     *
+     * @example
+     * ```typescript
+     * const store = new RedisStore({ prefix: 'app:' });
+     * ```
+     */
+    constructor(options?: RedisStoreOptions);
+    private get client();
+    /**
+     * Retrieve an item from Redis.
+     *
+     * @param key - Unique cache key identifier.
+     * @returns Parsed JSON value or null if missing/expired.
+     * @throws {Error} If Redis connection fails or read errors occur.
+     */
+    get<T = unknown>(key: CacheKey): Promise<CacheValue<T>>;
+    /**
+     * Store an item in Redis.
+     *
+     * @param key - Unique cache key identifier.
+     * @param value - Value to serialize and store.
+     * @param ttl - Expiration duration.
+     * @throws {Error} If Redis connection fails or write errors occur.
+     */
+    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 a numeric value in Redis.
+     *
+     * @param key - Unique cache key identifier.
+     * @param value - Amount to subtract.
+     * @returns Updated numeric value.
+     * @throws {Error} If key is not numeric or Redis errors occur.
+     */
+    decrement(key: CacheKey, value?: number): Promise<number>;
+    tagKey(key: string, _tags: readonly string[]): string;
+    tagIndexAdd(tags: readonly string[], taggedKey: string): Promise<void>;
+    tagIndexRemove(taggedKey: string): Promise<void>;
+    flushTags(tags: readonly string[]): Promise<void>;
+    ttl(key: CacheKey): Promise<number | null>;
+    lock(name: string, seconds?: number): CacheLock;
+}

package/dist/stores/TieredStore.d.ts

@@ -0,0 +1,37 @@
+import type { CacheStore } from '../store';
+import type { CacheKey, CacheTtl } from '../types';
+/**
+ * A multi-level cache store that coordinates access between a fast local L1 cache
+ * and a persistent remote L2 cache.
+ *
+ * It implements the read-through and write-through patterns to ensure that the
+ * most frequently accessed data remains in the fastest storage tier.
+ *
+ * @public
+ * @since 3.2.0
+ *
+ * @example
+ * ```typescript
+ * const store = new TieredStore(new MemoryStore(), new RedisStore());
+ * await store.put('key', 'value', 3600);
+ * ```
+ */
+export declare class TieredStore implements CacheStore {
+    private readonly local;
+    private readonly remote;
+    /**
+     * Initializes a new TieredStore.
+     *
+     * @param local - The L1 cache store (usually MemoryStore).
+     * @param remote - The L2 cache store (usually RedisStore or FileStore).
+     */
+    constructor(local: CacheStore, remote: CacheStore);
+    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>;
+}

package/dist/tagged-store.d.ts

@@ -0,0 +1,29 @@
+import type { CacheLock } from './locks';
+import type { CacheStore } from './store';
+import { type CacheKey, type CacheTtl } from './types';
+/**
+ * A CacheStore wrapper that prefixes keys with tag-based namespacing.
+ *
+ * Used internally by CacheRepository.tags() to create isolated key spaces
+ * for collective cache operations (e.g., flushing all keys with a given tag).
+ *
+ * @internal
+ */
+export declare class TaggedStore implements CacheStore {
+    private readonly store;
+    private readonly tags;
+    constructor(store: CacheStore & {
+        flushTags: (tags: readonly string[]) => Promise<void>;
+        tagKey: (key: string, tags: readonly string[]) => string;
+        tagIndexAdd: (tags: readonly string[], taggedKey: string) => void;
+    }, tags: readonly string[]);
+    private tagged;
+    get<T = unknown>(key: CacheKey): Promise<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>;
+    lock(name: string, seconds?: number): CacheLock | undefined;
+}