@pioneer-platform/pioneer-cache 1.0.0

package/dist/core/cache-manager.js

@@ -0,0 +1,238 @@
+"use strict";
+/*
+    CacheManager - Orchestrates all cache instances
+
+    Central coordinator for all cache types (balance, price, transaction).
+    Manages cache lifecycle, health monitoring, and worker coordination.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CacheManager = void 0;
+const balance_cache_1 = require("../stores/balance-cache");
+const price_cache_1 = require("../stores/price-cache");
+const transaction_cache_1 = require("../stores/transaction-cache");
+const refresh_worker_1 = require("../workers/refresh-worker");
+const log = require('@pioneer-platform/loggerdog')();
+const TAG = ' | CacheManager | ';
+/**
+ * CacheManager - Central coordinator for all caches
+ */
+class CacheManager {
+    constructor(config) {
+        this.workers = [];
+        this.redis = config.redis;
+        // Initialize Balance Cache
+        if (config.enableBalanceCache !== false && config.balanceModule) {
+            this.balanceCache = new balance_cache_1.BalanceCache(this.redis, config.balanceModule);
+            log.info(TAG, '✅ Balance cache initialized');
+        }
+        // Initialize Price Cache
+        if (config.enablePriceCache !== false && config.markets) {
+            this.priceCache = new price_cache_1.PriceCache(this.redis, config.markets);
+            log.info(TAG, '✅ Price cache initialized');
+        }
+        // Initialize Transaction Cache
+        if (config.enableTransactionCache !== false) {
+            this.transactionCache = new transaction_cache_1.TransactionCache(this.redis);
+            log.info(TAG, '✅ Transaction cache initialized');
+        }
+        // Auto-start workers if requested
+        if (config.startWorkers) {
+            setImmediate(() => {
+                this.startWorkers();
+            });
+        }
+        log.info(TAG, '✅ CacheManager initialized');
+    }
+    /**
+     * Start background refresh workers for all caches
+     */
+    async startWorkers() {
+        const tag = TAG + 'startWorkers | ';
+        try {
+            log.info(tag, 'Starting refresh workers...');
+            // Create cache registry for workers
+            const cacheRegistry = new Map();
+            if (this.balanceCache) {
+                cacheRegistry.set('balance', this.balanceCache);
+            }
+            if (this.priceCache) {
+                cacheRegistry.set('price', this.priceCache);
+            }
+            // Start unified worker if we have any caches with queues
+            if (cacheRegistry.size > 0) {
+                const worker = await (0, refresh_worker_1.startUnifiedWorker)(this.redis, cacheRegistry, 'cache-refresh', // Unified queue name
+                {
+                    maxRetries: 3,
+                    retryDelay: 5000,
+                    pollInterval: 100
+                });
+                this.workers.push(worker);
+                log.info(tag, '✅ Refresh worker started for all caches');
+            }
+        }
+        catch (error) {
+            log.error(tag, '❌ Failed to start workers:', error);
+            throw error;
+        }
+    }
+    /**
+     * Stop all workers gracefully
+     */
+    async stopWorkers() {
+        const tag = TAG + 'stopWorkers | ';
+        try {
+            log.info(tag, 'Stopping all workers...');
+            for (const worker of this.workers) {
+                await worker.stop();
+            }
+            this.workers = [];
+            log.info(tag, '✅ All workers stopped');
+        }
+        catch (error) {
+            log.error(tag, 'Error stopping workers:', error);
+            throw error;
+        }
+    }
+    /**
+     * Get aggregate health status for all caches
+     * @param forceRefresh - Force refresh stats (bypasses 30s cache)
+     */
+    async getHealth(forceRefresh = false) {
+        const tag = TAG + 'getHealth | ';
+        try {
+            const checks = {};
+            const issues = [];
+            const warnings = [];
+            // Check balance cache
+            if (this.balanceCache) {
+                const balanceHealth = await this.balanceCache.getHealth(forceRefresh);
+                checks.balance = balanceHealth;
+                if (balanceHealth.status === 'unhealthy') {
+                    issues.push(...balanceHealth.issues.map(i => `Balance: ${i}`));
+                }
+                else if (balanceHealth.status === 'degraded') {
+                    warnings.push(...balanceHealth.warnings.map(w => `Balance: ${w}`));
+                }
+            }
+            // Check price cache
+            if (this.priceCache) {
+                const priceHealth = await this.priceCache.getHealth(forceRefresh);
+                checks.price = priceHealth;
+                if (priceHealth.status === 'unhealthy') {
+                    issues.push(...priceHealth.issues.map(i => `Price: ${i}`));
+                }
+                else if (priceHealth.status === 'degraded') {
+                    warnings.push(...priceHealth.warnings.map(w => `Price: ${w}`));
+                }
+            }
+            // Check transaction cache (simple stats check)
+            if (this.transactionCache) {
+                const txStats = await this.transactionCache.getStats();
+                checks.transaction = {
+                    status: 'healthy',
+                    stats: txStats
+                };
+            }
+            // Check workers
+            for (const worker of this.workers) {
+                const workerStats = await worker.getStats();
+                checks.worker = workerStats;
+                if (!workerStats.isRunning) {
+                    issues.push('Refresh worker not running');
+                }
+            }
+            // Determine overall status
+            let status = 'healthy';
+            if (issues.length > 0) {
+                status = 'unhealthy';
+            }
+            else if (warnings.length > 0) {
+                status = 'degraded';
+            }
+            return {
+                status,
+                queueInitialized: this.workers.length > 0,
+                redisConnected: true,
+                stats: {
+                    totalEntries: 0,
+                    staleEntries: 0,
+                    freshEntries: 0,
+                    stalenessRate: '0%'
+                },
+                issues,
+                warnings,
+                timestamp: Date.now(),
+                timestampISO: new Date().toISOString(),
+                checks
+            };
+        }
+        catch (error) {
+            log.error(tag, 'Health check failed:', error);
+            return {
+                status: 'unhealthy',
+                queueInitialized: false,
+                redisConnected: false,
+                stats: {
+                    totalEntries: 0,
+                    staleEntries: 0,
+                    freshEntries: 0,
+                    stalenessRate: '0%'
+                },
+                issues: [`Health check error: ${error instanceof Error ? error.message : String(error)}`],
+                warnings: [],
+                timestamp: Date.now(),
+                timestampISO: new Date().toISOString()
+            };
+        }
+    }
+    /**
+     * Get all cache instances
+     */
+    getCaches() {
+        return {
+            balance: this.balanceCache,
+            price: this.priceCache,
+            transaction: this.transactionCache
+        };
+    }
+    /**
+     * Get specific cache by name
+     */
+    getCache(name) {
+        switch (name) {
+            case 'balance':
+                return this.balanceCache;
+            case 'price':
+                return this.priceCache;
+            case 'transaction':
+                return this.transactionCache;
+            default:
+                return undefined;
+        }
+    }
+    /**
+     * Clear all caches (use with caution!)
+     */
+    async clearAll() {
+        const tag = TAG + 'clearAll | ';
+        try {
+            const result = {};
+            if (this.balanceCache) {
+                result.balance = await this.balanceCache.clearAll();
+            }
+            if (this.priceCache) {
+                result.price = await this.priceCache.clearAll();
+            }
+            if (this.transactionCache) {
+                result.transaction = await this.transactionCache.clearAll();
+            }
+            log.info(tag, 'Cleared all caches:', result);
+            return result;
+        }
+        catch (error) {
+            log.error(tag, 'Error clearing caches:', error);
+            throw error;
+        }
+    }
+}
+exports.CacheManager = CacheManager;

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { BaseCache } from './core/base-cache';
+export { CacheManager } from './core/cache-manager';
+export { BalanceCache } from './stores/balance-cache';
+export { PriceCache } from './stores/price-cache';
+export { TransactionCache } from './stores/transaction-cache';
+export { RefreshWorker, startUnifiedWorker } from './workers/refresh-worker';
+export type { CacheConfig, CachedValue, CacheResult, RefreshJob, HealthCheckResult, CacheStats } from './types';
+export type { BalanceData } from './stores/balance-cache';
+export type { PriceData } from './stores/price-cache';
+export type { CacheManagerConfig } from './core/cache-manager';
+export type { WorkerConfig } from './workers/refresh-worker';

