add cleanup

Author: robin-drexler

README.md

@@ -39,6 +39,54 @@ Wraps a Storage object to add expiration functionality.
 
 **Returns:** A Storage-compatible object with expiration support
 
+### `cleanupFactory(originalStorage, options?)`
+
+Creates a cleanup function to wrap existing values and remove expired ones.
+
+**Parameters:**
+
+- `originalStorage` (Storage): The storage object (localStorage or sessionStorage)
+- `options` (object, optional):
+  - `expiresInSeconds` (number, optional): Time in seconds after which stored items expire
+  - `runWhenBrowserIsIdle` (boolean, optional): Whether to run cleanup when browser is idle (default: false)
+
+**Returns:** An object with a `runCleanup()` method
+
+**Example:**
+
+```javascript
+import { cleanupFactory } from "expirix";
+
+// Create cleanup that runs when browser is idle
+const cleanup = cleanupFactory(localStorage, {
+  expiresInSeconds: 3600, // 1 hour
+  runWhenBrowserIsIdle: true,
+});
+
+// Run cleanup (will use requestIdleCallback if available, setTimeout as fallback)
+cleanup.runCleanup();
+```
+
+## Browser Idle Cleanup
+
+The library includes support for running cleanup operations when the browser is idle, using the `requestIdleCallback` API when available, with a simple polyfill fallback for older browsers.
+
+```javascript
+// Cleanup will run when browser is idle
+const idleCleanup = cleanupFactory(localStorage, {
+  expiresInSeconds: 3600,
+  runWhenBrowserIsIdle: true,
+});
+
+idleCleanup.runCleanup(); // Schedules cleanup for when browser is idle
+```
+
+**requestIdleCallback Polyfill:**
+
+- Uses native `requestIdleCallback` when available
+- Falls back to `setTimeout` with 1ms delay in older browsers
+- Provides deadline object with `didTimeout` and `timeRemaining()` methods
+
 ## Features
 
 - ✅ **Drop-in replacement** for localStorage/sessionStorage

examples/idle-cleanup.js

@@ -0,0 +1,104 @@
+/**
+ * Example: Using runWhenBrowserIsIdle for cleanup operations
+ *
+ * This example demonstrates how to use the cleanupFactory with the
+ * runWhenBrowserIsIdle option to perform cleanup operations when
+ * the browser is idle, improving performance by not blocking the
+ * main thread during busy periods.
+ */
+
+import { cleanupFactory } from "../src/index.mjs";
+
+// Example 1: Basic idle cleanup
+console.log("🔄 Example 1: Basic idle cleanup");
+
+// Create cleanup that runs when browser is idle
+const idleCleanup = cleanupFactory(localStorage, {
+  expiresInSeconds: 3600, // 1 hour expiration
+  runWhenBrowserIsIdle: true,
+});
+
+// Add some test data
+localStorage.setItem("user-preference", "dark-mode");
+localStorage.setItem(
+  "session-data",
+  JSON.stringify({ userId: 123, token: "abc" })
+);
+localStorage.setItem("temp-cache", "some-cached-data");
+
+console.log("Added test data to localStorage");
+console.log("Running idle cleanup...");
+
+// This will use requestIdleCallback if available, setTimeout as fallback
+idleCleanup.runCleanup();
+
+console.log("Cleanup scheduled for when browser is idle");
+console.log("Check developer tools to see the wrapped values in localStorage");
+
+// Example 2: Comparison with immediate cleanup
+console.log("\n🚀 Example 2: Immediate vs Idle cleanup comparison");
+
+const immediateCleanup = cleanupFactory(localStorage, {
+  expiresInSeconds: 7200, // 2 hours
+  runWhenBrowserIsIdle: false, // Run immediately
+});
+
+// Simulate adding data during heavy computation
+console.log("Simulating heavy computation...");
+const start = performance.now();
+
+// Add data
+localStorage.setItem("immediate-test", "test-data");
+
+// Run immediate cleanup
+immediateCleanup.runCleanup();
+
+const immediateTime = performance.now() - start;
+console.log(`Immediate cleanup took: ${immediateTime}ms`);
+
+// Now with idle cleanup
+localStorage.setItem("idle-test", "test-data");
+
+const idleStart = performance.now();
+const idleCleanup2 = cleanupFactory(localStorage, {
+  expiresInSeconds: 7200,
+  runWhenBrowserIsIdle: true,
+});
+
+idleCleanup2.runCleanup();
+const idleScheduleTime = performance.now() - idleStart;
+
+console.log(`Idle cleanup scheduling took: ${idleScheduleTime}ms`);
+console.log("Actual cleanup will run when browser is idle");
+
+// Example 3: Periodic idle cleanup
+console.log("\n⏰ Example 3: Periodic idle cleanup");
+
+function setupPeriodicIdleCleanup() {
+  const periodicCleanup = cleanupFactory(localStorage, {
+    expiresInSeconds: 1800, // 30 minutes
+    runWhenBrowserIsIdle: true,
+  });
+
+  // Schedule cleanup every 5 minutes, but only when browser is idle
+  setInterval(() => {
+    console.log("Running periodic idle cleanup...");
+    periodicCleanup.runCleanup();
+  }, 5 * 60 * 1000); // 5 minutes
+}
+
+// setupPeriodicIdleCleanup();
+console.log("Periodic cleanup example ready (uncomment to activate)");
+
+// Example 4: Feature detection
+console.log("\n🔍 Example 4: Feature detection");
+
+if (typeof window !== "undefined" && window.requestIdleCallback) {
+  console.log("✅ Native requestIdleCallback is available");
+} else {
+  console.log("📦 Using polyfill fallback for requestIdleCallback");
+}
+
+console.log(
+  "\n✨ All examples complete! Check localStorage in developer tools."
+);

