xypriss 1.0.0 → 1.1.0

package/dist/cjs/mods/toolkit/src/components/cache/cacheSys.utils.js

@@ -0,0 +1,136 @@
+'use strict';
+
+var util = require('util');
+var fs = require('fs');
+var path = require('path');
+var zlib = require('zlib');
+require('../../types.js');
+require('../../core/hash/hash-core.js');
+require('../../core/hash/hash-types.js');
+var crypto = require('crypto');
+require('../../core/hash/hash-security.js');
+require('../../core/hash/hash-advanced.js');
+require('../../algorithms/hash-algorithms.js');
+require('../../core/keys/keys-types.js');
+require('../../core/keys/keys-logger.js');
+require('../../core/keys/keys-utils.js');
+require('../../core/keys/algorithms/mods/PBKDF2Algo.js');
+var randomCore = require('../../core/random/random-core.js');
+require('../../core/random/random-types.js');
+require('../../core/random/random-sources.js');
+require('nehonix-uri-processor');
+require('../../utils/memory/index.js');
+require('argon2');
+require('child_process');
+require('../../types/secure-memory.js');
+require('https');
+require('../runtime-verification.js');
+require('../tamper-evident-logging.js');
+require('../secure-string/advanced/entropy-analyzer.js');
+require('../secure-string/advanced/quantum-safe.js');
+require('../secure-string/advanced/performance-monitor.js');
+require('nehoid');
+require('../../core/password/index.js');
+
+function _interopNamespaceDefault(e) {
+    var n = Object.create(null);
+    if (e) {
+        Object.keys(e).forEach(function (k) {
+            if (k !== 'default') {
+                var d = Object.getOwnPropertyDescriptor(e, k);
+                Object.defineProperty(n, k, d.get ? d : {
+                    enumerable: true,
+                    get: function () { return e[k]; }
+                });
+            }
+        });
+    }
+    n.default = e;
+    return Object.freeze(n);
+}
+
+var crypto__namespace = /*#__PURE__*/_interopNamespaceDefault(crypto);
+
+/**
+ * Ensure directory exists for file cache operations
+ */
+const ensureDirectoryExists = async (filePath) => {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+};
+/**
+ * Encrypt data for file storage
+ */
+const encryptFileData = (data, key) => {
+    const encryptionKey = key || randomCore.SecureRandom.getRandomBytes(32);
+    const iv = randomCore.SecureRandom.getRandomBytes(16);
+    const cipher = crypto__namespace.createCipheriv("aes-256-gcm", encryptionKey, iv);
+    let encrypted = cipher.update(data, "utf8", "base64");
+    encrypted += cipher.final("base64");
+    const authTag = cipher.getAuthTag();
+    return {
+        encrypted,
+        iv: iv.toString("base64"),
+        authTag: authTag.toString("base64"),
+        key: encryptionKey.toString("base64"),
+    };
+};
+/**
+ * Decrypt data from file storage
+ */
+const decryptFileData = (encrypted, iv, authTag, key) => {
+    const keyBuffer = Buffer.from(key, "base64");
+    const ivBuffer = Buffer.from(iv, "base64");
+    const authTagBuffer = Buffer.from(authTag, "base64");
+    const decipher = crypto__namespace.createDecipheriv("aes-256-gcm", keyBuffer, ivBuffer);
+    decipher.setAuthTag(authTagBuffer);
+    let decrypted = decipher.update(encrypted, "base64", "utf8");
+    decrypted += decipher.final("utf8");
+    return decrypted;
+};
+/**
+ * Compress data if beneficial
+ */
+const compressFileData = async (data) => {
+    if (data.length < 1024) {
+        // Don't compress small data
+        return { data, compressed: false };
+    }
+    try {
+        const deflate = util.promisify(zlib.deflate);
+        const compressed = await deflate(Buffer.from(data, "utf8"));
+        const compressedString = compressed.toString("base64");
+        if (compressedString.length < data.length * 0.9) {
+            return { data: compressedString, compressed: true };
+        }
+    }
+    catch (error) {
+        console.warn("File compression failed:", error);
+    }
+    return { data, compressed: false };
+};
+/**
+ * Decompress data
+ */
+const decompressFileData = async (data, compressed) => {
+    if (!compressed)
+        return data;
+    try {
+        const inflate = util.promisify(zlib.inflate);
+        const decompressed = await inflate(Buffer.from(data, "base64"));
+        return decompressed.toString("utf8");
+    }
+    catch (error) {
+        console.error("File decompression failed:", error);
+        throw new Error("Data decompression failed");
+    }
+};
+
+exports.compressFileData = compressFileData;
+exports.decompressFileData = decompressFileData;
+exports.decryptFileData = decryptFileData;
+exports.encryptFileData = encryptFileData;
+exports.ensureDirectoryExists = ensureDirectoryExists;
+//# sourceMappingURL=cacheSys.utils.js.map

