@kishangai/cache-shuttle 1.0.0

package/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kishan Gaiwala
+
+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.

package/README.md

@@ -0,0 +1,19 @@
+# Cache Shuttle 🚀
+
+A production-grade, fault-tolerant bridging framework to seamlessly dual-write, read-through, and migrate data across conflicting storage caching tiers without server downtime.
+
+Unlike standard multi-caching tools, **Cache Shuttle** focuses specifically on structural migration mechanics, giving you safe, chunked data synchronization utilities to transfer live data from one provider to another seamlessly.
+
+## Key Features
+
+* 🔒 **RAM Explosion Prevention:** Processes large migrations in adjustable, chunked batches to keep memory overhead near zero.
+* 🛡️ **Anti-Crash Isolation:** Utilizes parallel non-blocking execution routines (`Promise.allSettled`) to isolate backend network drops.
+* 🔄 **Read-Through & Auto-Healing:** Resolves fast local cache misses by looking up upstream nodes and auto-healing the local tier.
+* 🚚 **The Shuttle (`transferAll`):** Drain and migrate entire memory trees securely with a single line of code.
+
+---
+
+## Installation
+
+```bash
+npm install cache-shuttle

package/lib/index.js

@@ -0,0 +1,154 @@
+/**
+ * CacheShuttle
+ * A production-grade framework to securely dual-write, read-through, and migrate 
+ * data across different caching layers smoothly without server downtime.
+ */
+class CacheShuttle {
+    /**
+     * @param {Object} options
+     * @param {Object} options.source - The primary/fast caching tier adapter.
+     * @param {Object} options.target - The secondary/persistent caching tier adapter.
+     * @param {number} [options.batchSize=100] - Chunks processed per cycle to prevent memory overloads.
+     */
+    constructor(options = {}) {
+        this._validateAdapters(options.source, options.target);
+
+        this.source = options.source;
+        this.target = options.target;
+        this.batchSize = Math.max(1, parseInt(options.batchSize, 10) || 100);
+    }
+
+    /**
+     * Defensive Validation Checklist
+     * Throws explicit errors instantly on startup if the user misconfigures adapters.
+     * @private
+     */
+    _validateAdapters(source, target) {
+        if (!source || !target) {
+            throw new Error("CacheShuttle Core Error: Provide valid 'source' and 'target' configuration blocks.");
+        }
+
+        const requiredSourceMethods = ['get', 'set', 'getKeys'];
+        for (const method of requiredSourceMethods) {
+            if (typeof source[method] !== 'function') {
+                throw new Error(`CacheShuttle Core Error: Source adapter is missing structural "${method}()" hook.`);
+            }
+        }
+
+        if (typeof target.set !== 'function') {
+            throw new Error('CacheShuttle Core Error: Target adapter lacks standard "set()" entry point.');
+        }
+    }
+
+    /**
+     * Strategy: Dual-Write
+     * Executes background updates on both stores in parallel. Fully isolated to bypass system-wide breaks.
+     */
+    async set(key, value, ttlInSeconds = null) {
+        if (key === undefined || key === null) return false;
+
+        const results = await Promise.allSettled([
+            this.source.set(key, value, ttlInSeconds),
+            this.target.set(key, value, ttlInSeconds)
+        ]);
+
+        const sourceOk = results[0].status === 'fulfilled';
+        const targetOk = results[1].status === 'fulfilled';
+
+        if (!sourceOk) console.warn(`[CacheShuttle] Safe Warning: Outbound local write dropped for key "${key}".`);
+        if (!targetOk) console.warn(`[CacheShuttle] Safe Warning: Outbound upstream write dropped for key "${key}".`);
+
+        return sourceOk || targetOk;
+    }
+
+    /**
+     * Strategy: Read-Through + Self-Healing
+     * Returns data immediately on a fast cache hit. Resolves cache misses by pulling from target and refreshing source.
+     */
+    async get(key, ttlInSeconds = null) {
+        if (key === undefined || key === null) return null;
+
+        try {
+            // Step A: Read local fast engine
+            const cachedValue = await this.source.get(key);
+            if (cachedValue !== undefined && cachedValue !== null) {
+                return cachedValue;
+            }
+
+            // Step B: Search primary storage network layer
+            if (typeof this.target.get === 'function') {
+                const storedValue = await this.target.get(key);
+
+                if (storedValue !== undefined && storedValue !== null) {
+                    // Asynchronously heal source node to optimize downstream loops
+                    this.source.set(key, storedValue, ttlInSeconds).catch(err => {
+                        console.error(`[CacheShuttle] Failed healing back-fill for "${key}":`, err.message);
+                    });
+                    return storedValue;
+                }
+            }
+        } catch (error) {
+            console.error(`[CacheShuttle] Read Exception encountered on "${key}":`, error.message);
+        }
+
+        return null;
+    }
+
+    /**
+     * Strategy: The Shuttle (Safely Batched High-Speed Core Migration)
+     * Converts and drains memory trees into production databases safely using segmented loops.
+     */
+    async transferAll() {
+        const auditLog = {
+            success: true,
+            totalKeysFound: 0,
+            moved: 0,
+            failed: 0,
+            errors: []
+        };
+
+        try {
+            const keys = await this.source.getKeys();
+            if (!Array.isArray(keys) || keys.length === 0) {
+                return auditLog;
+            }
+
+            auditLog.totalKeysFound = keys.length;
+
+            // Safe memory slicing loops: moves batchSize records at a time
+            for (let i = 0; i < keys.length; i += this.batchSize) {
+                const chunk = keys.slice(i, i + this.batchSize);
+
+                await Promise.all(chunk.map(async (key) => {
+                    try {
+                        const rawData = await this.source.get(key);
+
+                        if (rawData !== undefined && rawData !== null) {
+                            await this.target.set(key, rawData);
+                            auditLog.moved++;
+                        } else {
+                            auditLog.failed++;
+                            auditLog.errors.push({ key, explanation: "Empty value detected inside origin engine." });
+                        }
+                    } catch (chunkError) {
+                        auditLog.failed++;
+                        auditLog.errors.push({ key, explanation: chunkError.message });
+                    }
+                }));
+            }
+
+            return auditLog;
+        } catch (fatalCrash) {
+            return {
+                success: false,
+                error: `Critical lifecycle break: ${fatalCrash.message}`,
+                totalKeysFound: auditLog.totalKeysFound,
+                moved: auditLog.moved,
+                failed: auditLog.failed,
+                errors: auditLog.errors
+            };
+        }
+    }
+}
+
+module.exports = CacheShuttle;

package/package.json

@@ -0,0 +1,29 @@
+{
+    "name": "@kishangai/cache-shuttle",
+    "version": "1.0.0",
+    "description": "A production-grade bridge framework to securely dual-write, read-through, and migrate records among conflicting storage cache providers seamlessly.",
+    "main": "lib/index.js",
+    "engines": {
+        "node": ">=14.0.0"
+    },
+    "files": [
+        "lib",
+        "README.md",
+        "LICENSE"
+    ],
+    "keywords": [
+        "cache",
+        "redis",
+        "node-cache",
+        "migration",
+        "data-transfer",
+        "synchronization",
+        "read-through"
+    ],
+    "author": "Kishan Gaiwala <gaiwalakishan@gmail.com>",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/kishangaiwala/cache-shuttle.git"
+    }
+}