package/dist/index.js

@@ -0,0 +1,25 @@
+"use strict";
+/*
+    @pioneer-platform/pioneer-cache
+
+    Unified caching system for Pioneer Platform.
+    Provides stale-while-revalidate caching with TTL, background refresh, and health monitoring.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startUnifiedWorker = exports.RefreshWorker = exports.TransactionCache = exports.PriceCache = exports.BalanceCache = exports.CacheManager = exports.BaseCache = void 0;
+// Core exports
+var base_cache_1 = require("./core/base-cache");
+Object.defineProperty(exports, "BaseCache", { enumerable: true, get: function () { return base_cache_1.BaseCache; } });
+var cache_manager_1 = require("./core/cache-manager");
+Object.defineProperty(exports, "CacheManager", { enumerable: true, get: function () { return cache_manager_1.CacheManager; } });
+// Cache implementations
+var balance_cache_1 = require("./stores/balance-cache");
+Object.defineProperty(exports, "BalanceCache", { enumerable: true, get: function () { return balance_cache_1.BalanceCache; } });
+var price_cache_1 = require("./stores/price-cache");
+Object.defineProperty(exports, "PriceCache", { enumerable: true, get: function () { return price_cache_1.PriceCache; } });
+var transaction_cache_1 = require("./stores/transaction-cache");
+Object.defineProperty(exports, "TransactionCache", { enumerable: true, get: function () { return transaction_cache_1.TransactionCache; } });
+// Worker exports
+var refresh_worker_1 = require("./workers/refresh-worker");
+Object.defineProperty(exports, "RefreshWorker", { enumerable: true, get: function () { return refresh_worker_1.RefreshWorker; } });
+Object.defineProperty(exports, "startUnifiedWorker", { enumerable: true, get: function () { return refresh_worker_1.startUnifiedWorker; } });

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

@@ -0,0 +1,47 @@
+import { BaseCache } from '../core/base-cache';
+import type { CacheConfig } from '../types';
+/**
+ * Balance data structure
+ */
+export interface BalanceData {
+    caip: string;
+    pubkey: string;
+    balance: string;
+    priceUsd?: string;
+    valueUsd?: string;
+    symbol?: string;
+    name?: string;
+    networkId?: string;
+}
+/**
+ * BalanceCache - Caches blockchain balance data
+ */
+export declare class BalanceCache extends BaseCache<BalanceData> {
+    private balanceModule;
+    constructor(redis: any, balanceModule: any, config?: Partial<CacheConfig>);
+    /**
+     * Build Redis key for balance data
+     * Format: balance_v2:caip:pubkey
+     */
+    protected buildKey(params: Record<string, any>): string;
+    /**
+     * Fetch balance from blockchain via balance module
+     */
+    protected fetchFromSource(params: Record<string, any>): Promise<BalanceData>;
+    /**
+     * Try to get balance from legacy cache format
+     */
+    protected getLegacyCached(params: Record<string, any>): Promise<BalanceData | null>;
+    /**
+     * Get balance for a specific asset and pubkey
+     * Convenience method that wraps base get()
+     */
+    getBalance(caip: string, pubkey: string, waitForFresh?: boolean): Promise<BalanceData>;
+    /**
+     * Get balances for multiple assets (batch operation)
+     */
+    getBatchBalances(items: Array<{
+        caip: string;
+        pubkey: string;
+    }>, waitForFresh?: boolean): Promise<BalanceData[]>;
+}

