@pioneer-platform/pioneer-cache 1.0.0

package/src/stores/price-cache.ts

@@ -0,0 +1,215 @@
+/*
+    PriceCache - Price-specific cache implementation
+
+    Extends BaseCache with price-specific logic.
+    All common logic is inherited from BaseCache (including all 5 fixes!)
+*/
+
+import { BaseCache } from '../core/base-cache';
+import type { CacheConfig } from '../types';
+
+const log = require('@pioneer-platform/loggerdog')();
+
+/**
+ * Price data structure
+ */
+export interface PriceData {
+    caip: string;
+    price: number;
+    source?: string;
+}
+
+/**
+ * PriceCache - Caches USD prices for assets
+ */
+export class PriceCache extends BaseCache<PriceData> {
+    private markets: any;
+
+    constructor(redis: any, markets: any, config?: Partial<CacheConfig>) {
+        const defaultConfig: CacheConfig = {
+            name: 'price',
+            keyPrefix: 'price_v2:',
+            ttl: 60 * 60 * 1000,                   // 1 hour
+            staleThreshold: 30 * 60 * 1000,        // 30 minutes (refresh after 30min)
+            enableTTL: true,
+            queueName: 'price-refresh-v2',
+            enableQueue: true,
+            maxRetries: 3,
+            retryDelay: 5000,
+            blockOnMiss: false,                    // Return immediately with $0 (prices less critical)
+            enableLegacyFallback: true,
+            defaultValue: {
+                caip: '',
+                price: 0
+            },
+            maxConcurrentJobs: 5,
+            apiTimeout: 5000,
+            logCacheHits: false,
+            logCacheMisses: true,
+            logRefreshJobs: true
+        };
+
+        super(redis, { ...defaultConfig, ...config });
+        this.markets = markets;
+    }
+
+    /**
+     * Build Redis key for price data
+     * Format: price_v2:caip
+     */
+    protected buildKey(params: Record<string, any>): string {
+        const { caip } = params;
+        if (!caip) {
+            throw new Error('PriceCache.buildKey: caip required');
+        }
+
+        const normalizedCaip = caip.toLowerCase();
+        return `${this.config.keyPrefix}${normalizedCaip}`;
+    }
+
+    /**
+     * Fetch price from markets API
+     */
+    protected async fetchFromSource(params: Record<string, any>): Promise<PriceData> {
+        const tag = this.TAG + 'fetchFromSource | ';
+
+        try {
+            const { caip } = params;
+
+            // Map CAIP to symbol for markets API
+            const assetData = require('@pioneer-platform/pioneer-discovery').assetData;
+            const asset = assetData[caip.toUpperCase()] || assetData[caip.toLowerCase()];
+
+            if (!asset || !asset.symbol) {
+                log.warn(tag, `No asset mapping found for ${caip}`);
+                return {
+                    caip,
+                    price: 0
+                };
+            }
+
+            // Get price from markets module
+            const symbol = asset.symbol.toLowerCase();
+            const priceResult = await this.markets.getPrice(symbol);
+
+            // Handle different response formats
+            let price = 0;
+            if (typeof priceResult === 'object' && priceResult.price) {
+                price = parseFloat(priceResult.price);
+            } else if (typeof priceResult === 'number') {
+                price = priceResult;
+            }
+
+            if (isNaN(price) || price <= 0) {
+                log.warn(tag, `Invalid price for ${caip} (${symbol}): ${priceResult}`);
+                return {
+                    caip,
+                    price: 0
+                };
+            }
+
+            log.debug(tag, `Fetched price for ${caip} (${symbol}): $${price}`);
+
+            return {
+                caip,
+                price,
+                source: 'markets'
+            };
+
+        } catch (error) {
+            log.error(tag, 'Error fetching price:', error);
+            throw error;
+        }
+    }
+
+    /**
+     * Try to get price from legacy cache formats
+     */
+    protected async getLegacyCached(params: Record<string, any>): Promise<PriceData | null> {
+        const tag = this.TAG + 'getLegacyCached | ';
+
+        try {
+            const { caip } = params;
+
+            // Try CoinGecko format first (more accurate)
+            const coingeckoKey = `coingecko:${caip}`;
+            const coingeckoData = await this.redis.get(coingeckoKey);
+
+            if (coingeckoData) {
+                const parsed = JSON.parse(coingeckoData);
+                if (parsed.current_price && typeof parsed.current_price === 'number') {
+                    return {
+                        caip,
+                        price: parsed.current_price,
+                        source: 'coingecko-legacy'
+                    };
+                }
+            }
+
+            // Try CoinCap format
+            const coincapKey = `coincap:${caip}`;
+            const coincapData = await this.redis.get(coincapKey);
+
+            if (coincapData) {
+                const parsed = JSON.parse(coincapData);
+                if (parsed.priceUsd && typeof parsed.priceUsd === 'string') {
+                    const price = parseFloat(parsed.priceUsd);
+                    if (!isNaN(price)) {
+                        return {
+                            caip,
+                            price,
+                            source: 'coincap-legacy'
+                        };
+                    }
+                }
+            }
+
+            return null;
+
+        } catch (error) {
+            log.error(tag, 'Error getting legacy cached price:', error);
+            return null;
+        }
+    }
+
+    /**
+     * Get price for a specific asset
+     * Convenience method that wraps base get()
+     */
+    async getPrice(caip: string, waitForFresh?: boolean): Promise<number> {
+        const result = await this.get({ caip }, waitForFresh);
+        return result.value?.price || 0;
+    }
+
+    /**
+     * Get prices for multiple assets (batch operation)
+     */
+    async getBatchPrices(caips: string[], waitForFresh?: boolean): Promise<Map<string, number>> {
+        const tag = this.TAG + 'getBatchPrices | ';
+        const startTime = Date.now();
+
+        try {
+            log.info(tag, `Batch request for ${caips.length} prices`);
+
+            // Get all prices in parallel
+            const promises = caips.map(caip => this.getPrice(caip, waitForFresh));
+            const results = await Promise.all(promises);
+
+            // Build map of caip -> price
+            const priceMap = new Map<string, number>();
+            caips.forEach((caip, index) => {
+                priceMap.set(caip, results[index]);
+            });
+
+            const responseTime = Date.now() - startTime;
+            log.info(tag, `Batch completed: ${results.length} prices in ${responseTime}ms (${(responseTime / results.length).toFixed(1)}ms avg)`);
+
+            return priceMap;
+
+        } catch (error) {
+            log.error(tag, 'Error in batch price request:', error);
+            // Return empty map
+            return new Map();
+        }
+    }
+}