package/dist/cjs/mods/toolkit/src/components/cache/cacheSys.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cacheSys.utils.js","sources":["../../../../../../../mods/toolkit/src/components/cache/cacheSys.utils.ts"],"sourcesContent":[null],"names":["existsSync","mkdirSync","SecureRandom","crypto","promisify"],"mappings":"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"}

package/dist/cjs/mods/toolkit/src/components/cache/config/cache.config.js

@@ -0,0 +1,39 @@
+'use strict';
+
+const CONFIG = {
+    CACHE_EXPIRY_MS: 10 * 60 * 1000, // 10 minutes default TTL
+    KEY_ROTATION_MS: 10 * 24 * 60 * 60 * 1000, // 10 days
+    ALGORITHM: "aes-256-gcm",
+    ENCODING: "hex",
+    KEY_ITERATIONS: 100000,
+    KEY_LENGTH: 32,
+    MAX_CACHE_SIZE_MB: 100, // Maximum memory usage
+    MAX_ENTRIES: 10000, // Maximum number of cache entries
+    COMPRESSION_THRESHOLD_BYTES: 1024,
+    CLEANUP_INTERVAL_MS: 5 * 60 * 1000, // Cleanup every 5 minutes
+    SECURITY_CHECK_INTERVAL_MS: 60 * 1000, // Security checks every minute
+    MAX_KEY_LENGTH: 512, // Prevent DoS via large keys
+    MAX_VALUE_SIZE_MB: 10, // Maximum size per cache entry
+};
+// ========================================
+// FILE CACHE CONFIGURATION
+// ========================================
+/**
+ * Default configuration for file-based cache
+ */
+const DEFAULT_FILE_CACHE_CONFIG = {
+    directory: ".data/cache",
+    extension: ".cache",
+    atomic: true,
+    compress: true,
+    encrypt: true,
+    namingStrategy: "hierarchical",
+    maxFileSize: 10 * 1024 * 1024, // 10MB
+    trackMetadata: true,
+    maxCacheSize: 50 * 1024 * 1024, // 50MB
+    ttl: 5 * 60 * 1000, // 5 minutes
+};
+
+exports.CONFIG = CONFIG;
+exports.DEFAULT_FILE_CACHE_CONFIG = DEFAULT_FILE_CACHE_CONFIG;
+//# sourceMappingURL=cache.config.js.map

package/dist/cjs/mods/toolkit/src/components/cache/config/cache.config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.config.js","sources":["../../../../../../../../mods/toolkit/src/components/cache/config/cache.config.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAGA,MAAM,MAAM,GAAG;AACX,IAAA,eAAe,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI;IAC/B,eAAe,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI;AACzC,IAAA,SAAS,EAAE,aAAsB;AACjC,IAAA,QAAQ,EAAE,KAAoC;AAC9C,IAAA,cAAc,EAAE,MAAM;AACtB,IAAA,UAAU,EAAE,EAAE;IACd,iBAAiB,EAAE,GAAG;IACtB,WAAW,EAAE,KAAK;AAClB,IAAA,2BAA2B,EAAE,IAAI;AACjC,IAAA,mBAAmB,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI;AAClC,IAAA,0BAA0B,EAAE,EAAE,GAAG,IAAI;IACrC,cAAc,EAAE,GAAG;IACnB,iBAAiB,EAAE,EAAE;EACvB;AAIF;AACA;AACA;AAEA;;AAEG;AACU,MAAA,yBAAyB,GAA+B;AACjE,IAAA,SAAS,EAAE,aAAa;AACxB,IAAA,SAAS,EAAE,QAAQ;AACnB,IAAA,MAAM,EAAE,IAAI;AACZ,IAAA,QAAQ,EAAE,IAAI;AACd,IAAA,OAAO,EAAE,IAAI;AACb,IAAA,cAAc,EAAE,cAAc;AAC9B,IAAA,WAAW,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI;AAC7B,IAAA,aAAa,EAAE,IAAI;AACnB,IAAA,YAAY,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI;AAC9B,IAAA,GAAG,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI;;;;;;"}