package/dist/stores/balance-cache.js

@@ -0,0 +1,158 @@
+"use strict";
+/*
+    BalanceCache - Balance-specific cache implementation
+
+    Extends BaseCache with balance-specific logic.
+    All common logic is inherited from BaseCache.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BalanceCache = void 0;
+const base_cache_1 = require("../core/base-cache");
+const log = require('@pioneer-platform/loggerdog')();
+/**
+ * BalanceCache - Caches blockchain balance data
+ */
+class BalanceCache extends base_cache_1.BaseCache {
+    constructor(redis, balanceModule, config) {
+        const defaultConfig = {
+            name: 'balance',
+            keyPrefix: 'balance_v2:',
+            ttl: 5 * 60 * 1000, // 5 minutes
+            staleThreshold: 2 * 60 * 1000, // 2 minutes
+            enableTTL: true,
+            queueName: 'balance-refresh-v2',
+            enableQueue: true,
+            maxRetries: 3,
+            retryDelay: 10000,
+            blockOnMiss: true, // Wait for fresh data on first request
+            enableLegacyFallback: true,
+            defaultValue: {
+                caip: '',
+                pubkey: '',
+                balance: '0',
+            },
+            maxConcurrentJobs: 10,
+            apiTimeout: 15000,
+            logCacheHits: false,
+            logCacheMisses: true,
+            logRefreshJobs: true
+        };
+        super(redis, { ...defaultConfig, ...config });
+        this.balanceModule = balanceModule;
+    }
+    /**
+     * Build Redis key for balance data
+     * Format: balance_v2:caip:pubkey
+     */
+    buildKey(params) {
+        const { caip, pubkey } = params;
+        if (!caip || !pubkey) {
+            throw new Error('BalanceCache.buildKey: caip and pubkey required');
+        }
+        const normalizedCaip = caip.toLowerCase();
+        // Don't lowercase pubkeys - xpub/ypub/zpub are case-sensitive base58
+        const normalizedPubkey = pubkey;
+        return `${this.config.keyPrefix}${normalizedCaip}:${normalizedPubkey}`;
+    }
+    /**
+     * Fetch balance from blockchain via balance module
+     */
+    async fetchFromSource(params) {
+        const tag = this.TAG + 'fetchFromSource | ';
+        try {
+            const { caip, pubkey } = params;
+            // Fetch balance using balance module
+            const asset = { caip };
+            const owner = { pubkey };
+            const balanceInfo = await this.balanceModule.getBalance(asset, owner);
+            if (!balanceInfo || !balanceInfo.balance) {
+                log.warn(tag, `No balance returned for ${caip}/${pubkey.substring(0, 10)}...`);
+                return {
+                    caip,
+                    pubkey,
+                    balance: '0'
+                };
+            }
+            // Get asset metadata
+            const assetData = require('@pioneer-platform/pioneer-discovery').assetData;
+            const { caipToNetworkId } = require('@pioneer-platform/pioneer-caip');
+            const assetInfo = assetData[caip.toUpperCase()] || assetData[caip.toLowerCase()] || {};
+            const networkId = caipToNetworkId(caip);
+            return {
+                caip,
+                pubkey,
+                balance: balanceInfo.balance,
+                symbol: assetInfo.symbol,
+                name: assetInfo.name,
+                networkId
+            };
+        }
+        catch (error) {
+            log.error(tag, 'Error fetching balance:', error);
+            throw error;
+        }
+    }
+    /**
+     * Try to get balance from legacy cache format
+     */
+    async getLegacyCached(params) {
+        const tag = this.TAG + 'getLegacyCached | ';
+        try {
+            const { caip, pubkey } = params;
+            const { caipToNetworkId } = require('@pioneer-platform/pioneer-caip');
+            const networkId = caipToNetworkId(caip);
+            // Try legacy format: cache:balance:pubkey:asset
+            const legacyKey = `cache:balance:${pubkey}:${networkId}`;
+            const legacyData = await this.redis.get(legacyKey);
+            if (legacyData) {
+                const parsed = JSON.parse(legacyData);
+                if (parsed.balance !== undefined) {
+                    return {
+                        caip,
+                        pubkey,
+                        balance: typeof parsed.balance === 'string' ? parsed.balance : String(parsed.balance)
+                    };
+                }
+            }
+            return null;
+        }
+        catch (error) {
+            log.error(tag, 'Error getting legacy cached balance:', error);
+            return null;
+        }
+    }
+    /**
+     * Get balance for a specific asset and pubkey
+     * Convenience method that wraps base get()
+     */
+    async getBalance(caip, pubkey, waitForFresh) {
+        const result = await this.get({ caip, pubkey }, waitForFresh);
+        return result.value || this.config.defaultValue;
+    }
+    /**
+     * Get balances for multiple assets (batch operation)
+     */
+    async getBatchBalances(items, waitForFresh) {
+        const tag = this.TAG + 'getBatchBalances | ';
+        const startTime = Date.now();
+        try {
+            log.info(tag, `Batch request for ${items.length} balances`);
+            // Get all balances in parallel
+            const promises = items.map(item => this.getBalance(item.caip, item.pubkey, waitForFresh));
+            const results = await Promise.all(promises);
+            const responseTime = Date.now() - startTime;
+            log.info(tag, `Batch completed: ${results.length} balances in ${responseTime}ms (${(responseTime / results.length).toFixed(1)}ms avg)`);
+            return results;
+        }
+        catch (error) {
+            log.error(tag, 'Error in batch balance request:', error);
+            // Return defaults for all items
+            return items.map(item => ({
+                caip: item.caip,
+                pubkey: item.pubkey,
+                balance: '0'
+            }));
+        }
+    }
+}
+exports.BalanceCache = BalanceCache;

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