package/src/stores/transaction-cache.ts

@@ -0,0 +1,172 @@
+/*
+    TransactionCache - Transaction-specific cache implementation
+
+    Different pattern from Balance/Price caches:
+    - Caches transaction data PERMANENTLY (no TTL)
+    - No background refresh (blockchain data is immutable)
+    - Simple cache-aside pattern with getOrFetch()
+    - No workers needed
+
+    Does NOT extend BaseCache - intentionally different architecture.
+*/
+
+const log = require('@pioneer-platform/loggerdog')();
+
+/**
+ * TransactionCache - Caches immutable blockchain transaction data
+ */
+export class TransactionCache {
+    private redis: any;
+    private readonly keyPrefix = 'tx:';
+    private readonly TAG = ' | TransactionCache | ';
+
+    constructor(redis: any) {
+        this.redis = redis;
+        log.info(this.TAG, 'TransactionCache initialized (permanent caching, no TTL)');
+    }
+
+    /**
+     * Get cached transaction data by txid
+     */
+    async get(txid: string): Promise<any | null> {
+        const tag = this.TAG + 'get | ';
+
+        try {
+            const key = this.buildKey(txid);
+            const cached = await this.redis.get(key);
+
+            if (cached) {
+                log.info(tag, `Cache HIT for txid: ${txid.substring(0, 16)}...`);
+                return JSON.parse(cached);
+            }
+
+            log.info(tag, `Cache MISS for txid: ${txid.substring(0, 16)}...`);
+            return null;
+
+        } catch (error) {
+            log.error(tag, `Error getting cached tx ${txid}:`, error);
+            return null; // Fail gracefully
+        }
+    }
+
+    /**
+     * Cache transaction data PERMANENTLY (no expiry)
+     * Transactions are immutable - once on the blockchain, they never change
+     */
+    async set(txid: string, txData: any): Promise<void> {
+        const tag = this.TAG + 'set | ';
+
+        try {
+            const key = this.buildKey(txid);
+
+            // NO TTL - cache permanently
+            await this.redis.set(key, JSON.stringify(txData));
+
+            log.info(tag, `Cached txid: ${txid.substring(0, 16)}... (PERMANENT - no expiry)`);
+
+        } catch (error) {
+            log.error(tag, `Error caching tx ${txid}:`, error);
+            // Don't throw - caching is optional
+        }
+    }
+
+    /**
+     * Get transaction from cache or fetch from source and cache it
+     * Classic cache-aside pattern
+     */
+    async getOrFetch(txid: string, fetchFn: () => Promise<any>): Promise<any> {
+        const tag = this.TAG + 'getOrFetch | ';
+
+        // Try cache first
+        const cached = await this.get(txid);
+        if (cached) {
+            return cached;
+        }
+
+        // Not in cache - fetch from source
+        log.info(tag, `Fetching from source: ${txid.substring(0, 16)}...`);
+        const txData = await fetchFn();
+
+        // Cache the result
+        await this.set(txid, txData);
+
+        return txData;
+    }
+
+    /**
+     * Invalidate cached transaction (useful for unconfirmed transactions)
+     */
+    async invalidate(txid: string): Promise<void> {
+        const tag = this.TAG + 'invalidate | ';
+
+        try {
+            const key = this.buildKey(txid);
+            await this.redis.del(key);
+            log.info(tag, `Invalidated cache for txid: ${txid.substring(0, 16)}...`);
+
+        } catch (error) {
+            log.error(tag, `Error invalidating cached tx ${txid}:`, error);
+        }
+    }
+
+    /**
+     * Get cache statistics
+     */
+    async getStats(): Promise<{ totalKeys: number; memoryUsage: string }> {
+        const tag = this.TAG + 'getStats | ';
+
+        try {
+            const keys = await this.redis.keys(`${this.keyPrefix}*`);
+            const totalKeys = keys.length;
+
+            // Get Redis memory info
+            const info = await this.redis.info('memory');
+            const memoryMatch = info.match(/used_memory_human:(.+)/);
+            const memoryUsage = memoryMatch ? memoryMatch[1].trim() : 'unknown';
+
+            log.info(tag, `Cache stats: ${totalKeys} keys, ${memoryUsage} memory`);
+
+            return {
+                totalKeys,
+                memoryUsage
+            };
+
+        } catch (error) {
+            log.error(tag, 'Error getting cache stats:', error);
+            return {
+                totalKeys: 0,
+                memoryUsage: 'unknown'
+            };
+        }
+    }
+
+    /**
+     * Clear all cached transactions (use with caution)
+     */
+    async clearAll(): Promise<number> {
+        const tag = this.TAG + 'clearAll | ';
+
+        try {
+            const keys = await this.redis.keys(`${this.keyPrefix}*`);
+            if (keys.length === 0) {
+                log.info(tag, 'No cached transactions to clear');
+                return 0;
+            }
+
+            await this.redis.del(...keys);
+            log.info(tag, `Cleared ${keys.length} cached transactions`);
+            return keys.length;
+
+        } catch (error) {
+            log.error(tag, 'Error clearing cache:', error);
+            return 0;
+        }
+    }
+
+    /**
+     * Build cache key for a transaction
+     */
+    private buildKey(txid: string): string {
+        return `${this.keyPrefix}${txid}`;
+    }
+}