package/dist/cjs/mods/toolkit/src/components/cache/index.js

@@ -0,0 +1,459 @@
+'use strict';
+
+var path = require('path');
+require('../../types.js');
+var hashCore = require('../../core/hash/hash-core.js');
+require('../../core/hash/hash-types.js');
+require('crypto');
+require('../../core/hash/hash-security.js');
+require('../../core/hash/hash-advanced.js');
+require('../../algorithms/hash-algorithms.js');
+require('../../core/keys/keys-types.js');
+require('../../core/keys/keys-logger.js');
+require('../../core/keys/keys-utils.js');
+require('../../core/keys/algorithms/mods/PBKDF2Algo.js');
+require('../../core/random/random-types.js');
+require('../../core/random/random-sources.js');
+require('nehonix-uri-processor');
+require('../../utils/memory/index.js');
+require('argon2');
+require('child_process');
+require('../../types/secure-memory.js');
+require('https');
+require('../runtime-verification.js');
+require('../tamper-evident-logging.js');
+require('../secure-string/advanced/entropy-analyzer.js');
+require('../secure-string/advanced/quantum-safe.js');
+require('../secure-string/advanced/performance-monitor.js');
+require('nehoid');
+require('../../core/password/index.js');
+var useCache = require('./useCache.js');
+require('util');
+require('zlib');
+require('events');
+var cache_config = require('./config/cache.config.js');
+var cacheSys = require('./cacheSys.js');
+
+/***************************************************************************
+ * XyPrissSecurity - Secure Array Types
+ *
+ * This file contains type definitions for the SecureArray modular architecture
+ *
+ * @author Nehonix
+ * @license MIT
+ *
+ * Copyright (c) 2025 Nehonix. All rights reserved.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ ***************************************************************************** */
+// SecureCacheAdapter type will be imported dynamically when needed
+/**
+ * @fileoverview XyPrissSecurity Unified Cache System - Enterprise-Grade Caching Solution
+ *
+ * A comprehensive,  caching solution combining multiple strategies
+ * with military-grade security and ultra-fast performance optimization.
+ *
+ * ## Cache Strategies
+ * - **Memory Cache**: Ultra-fast in-process storage with LRU eviction
+ * - **File Cache**: Persistent cross-process storage with real disk monitoring
+ * - **Hybrid Cache**: Automatic optimization between memory and file storage
+ * - **Redis Cache**: Distributed scalable storage (via integrations)
+ *
+ * ## Security Features
+ * - AES-256-GCM encryption for all cached data
+ * - PBKDF2 key derivation with automatic key rotation
+ * - Tamper-evident storage with integrity verification
+ * - Secure key management and access pattern monitoring
+ * - Memory-safe operations with automatic cleanup
+ *
+ * ## Performance Features
+ * - Zlib compression for large values (configurable threshold)
+ * - LRU eviction with intelligent memory pressure management
+ * - Real-time disk space monitoring and automatic cleanup
+ * - Atomic file operations for data consistency
+ * - Sub-millisecond cache hits with object pooling
+ * - Configurable TTL with background expiration cleanup
+ *
+ * ## Production Features
+ * - Comprehensive error handling with graceful degradation
+ * - Real-time performance metrics and health monitoring
+ * - Configurable naming strategies (flat, hierarchical, dated, direct)
+ * - Cross-platform compatibility (Windows, macOS, Linux)
+ * - Zero-dependency core with optional integrations
+ * - TypeScript support with complete type definitions
+ *
+ * @example
+ * ```typescript
+ * // Quick start with default memory cache
+ * import { Cache } from "xypriss-security";
+ *
+ * await Cache.set('user:123', { name: 'John', role: 'admin' }, { ttl: 3600000 });
+ * const user = await Cache.get('user:123');
+ *
+ * // File-based persistent cache
+ * import { FileCache } from "xypriss-security";
+ *
+ * const fileCache = new FileCache({
+ *   directory: './cache',
+ *   encrypt: true,
+ *   compress: true,
+ *   maxCacheSize: 1024 * 1024 * 100 // 100MB
+ * });
+ *
+ * await fileCache.set('session:abc', sessionData, { ttl: 86400000 });
+ *
+ * // Hybrid cache for optimal performance
+ * import { createOptimalCache } from "xypriss-security";
+ *
+ * const hybridCache = createOptimalCache({
+ *   type: 'hybrid',
+ *   config: { encrypt: true, compress: true }
+ * });
+ * ```
+ *
+ * @version 4.2.3
+ * @author NEHONIX
+ * @since 2024-12-19
+ * @license MIT
+ */
+// ========================================
+// MAIN CACHE EXPORTS
+// ========================================
+/**
+ * Default secure in-memory cache instance
+ *
+ * Pre-configured singleton instance with optimal security settings for immediate use.
+ * Features AES-256-GCM encryption, LRU eviction, and automatic memory management.
+ *
+ * @example
+ * ```typescript
+ * import { Cache } from "xypriss-security";
+ *
+ * // Store user session with 1-hour TTL
+ * await Cache.set('session:user123', {
+ *   userId: 123,
+ *   permissions: ['read', 'write'],
+ *   loginTime: Date.now()
+ * }, { ttl: 3600000 });
+ *
+ * // Retrieve cached data
+ * const session = await Cache.get('session:user123');
+ *
+ * // Check cache statistics
+ * const stats = Cache.getStats();
+ * console.log(`Hit rate: ${stats.hitRate}%`);
+ * ```
+ *
+ * @since 4.2.2
+ */
+const Cache = new useCache.SecureInMemoryCache();
+// ========================================
+// FILE CACHE UTILITIES
+// ========================================
+/**
+ * Generate a secure file path for cache storage
+ *
+ * Creates secure, collision-resistant file paths using configurable naming strategies.
+ * All keys are hashed using SHA-256 to prevent directory traversal attacks and
+ * ensure consistent path generation across platforms.
+ *
+ * @param key - The cache key to generate a path for
+ * @param options - Optional configuration for path generation
+ * @returns Secure file path for the given key
+ *
+ * @example
+ * ```typescript
+ * import { generateFilePath } from "xypriss-security";
+ *
+ * // Hierarchical structure (recommended for large caches)
+ * const path1 = generateFilePath('user:123', {
+ *   namingStrategy: 'hierarchical',
+ *   directory: './cache'
+ * });
+ * // Result: ./cache/a1/b2/a1b2c3d4...cache
+ *
+ * // Date-based organization (good for time-series data)
+ * const path2 = generateFilePath('daily-report', {
+ *   namingStrategy: 'dated',
+ *   directory: './reports'
+ * });
+ * // Result: ./reports/2024/12/19/hash...cache
+ *
+ * // Direct naming (human-readable, limited special chars)
+ * const path3 = generateFilePath('config-settings', {
+ *   namingStrategy: 'direct',
+ *   directory: './config'
+ * });
+ * // Result: ./config/config-settings.cache
+ * ```
+ *
+ * @since 4.2.2
+ */
+const generateFilePath = (key, options = {}) => {
+    const config = { ...cache_config.DEFAULT_FILE_CACHE_CONFIG, ...options };
+    const sanitized = hashCore.Hash.create(key, { outputFormat: "hex" });
+    let filePath;
+    switch (config.namingStrategy) {
+        case "hierarchical":
+            const dir = sanitized.substring(0, 2);
+            const subdir = sanitized.substring(2, 4);
+            filePath = path.resolve(config.directory, dir, subdir, `${sanitized}${config.extension}`);
+            break;
+        case "dated":
+            const now = new Date();
+            const year = now.getFullYear();
+            const month = String(now.getMonth() + 1).padStart(2, "0");
+            const day = String(now.getDate()).padStart(2, "0");
+            filePath = path.resolve(config.directory, String(year), month, day, `${sanitized}${config.extension}`);
+            break;
+        case "direct":
+            const safeKey = key.replace(/[^a-zA-Z0-9_-]/g, "_");
+            filePath = path.resolve(config.directory, `${safeKey}${config.extension}`);
+            break;
+        case "flat":
+        default:
+            filePath = path.resolve(config.directory, `${sanitized}${config.extension}`);
+            break;
+    }
+    return filePath;
+};
+// ========================================
+// FILE CACHE EXPORTS
+// ========================================
+/**
+ * Default FileCache instance with lazy initialization
+ *
+ * Pre-configured file cache instance optimized for general use cases.
+ * Features encryption, compression, and real disk space monitoring.
+ * Uses lazy initialization to avoid circular dependency issues.
+ *
+ * @example
+ * ```typescript
+ * import { defaultFileCache } from "xypriss-security";
+ *
+ * // Store large dataset with compression
+ * await defaultFileCache.set('analytics:daily', bigDataSet, {
+ *   ttl: 86400000, // 24 hours
+ *   compress: true
+ * });
+ *
+ * // Check cache health
+ * const info = await defaultFileCache.getCacheInfo();
+ * if (!info.health.healthy) {
+ *   console.warn('Cache issues:', info.health.issues);
+ * }
+ * ```
+ *
+ * @since 4.2.0
+ */
+let _defaultFileCache = null;
+new Proxy({}, {
+    get(target, prop) {
+        if (!_defaultFileCache) {
+            _defaultFileCache = new cacheSys.FileCache();
+        }
+        const value = _defaultFileCache[prop];
+        return typeof value === "function"
+            ? value.bind(_defaultFileCache)
+            : value;
+    },
+});
+// ========================================
+// MEMORY CACHE API
+// ========================================
+/**
+ * Read data from memory cache with fallback
+ *
+ * Retrieves data from the default memory cache instance.
+ * Returns empty object if key is not found (legacy behavior).
+ *
+ * @param args - Arguments passed to Cache.get()
+ * @returns Promise resolving to cached data or empty object
+ *
+ * @example
+ * ```typescript
+ * import { readCache } from "xypriss-security";
+ *
+ * const sessionData = await readCache('session:user123');
+ * console.log('User ID:', sessionData.userId || 'Not found');
+ * ```
+ *
+ * @since 4.2.2
+ */
+const readCache = async (...args) => {
+    const result = await Cache.get(...args);
+    return result || {};
+};
+/**
+ * Write data to memory cache
+ *
+ * Stores data in the default memory cache instance with encryption
+ * and automatic compression for large values.
+ *
+ * @param args - Arguments passed to Cache.set()
+ * @returns Promise resolving to true if successful
+ *
+ * @example
+ * ```typescript
+ * import { writeCache } from "xypriss-security";
+ *
+ * await writeCache('user:profile', userData, { ttl: 1800000 }); // 30 min
+ * ```
+ *
+ * @since 4.2.2
+ */
+const writeCache = async (...args) => {
+    return Cache.set(...args);
+};
+/**
+ * Get memory cache performance statistics
+ *
+ * Returns comprehensive statistics including hit rates, memory usage,
+ * and performance metrics for the default cache instance.
+ *
+ * @returns Current cache statistics
+ *
+ * @example
+ * ```typescript
+ * import { getCacheStats } from "xypriss-security";
+ *
+ * const stats = getCacheStats();
+ * console.log(`Hit rate: ${stats.hitRate}%`);
+ * console.log(`Memory usage: ${stats.memoryUsage} bytes`);
+ * ```
+ *
+ * @since 4.2.2
+ */
+const getCacheStats = () => {
+    return Cache.getStats;
+};
+// ========================================
+// UTILITY FUNCTIONS
+// ========================================
+/**
+ * Create optimal cache instance based on performance requirements
+ *
+ * Factory function that creates the most suitable cache instance for your use case.
+ * Automatically configures security settings and performance optimizations.
+ *
+ * @param options - Cache configuration options
+ * @param options.type - Cache strategy: 'memory' (fastest), 'file' (persistent), 'hybrid' (balanced)
+ * @param options.config - Optional file cache configuration (ignored for memory-only)
+ * @returns Configured cache instance optimized for the specified requirements
+ *
+ * @example
+ * ```typescript
+ * import { createOptimalCache } from "xypriss-security";
+ *
+ * // Ultra-fast memory cache for session data
+ * const sessionCache = createOptimalCache({ type: 'memory' });
+ *
+ * // Persistent file cache for application data
+ * const appCache = createOptimalCache({
+ *   type: 'file',
+ *   config: {
+ *     directory: './app-cache',
+ *     encrypt: true,
+ *     maxCacheSize: 100 * 1024 * 1024 // 100MB
+ *   }
+ * });
+ *
+ * // Hybrid cache for optimal performance and persistence
+ * const hybridCache = createOptimalCache({
+ *   type: 'hybrid',
+ *   config: { encrypt: true, compress: true }
+ * });
+ *
+ * // Use hybrid cache (memory-first with file backup)
+ * await hybridCache.set('user:123', userData);
+ * const user = await hybridCache.get('user:123'); // Served from memory
+ * ```
+ *
+ * @since 4.2.2
+ */
+const createOptimalCache = (options) => {
+    switch (options.type) {
+        case "memory":
+            return new useCache.SecureInMemoryCache();
+        case "file":
+            return new cacheSys.FileCache(options.config);
+        case "hybrid":
+            // Return both memory cache and file cache in a wrapper
+            return {
+                memory: new useCache.SecureInMemoryCache(),
+                file: new cacheSys.FileCache(options.config),
+                async get(key) {
+                    // Try memory first, then file
+                    let result = await this.memory.get(key);
+                    if (!result) {
+                        result = await this.file.get(key);
+                        if (result) {
+                            // Cache in memory for faster access
+                            await this.memory.set(key, result);
+                        }
+                    }
+                    return result;
+                },
+                async set(key, value, options) {
+                    // Set in both caches
+                    const memoryResult = await this.memory.set(key, value, options);
+                    const fileResult = await this.file.set(key, value, options);
+                    return memoryResult && fileResult;
+                },
+            };
+        default:
+            return new useCache.SecureInMemoryCache();
+    }
+};
+// ========================================
+// GRACEFUL SHUTDOWN HANDLING
+// ========================================
+/**
+ * Graceful shutdown handler for cache system
+ *
+ * Automatically registered to handle SIGTERM and SIGINT signals.
+ * Ensures all cache operations complete before process termination.
+ *
+ * @internal
+ * @since 4.2.2
+ */
+const handleGracefulShutdown = () => {
+    console.log("Shutting down XyPrissSecurity CS gracefully...");
+    try {
+        Cache.shutdown();
+    }
+    catch (error) {
+        console.error("Error during cache shutdown:", error);
+    }
+};
+// Register shutdown handlers
+process.on("SIGTERM", handleGracefulShutdown);
+process.on("SIGINT", handleGracefulShutdown);
+
+exports.SecureInMemoryCache = useCache.SecureInMemoryCache;
+exports.DEFAULT_CACHE_CONFIG = cache_config.CONFIG;
+exports.DEFAULT_FILE_CACHE_CONFIG = cache_config.DEFAULT_FILE_CACHE_CONFIG;
+exports.FileCache = cacheSys.FileCache;
+exports.Cache = Cache;
+exports.createOptimalCache = createOptimalCache;
+exports.generateFilePath = generateFilePath;
+exports.getCacheStats = getCacheStats;
+exports.readCache = readCache;
+exports.writeCache = writeCache;
+//# sourceMappingURL=index.js.map

package/dist/cjs/mods/toolkit/src/components/cache/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../../../../../mods/toolkit/src/components/cache/index.ts"],"sourcesContent":[null],"names":["SecureInMemoryCache","DEFAULT_FILE_CACHE_CONFIG","Hash","FileCache"],"mappings":"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"}