playground/main.js

@@ -1,17 +1,42 @@
-import { wrapStorage } from "../src/index.mjs";
+import { wrapStorage, cleanupFactory } from "../src/index.mjs";
 
 // Create wrapped storage with 60 seconds expiry and make it globally available
 window.storage = wrapStorage(localStorage, { expiresInSeconds: 60 });
 
 // Also expose the wrapStorage function globally for custom configurations
 window.wrapStorage = wrapStorage;
 
-// Log to console that everything is ready
+// Demonstrate runWhenBrowserIsIdle feature
 console.log("🚀 Expirix loaded!");
 console.log("Available globals:");
 console.log("  storage - Pre-configured localStorage with 60s expiry");
 console.log("  wrapStorage - Function to create custom storage instances");
 console.log("");
+
+// Demonstrate idle cleanup
+console.log("🛠️ Demonstrating idle cleanup feature:");
+console.log("Creating cleanup with runWhenBrowserIsIdle=true...");
+
+const idleCleanup = cleanupFactory(localStorage, {
+  expiresInSeconds: 60,
+  runWhenBrowserIsIdle: true,
+});
+
+// Add some test data
+localStorage.setItem("demo-key1", "demo-value1");
+localStorage.setItem("demo-key2", "demo-value2");
+
+console.log("Added test data to localStorage");
+console.log("Running cleanup (will use requestIdleCallback if available)...");
+
+idleCleanup.runCleanup();
+
+console.log("Cleanup scheduled! Check localStorage to see wrapped values.");
+console.log("");
 console.log("Try it out:");
 console.log('  storage.setItem("test", "hello world")');
 console.log('  storage.getItem("test")');
+console.log("  idleCleanup.runCleanup() // Run cleanup when browser is idle");
+
+// Make cleanup available globally for experimentation
+window.idleCleanup = idleCleanup;

src/cleanup.mjs

@@ -0,0 +1,101 @@
+import { isWrappedValue, createWrappedItem, isExpired } from "./utils.mjs";
+
+/**
+ * Simple polyfill for requestIdleCallback
+ * @param {Function} callback - The callback to run when idle
+ * @param {{ timeout?: number }} [options] - Options object
+ * @returns {number} - The callback ID
+ */
+function requestIdleCallbackPolyfill(callback, options = {}) {
+  const timeout = options.timeout || 0;
+  const start = Date.now();
+
+  // @ts-ignore - setTimeout returns different types in different environments
+  return setTimeout(() => {
+    const deadline = {
+      didTimeout: timeout > 0 && Date.now() - start >= timeout,
+      timeRemaining() {
+        return Math.max(0, 50 - (Date.now() - start));
+      },
+    };
+    callback(deadline);
+  }, 1);
+}
+
+/**
+ * Get requestIdleCallback with polyfill fallback
+ * @returns {Function} - The requestIdleCallback function
+ */
+function getRequestIdleCallback() {
+  if (typeof window !== "undefined" && window.requestIdleCallback) {
+    return window.requestIdleCallback.bind(window);
+  }
+  return requestIdleCallbackPolyfill;
+}
+
+/**
+ * @param {Storage} originalStorage - The storage object (localStorage or sessionStorage)
+ * @param {{ expiresInSeconds?: number, runWhenBrowserIsIdle?: boolean }} [options={}] - Configuration options
+ * @returns {{ runCleanup: () => void }}
+ */
+export function cleanupFactory(
+  originalStorage,
+  { expiresInSeconds, runWhenBrowserIsIdle = false } = {}
+) {
+  /**
+   * @returns {void}
+   */
+  function runCleanup() {
+    const actualCleanup = () => {
+      // Collect all keys first to avoid issues with storage mutation during iteration
+      const keys = [];
+      for (let i = 0; i < originalStorage.length; i++) {
+        const key = originalStorage.key(i);
+        if (key !== null) {
+          keys.push(key);
+        }
+      }
+
+      // Process each key
+      keys.forEach((key) => {
+        const value = originalStorage.getItem(key);
+        if (!value) return;
+
+        try {
+          const parsed = JSON.parse(value);
+
+          if (isWrappedValue(parsed)) {
+            // Check if it should be deleted (expired)
+            if (isExpired(parsed)) {
+              originalStorage.removeItem(key);
+            }
+            // If not expired, leave it as is
+          } else {
+            // Not a wrapped value yet, wrap it
+            originalStorage.setItem(
+              key,
+              JSON.stringify(createWrappedItem(value, expiresInSeconds))
+            );
+          }
+        } catch (e) {
+          // Handle non-JSON values - treat as plain string and wrap
+          originalStorage.setItem(
+            key,
+            JSON.stringify(createWrappedItem(value, expiresInSeconds))
+          );
+        }
+      });
+    };
+
+    if (runWhenBrowserIsIdle) {
+      const requestIdleCallback = getRequestIdleCallback();
+      requestIdleCallback(actualCleanup);
+    } else {
+      actualCleanup();
+    }
+  }
+
+  return {
+    runCleanup,
+  };
+}