package/src/types/index.ts

@@ -0,0 +1,121 @@
+/*
+    Pioneer Cache - Core Types and Interfaces
+*/
+
+/**
+ * Cache configuration for a specific cache store
+ */
+export interface CacheConfig {
+    // Cache identification
+    name: string;                          // e.g., 'balance', 'price', 'transaction'
+    keyPrefix: string;                     // Redis key prefix, e.g., 'balance_v2:'
+
+    // TTL configuration
+    ttl: number;                           // Time-to-live in milliseconds
+    staleThreshold?: number;               // When to trigger background refresh (optional)
+    enableTTL: boolean;                    // Set to false for permanent caching (transactions)
+
+    // Queue configuration
+    queueName: string;                     // Redis queue name
+    enableQueue: boolean;                  // Set to false if no background refresh needed
+    maxRetries: number;                    // Max retry attempts for failed jobs
+    retryDelay: number;                    // Delay between retries in ms
+
+    // Cache behavior
+    blockOnMiss: boolean;                  // Wait for fresh data on cache miss
+    enableLegacyFallback: boolean;         // Try legacy cache keys on miss
+    defaultValue: any;                     // Default value to return on error
+
+    // Performance
+    maxConcurrentJobs: number;             // Max jobs processed concurrently
+    apiTimeout: number;                    // Timeout for source fetch operations
+
+    // Logging
+    logCacheHits: boolean;
+    logCacheMisses: boolean;
+    logRefreshJobs: boolean;
+}
+
+/**
+ * Generic cached value wrapper
+ */
+export interface CachedValue<T> {
+    value: T;
+    timestamp: number;
+    source: string;                        // 'network', 'legacy', 'startup'
+    lastUpdated: string;                   // ISO timestamp
+    metadata?: Record<string, any>;        // Additional metadata
+}
+
+/**
+ * Cache operation result
+ */
+export interface CacheResult<T> {
+    success: boolean;
+    value?: T;
+    cached: boolean;                       // Was value served from cache?
+    fresh: boolean;                        // Is value fresh (not stale)?
+    age?: number;                          // Age of cached value in ms
+    error?: string;
+}
+
+/**
+ * Health check result
+ */
+export interface HealthCheckResult {
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    queueInitialized: boolean;
+    redisConnected: boolean;
+    stats: CacheStats;
+    issues: string[];
+    warnings: string[];
+    timestamp: number;
+    timestampISO: string;
+}
+
+/**
+ * Cache statistics
+ */
+export interface CacheStats {
+    totalEntries: number;
+    staleEntries: number;
+    freshEntries: number;
+    stalenessRate: string;                 // Percentage string
+    sources?: Record<string, number>;
+    byNetwork?: Record<string, number>;
+    entriesWithoutTTL?: number;
+    ttl?: number;                          // Configured TTL
+    staleThreshold?: number;               // Configured stale threshold
+}
+
+/**
+ * Refresh job for background workers
+ */
+export interface RefreshJob {
+    type: string;                          // 'REFRESH_BALANCE', 'REFRESH_PRICE', etc.
+    key: string;                           // Cache key or identifier
+    params: Record<string, any>;           // Job-specific parameters
+    priority?: 'high' | 'normal' | 'low';
+    retryCount?: number;
+    timestamp?: number;
+}
+
+/**
+ * Source fetcher function signature
+ * Returns the data to be cached
+ */
+export type SourceFetcher<T> = (params: Record<string, any>) => Promise<T>;
+
+/**
+ * Key builder function signature
+ * Builds Redis key from parameters
+ */
+export type KeyBuilder = (...args: any[]) => string;
+
+/**
+ * Legacy key pattern for migration
+ */
+export interface LegacyKeyPattern {
+    prefix: string;
+    keyBuilder: KeyBuilder;
+}