@@ -0,0 +1,39 @@
+import { BaseCache } from '../core/base-cache';
+import type { CacheConfig } from '../types';
+/**
+ * Price data structure
+ */
+export interface PriceData {
+    caip: string;
+    price: number;
+    source?: string;
+}
+/**
+ * PriceCache - Caches USD prices for assets
+ */
+export declare class PriceCache extends BaseCache<PriceData> {
+    private markets;
+    constructor(redis: any, markets: any, config?: Partial<CacheConfig>);
+    /**
+     * Build Redis key for price data
+     * Format: price_v2:caip
+     */
+    protected buildKey(params: Record<string, any>): string;
+    /**
+     * Fetch price from markets API
+     */
+    protected fetchFromSource(params: Record<string, any>): Promise<PriceData>;
+    /**
+     * Try to get price from legacy cache formats
+     */
+    protected getLegacyCached(params: Record<string, any>): Promise<PriceData | null>;
+    /**
+     * Get price for a specific asset
+     * Convenience method that wraps base get()
+     */
+    getPrice(caip: string, waitForFresh?: boolean): Promise<number>;
+    /**
+     * Get prices for multiple assets (batch operation)
+     */
+    getBatchPrices(caips: string[], waitForFresh?: boolean): Promise<Map<string, number>>;
+}