@gravito/stasis 1.0.0-beta.4 → 1.0.0-beta.6

package/dist/index.d.ts

@@ -0,0 +1,450 @@
+import { PlanetCore, GravitoOrbit } from 'gravito-core';
+
+declare class LockTimeoutError extends Error {
+    name: string;
+}
+interface CacheLock {
+    acquire(): Promise<boolean>;
+    release(): Promise<void>;
+    block<T>(seconds: number, callback: () => Promise<T> | T, options?: {
+        sleepMillis?: number;
+    }): Promise<T>;
+}
+declare function sleep(ms: number): Promise<void>;
+
+type CacheKey = string;
+/**
+ * Laravel-like TTL:
+ * - `number` = seconds from now
+ * - `Date` = absolute expiry time
+ * - `null` = forever
+ * - `undefined` = store default / repository default (when applicable)
+ */
+type CacheTtl = number | Date | null | undefined;
+type CacheValue<T = unknown> = T | null;
+declare function normalizeCacheKey(key: string): string;
+declare function ttlToExpiresAt(ttl: CacheTtl, now?: number): number | null | undefined;
+declare function isExpired(expiresAt: number | null | undefined, now?: number): boolean;
+
+interface CacheStore {
+    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;
+}
+interface TaggableStore {
+    flushTags(tags: readonly string[]): Promise<void>;
+    tagKey(key: string, tags: readonly string[]): string;
+    tagIndexAdd(tags: readonly string[], taggedKey: string): void;
+    tagIndexRemove(taggedKey: string): void;
+}
+declare function isTaggableStore(store: CacheStore): store is CacheStore & TaggableStore;
+
+type CacheEventMode = 'sync' | 'async' | 'off';
+type CacheEvents = {
+    hit?: (key: string) => void | Promise<void>;
+    miss?: (key: string) => void | Promise<void>;
+    write?: (key: string) => void | Promise<void>;
+    forget?: (key: string) => void | Promise<void>;
+    flush?: () => void | Promise<void>;
+};
+type CacheRepositoryOptions = {
+    prefix?: string;
+    defaultTtl?: CacheTtl;
+    events?: CacheEvents;
+    eventsMode?: CacheEventMode;
+    throwOnEventError?: boolean;
+    onEventError?: (error: unknown, event: keyof CacheEvents, payload: {
+        key?: string;
+    }) => void;
+};
+declare class CacheRepository {
+    protected readonly store: CacheStore;
+    protected readonly options: CacheRepositoryOptions;
+    constructor(store: CacheStore, options?: CacheRepositoryOptions);
+    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>;
+    get<T = unknown>(key: CacheKey, defaultValue?: T | (() => T | Promise<T>)): Promise<T | null>;
+    has(key: CacheKey): Promise<boolean>;
+    missing(key: CacheKey): Promise<boolean>;
+    put(key: CacheKey, value: unknown, ttl: CacheTtl): Promise<void>;
+    set(key: CacheKey, value: unknown, ttl?: CacheTtl): Promise<void>;
+    add(key: CacheKey, value: unknown, ttl?: CacheTtl): Promise<boolean>;
+    forever(key: CacheKey, value: unknown): Promise<void>;
+    remember<T = unknown>(key: CacheKey, ttl: CacheTtl, callback: () => Promise<T> | T): Promise<T>;
+    rememberForever<T = unknown>(key: CacheKey, callback: () => Promise<T> | T): Promise<T>;
+    many<T = unknown>(keys: readonly CacheKey[]): Promise<Record<string, T | null>>;
+    putMany(values: Record<string, unknown>, ttl: CacheTtl): Promise<void>;
+    /**
+     * Laravel-like flexible cache (stale-while-revalidate).
+     *
+     * - `ttlSeconds`: how long the value is considered fresh
+     * - `staleSeconds`: how long the stale value may be served while a refresh happens
+     */
+    flexible<T = unknown>(key: CacheKey, ttlSeconds: number, staleSeconds: number, callback: () => Promise<T> | T): Promise<T>;
+    private refreshFlexible;
+    pull<T = unknown>(key: CacheKey, defaultValue?: T): Promise<T | null>;
+    forget(key: CacheKey): Promise<boolean>;
+    delete(key: CacheKey): Promise<boolean>;
+    flush(): Promise<void>;
+    clear(): Promise<void>;
+    increment(key: string, value?: number): Promise<number>;
+    decrement(key: string, value?: number): Promise<number>;
+    lock(name: string, seconds?: number): CacheLock | undefined;
+    tags(tags: readonly string[]): CacheRepository;
+    /**
+     * Get the underlying store
+     */
+    getStore(): CacheStore;
+}
+
+interface RateLimiterResponse {
+    allowed: boolean;
+    remaining: number;
+    reset: number;
+}
+declare class RateLimiter {
+    private store;
+    constructor(store: CacheStore);
+    /**
+     * Attempt to acquire a lock
+     * @param key - The unique key (e.g., "ip:127.0.0.1")
+     * @param maxAttempts - Maximum number of attempts allowed
+     * @param decaySeconds - Time in seconds until the limit resets
+     */
+    attempt(key: string, maxAttempts: number, decaySeconds: number): Promise<RateLimiterResponse>;
+    /**
+     * Clear the limiter for a key
+     */
+    clear(key: string): Promise<void>;
+}
+
+type StoreConfig = {
+    driver: 'memory';
+    maxItems?: number;
+} | {
+    driver: 'file';
+    directory: string;
+} | {
+    driver: 'redis';
+    connection?: string;
+    prefix?: string;
+} | {
+    driver: 'null';
+} | {
+    driver: 'provider';
+};
+type CacheConfig = {
+    default?: string;
+    prefix?: string;
+    defaultTtl?: CacheTtl;
+    stores?: Record<string, StoreConfig & {
+        provider?: CacheStore;
+    }>;
+};
+declare class CacheManager {
+    private readonly storeFactory;
+    private readonly config;
+    private readonly events?;
+    private readonly eventOptions?;
+    private stores;
+    constructor(storeFactory: (name: string) => CacheStore, config?: CacheConfig, events?: CacheEvents | undefined, eventOptions?: {
+        mode?: CacheEventMode;
+        throwOnError?: boolean;
+        onError?: (error: unknown, event: keyof CacheEvents, payload: {
+            key?: string;
+        }) => void;
+    } | undefined);
+    /**
+     * Get a rate limiter instance for a store
+     * @param name - Store name (optional, defaults to default store)
+     */
+    limiter(name?: string): RateLimiter;
+    store(name?: string): CacheRepository;
+    /**
+     * Retrieve an item from the cache.
+     *
+     * @param key - The unique cache key.
+     * @param defaultValue - The default value if the key is missing (can be a value or a closure).
+     * @returns The cached value or the default.
+     *
+     * @example
+     * ```typescript
+     * const value = await cache.get('user:1', { name: 'Guest' });
+     * ```
+     */
+    get<T = unknown>(key: string, defaultValue?: T | (() => T | Promise<T>)): Promise<T | null>;
+    /**
+     * Check if an item exists in the cache.
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Check if an item is missing from the cache.
+     */
+    missing(key: string): Promise<boolean>;
+    /**
+     * 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 (or Date).
+     *
+     * @example
+     * ```typescript
+     * await cache.put('key', 'value', 60); // 60 seconds
+     * ```
+     */
+    put(key: string, value: unknown, ttl: CacheTtl): Promise<void>;
+    /**
+     * Store an item in the cache (alias for put with optional TTL).
+     */
+    set(key: string, value: unknown, ttl?: CacheTtl): Promise<void>;
+    /**
+     * Store an item in the cache if it doesn't already exist.
+     *
+     * @returns True if added, false if it already existed.
+     */
+    add(key: string, value: unknown, ttl?: CacheTtl): Promise<boolean>;
+    /**
+     * Store an item in the cache indefinitely.
+     */
+    forever(key: string, value: unknown): Promise<void>;
+    /**
+     * Get an item from the cache, or execute the callback and store the result.
+     *
+     * @param key - The cache key.
+     * @param ttl - Time to live if the item is missing.
+     * @param callback - Closure to execute on miss.
+     * @returns The cached or fetched value.
+     *
+     * @example
+     * ```typescript
+     * const user = await cache.remember('user:1', 60, async () => {
+     *   return await db.findUser(1);
+     * });
+     * ```
+     */
+    remember<T = unknown>(key: string, ttl: CacheTtl, callback: () => Promise<T> | T): Promise<T>;
+    /**
+     * Get an item from the cache, or execute the callback and store the result forever.
+     */
+    rememberForever<T = unknown>(key: string, callback: () => Promise<T> | T): Promise<T>;
+    /**
+     * Retrieve multiple items from the cache.
+     */
+    many<T = unknown>(keys: readonly string[]): Promise<Record<string, T | null>>;
+    /**
+     * Store multiple items in the cache.
+     */
+    putMany(values: Record<string, unknown>, ttl: CacheTtl): Promise<void>;
+    /**
+     * Get an item from the cache, allowing stale data while refreshing in background.
+     *
+     * @param key - Cache key.
+     * @param ttlSeconds - How long the value is considered fresh.
+     * @param staleSeconds - How long to serve stale data while refreshing.
+     * @param callback - Closure to refresh the data.
+     */
+    flexible<T = unknown>(key: string, ttlSeconds: number, staleSeconds: number, callback: () => Promise<T> | T): Promise<T>;
+    /**
+     * Retrieve an item from the cache and delete it.
+     */
+    pull<T = unknown>(key: string, defaultValue?: T): Promise<T | null>;
+    /**
+     * Remove an item from the cache.
+     */
+    forget(key: string): Promise<boolean>;
+    /**
+     * Remove an item from the cache (alias for forget).
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Remove all items from the cache.
+     */
+    flush(): Promise<void>;
+    /**
+     * Clear the entire cache (alias for flush).
+     */
+    clear(): Promise<void>;
+    /**
+     * Increment an integer item in the cache.
+     */
+    increment(key: string, value?: number): Promise<number>;
+    /**
+     * Decrement an integer item in the cache.
+     */
+    decrement(key: string, value?: number): Promise<number>;
+    /**
+     * Get a lock instance.
+     *
+     * @param name - Lock name.
+     * @param seconds - Lock duration.
+     * @returns CacheLock instance.
+     */
+    lock(name: string, seconds?: number): CacheLock | undefined;
+    /**
+     * Access a tagged cache section (only supported by some stores).
+     */
+    tags(tags: readonly string[]): CacheRepository;
+}
+
+type FileStoreOptions = {
+    directory: string;
+};
+declare class FileStore implements CacheStore {
+    private options;
+    constructor(options: FileStoreOptions);
+    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>;
+    lock(name: string, seconds?: number): CacheLock;
+}
+
+type MemoryStoreOptions = {
+    maxItems?: number;
+};
+declare class MemoryStore implements CacheStore, TaggableStore {
+    private options;
+    private entries;
+    private locks;
+    private tagToKeys;
+    private keyToTags;
+    constructor(options?: MemoryStoreOptions);
+    private touchLRU;
+    private pruneIfNeeded;
+    private cleanupExpired;
+    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;
+    tagKey(key: string, tags: readonly string[]): string;
+    tagIndexAdd(tags: readonly string[], taggedKey: string): void;
+    tagIndexRemove(taggedKey: string): void;
+    flushTags(tags: readonly string[]): Promise<void>;
+}
+
+declare class NullStore implements CacheStore {
+    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>;
+}
+
+type RedisStoreOptions = {
+    connection?: string;
+    prefix?: string;
+};
+declare class RedisStore implements CacheStore, TaggableStore {
+    private connectionName?;
+    constructor(options?: RedisStoreOptions);
+    private get client();
+    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>;
+    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>;
+    lock(name: string, seconds?: number): CacheLock;
+}
+
+interface CacheProvider {
+    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>;
+}
+interface CacheService {
+    get<T = unknown>(key: string): Promise<T | null>;
+    set(key: string, value: unknown, ttl?: CacheTtl): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    clear(): Promise<void>;
+    remember<T>(key: string, ttl: CacheTtl, callback: () => Promise<T> | T): Promise<T>;
+}
+declare class MemoryCacheProvider implements CacheProvider {
+    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 = {
+    driver: 'memory';
+    maxItems?: number;
+} | {
+    driver: 'file';
+    directory: string;
+} | {
+    driver: 'redis';
+    connection?: string;
+    prefix?: string;
+} | {
+    driver: 'null';
+} | {
+    driver: 'custom';
+    store: CacheStore;
+} | {
+    driver: 'provider';
+    provider: CacheProvider;
+};
+interface OrbitCacheOptions {
+    exposeAs?: string;
+    default?: string;
+    prefix?: string;
+    defaultTtl?: CacheTtl;
+    stores?: Record<string, OrbitCacheStoreConfig>;
+    eventsMode?: CacheEventMode;
+    throwOnEventError?: boolean;
+    onEventError?: (error: unknown, event: keyof CacheEvents, payload: {
+        key?: string;
+    }) => void;
+    provider?: CacheProvider;
+    defaultTTL?: number;
+}
+/**
+ * OrbitStasis - Cache Orbit
+ *
+ * Provides caching functionality for Gravito applications.
+ */
+declare class OrbitStasis implements GravitoOrbit {
+    private options?;
+    private manager;
+    constructor(options?: OrbitCacheOptions | undefined);
+    install(core: PlanetCore): void;
+    getCache(): CacheManager;
+}
+declare function orbitCache(core: PlanetCore, options?: OrbitCacheOptions): CacheManager;
+/** @deprecated Use OrbitStasis instead */
+declare const OrbitCache: typeof OrbitStasis;
+declare module 'gravito-core' {
+    interface GravitoVariables {
+        /** Cache manager for caching operations */
+        cache?: CacheManager;
+    }
+}
+
+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 };