@pioneer-platform/pioneer-cache 1.0.0

package/dist/stores/price-cache.js

@@ -0,0 +1,179 @@
+"use strict";
+/*
+    PriceCache - Price-specific cache implementation
+
+    Extends BaseCache with price-specific logic.
+    All common logic is inherited from BaseCache (including all 5 fixes!)
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PriceCache = void 0;
+const base_cache_1 = require("../core/base-cache");
+const log = require('@pioneer-platform/loggerdog')();
+/**
+ * PriceCache - Caches USD prices for assets
+ */
+class PriceCache extends base_cache_1.BaseCache {
+    constructor(redis, markets, config) {
+        const defaultConfig = {
+            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
+     */
+    buildKey(params) {
+        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
+     */
+    async fetchFromSource(params) {
+        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
+     */
+    async getLegacyCached(params) {
+        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, waitForFresh) {
+        const result = await this.get({ caip }, waitForFresh);
+        return result.value?.price || 0;
+    }
+    /**
+     * Get prices for multiple assets (batch operation)
+     */
+    async getBatchPrices(caips, waitForFresh) {
+        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();
+            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();
+        }
+    }
+}
+exports.PriceCache = PriceCache;

package/dist/stores/transaction-cache.d.ts

@@ -0,0 +1,42 @@
+/**
+ * TransactionCache - Caches immutable blockchain transaction data
+ */
+export declare class TransactionCache {
+    private redis;
+    private readonly keyPrefix;
+    private readonly TAG;
+    constructor(redis: any);
+    /**
+     * Get cached transaction data by txid
+     */
+    get(txid: string): Promise<any | null>;
+    /**
+     * Cache transaction data PERMANENTLY (no expiry)
+     * Transactions are immutable - once on the blockchain, they never change
+     */
+    set(txid: string, txData: any): Promise<void>;
+    /**
+     * Get transaction from cache or fetch from source and cache it
+     * Classic cache-aside pattern
+     */
+    getOrFetch(txid: string, fetchFn: () => Promise<any>): Promise<any>;
+    /**
+     * Invalidate cached transaction (useful for unconfirmed transactions)
+     */
+    invalidate(txid: string): Promise<void>;
+    /**
+     * Get cache statistics
+     */
+    getStats(): Promise<{
+        totalKeys: number;
+        memoryUsage: string;
+    }>;
+    /**
+     * Clear all cached transactions (use with caution)
+     */
+    clearAll(): Promise<number>;
+    /**
+     * Build cache key for a transaction
+     */
+    private buildKey;
+}

package/dist/stores/transaction-cache.js

@@ -0,0 +1,148 @@
+"use strict";
+/*
+    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.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransactionCache = void 0;
+const log = require('@pioneer-platform/loggerdog')();
+/**
+ * TransactionCache - Caches immutable blockchain transaction data
+ */
+class TransactionCache {
+    constructor(redis) {
+        this.keyPrefix = 'tx:';
+        this.TAG = ' | TransactionCache | ';
+        this.redis = redis;
+        log.info(this.TAG, 'TransactionCache initialized (permanent caching, no TTL)');
+    }
+    /**
+     * Get cached transaction data by txid
+     */
+    async get(txid) {
+        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, txData) {
+        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, fetchFn) {
+        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) {
+        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() {
+        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() {
+        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
+     */
+    buildKey(txid) {
+        return `${this.keyPrefix}${txid}`;
+    }
+}
+exports.TransactionCache = TransactionCache;

package/dist/types/index.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Cache configuration for a specific cache store
+ */
+export interface CacheConfig {
+    name: string;
+    keyPrefix: string;
+    ttl: number;
+    staleThreshold?: number;
+    enableTTL: boolean;
+    queueName: string;
+    enableQueue: boolean;
+    maxRetries: number;
+    retryDelay: number;
+    blockOnMiss: boolean;
+    enableLegacyFallback: boolean;
+    defaultValue: any;
+    maxConcurrentJobs: number;
+    apiTimeout: number;
+    logCacheHits: boolean;
+    logCacheMisses: boolean;
+    logRefreshJobs: boolean;
+}
+/**
+ * Generic cached value wrapper
+ */
+export interface CachedValue<T> {
+    value: T;
+    timestamp: number;
+    source: string;
+    lastUpdated: string;
+    metadata?: Record<string, any>;
+}
+/**
+ * Cache operation result
+ */
+export interface CacheResult<T> {
+    success: boolean;
+    value?: T;
+    cached: boolean;
+    fresh: boolean;
+    age?: number;
+    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;
+    sources?: Record<string, number>;
+    byNetwork?: Record<string, number>;
+    entriesWithoutTTL?: number;
+    ttl?: number;
+    staleThreshold?: number;
+}
+/**
+ * Refresh job for background workers
+ */
+export interface RefreshJob {
+    type: string;
+    key: string;
+    params: Record<string, any>;
+    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;
+}

package/dist/types/index.js

@@ -0,0 +1,5 @@
+"use strict";
+/*
+    Pioneer Cache - Core Types and Interfaces
+*/
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/workers/refresh-worker.d.ts

@@ -0,0 +1,57 @@
+import type { BaseCache } from '../core/base-cache';
+/**
+ * Worker configuration
+ */
+export interface WorkerConfig {
+    queueName: string;
+    maxRetries: number;
+    retryDelay: number;
+    pollInterval?: number;
+}
+/**
+ * Unified refresh worker that processes jobs for any cache type
+ */
+export declare class RefreshWorker {
+    private redis;
+    private redisQueue;
+    private cacheRegistry;
+    private config;
+    private isRunning;
+    private isProcessing;
+    private pollTimeoutId;
+    constructor(redis: any, config: WorkerConfig);
+    /**
+     * Register a cache instance with this worker
+     * The worker will route jobs to the appropriate cache based on job type
+     */
+    registerCache(cacheName: string, cache: BaseCache<any>): void;
+    /**
+     * Start processing jobs from the queue
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the worker gracefully
+     */
+    stop(): Promise<void>;
+    /**
+     * Poll for next job from the queue
+     */
+    private poll;
+    /**
+     * Schedule next poll
+     */
+    private schedulePoll;
+    /**
+     * Process a single refresh job
+     */
+    private processJob;
+    /**
+     * Get worker statistics
+     */
+    getStats(): Promise<any>;
+}
+/**
+ * Start a unified refresh worker for multiple cache types
+ * Convenience function for common usage
+ */
+export declare function startUnifiedWorker(redis: any, caches: Map<string, BaseCache<any>>, queueName: string, config?: Partial<WorkerConfig>): Promise<RefreshWorker>;