Merge pull request #7 from robin-drexler/rd/cleanup

Rd/cleanup

Author: robin-drexler

README.md

@@ -10,7 +10,9 @@ A storage wrapper that adds expiration functionality to `localStorage` or any ot
 npm install expiring-storage
 ```
 
-## Usage
+## Examples
+
+### Basic Usage
 
 ```javascript
 import { wrapStorage } from "expirix";
@@ -25,6 +27,31 @@ storage.setItem("key", "value");
 const value = storage.getItem("key");
 ```
 
+### Creating a reusable storage module
+
+```javascript
+// app-storage.js
+import { wrapStorage } from "expirix";
+
+const wrappedLocalStorage = wrapStorage(localStorage, {
+  expiresInSeconds: 3600,
+});
+
+export default wrappedLocalStorage;
+```
+
+```javascript
+// Using in your app
+import storage from "./app-storage.js";
+
+// Store user preferences that expire in 1 hour
+storage.setItem("theme", "dark");
+storage.setItem("language", "en");
+
+// Later...
+const theme = storage.getItem("theme"); // null if expired
+```
+
 ## API
 
 ### `wrapStorage(originalStorage, options?)`
@@ -39,6 +66,85 @@ Wraps a Storage object to add expiration functionality.
 
 **Returns:** A Storage-compatible object with expiration support
 
+### `cleanupFactory(originalStorage, options?)`
+
+Creates a cleanup function to remove expired values and optionally wrap unwrapped values so that they can be cleaned up later on as well.
+Useful to cleanup keys that might not be requested by the app anymore.
+
+**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: true)
+  - `wrapUnwrappedItems` (boolean, optional): Whether to wrap non-wrapped items with expiration metadata (default: false)
+    If turned on, this will wrap existing values in a JSON structure. Only use it if you are sure that whatever code reads these values can handle this.
+
+**Returns:** An object with a `runCleanup()` method
+
+**Example:**
+
+```javascript
+import { cleanupFactory } from "expirix";
+
+// Create cleanup that runs when browser is idle (default behavior)
+const cleanup = cleanupFactory(localStorage, {
+  expiresInSeconds: 3600, // 1 hour
+});
+
+// Run cleanup (will use requestIdleCallback if available, setTimeout as fallback)
+cleanup.runCleanup();
+
+// To run cleanup immediately instead:
+const immediateCleanup = cleanupFactory(localStorage, {
+  expiresInSeconds: 3600,
+  runWhenBrowserIsIdle: false,
+});
+```
+
+#### Wrapping Behavior Control
+
+By default, cleanup operations only remove expired items but do not modify existing unwrapped values. You can control whether cleanup should wrap existing unwrapped items with the `wrapUnwrappedItems` option.
+
+```javascript
+// Only clean up expired items, leave unwrapped items as-is (default)
+const cleanupOnly = cleanupFactory(localStorage, {
+  expiresInSeconds: 3600,
+});
+
+// Clean up expired items AND wrap unwrapped items
+const cleanupAndWrap = cleanupFactory(localStorage, {
+  expiresInSeconds: 3600,
+  wrapUnwrappedItems: true,
+});
+```
+
+This gives you fine-grained control over when existing data gets wrapped with expiration metadata.
+
+#### Browser Idle Cleanup
+
+By default, the library runs 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 (default behavior)
+const idleCleanup = cleanupFactory(localStorage, {
+  expiresInSeconds: 3600,
+});
+
+idleCleanup.runCleanup(); // Schedules cleanup for when browser is idle
+
+// To run cleanup immediately instead:
+const immediateCleanup = cleanupFactory(localStorage, {
+  expiresInSeconds: 3600,
+  runWhenBrowserIsIdle: false,
+});
+```
+
+**requestIdleCallback Polyfill:**
+
+- Uses native `requestIdleCallback` when available
+- Falls back to `setTimeout` with 1ms delay in older browsers
+
 ## Features
 
 - ✅ **Drop-in replacement** for localStorage/sessionStorage

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,102 @@
+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, wrapUnwrappedItems?: boolean }} [options={}] - Configuration options
+ * @returns {{ runCleanup: () => void }}
+ */
+export function cleanupFactory(
+  originalStorage,
+  {
+    expiresInSeconds,
+    runWhenBrowserIsIdle = true,
+    wrapUnwrappedItems = false,
+  } = {}
+) {
+  /**
+   * @returns {void}
+   */
+  function runCleanup() {
+    const actualCleanup = () => {
+      // Iterate backwards through storage to handle removals safely in a single pass
+      for (let i = originalStorage.length - 1; i >= 0; i--) {
+        const key = originalStorage.key(i);
+        if (key === null) continue;
+
+        const value = originalStorage.getItem(key);
+        if (!value) continue;
+
+        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 if (wrapUnwrappedItems) {
+            // Not a wrapped value yet, wrap it only if wrapUnwrappedItems is true
+            originalStorage.setItem(
+              key,
+              JSON.stringify(createWrappedItem(value, expiresInSeconds))
+            );
+          }
+          // If wrapUnwrappedItems is false, leave unwrapped items as-is
+        } catch (e) {
+          // Handle non-JSON values - treat as plain string and wrap only if wrapUnwrappedItems is true
+          if (wrapUnwrappedItems) {
+            originalStorage.setItem(
+              key,
+              JSON.stringify(createWrappedItem(value, expiresInSeconds))
+            );
+          }
+        }
+      }
+    };
+
+    if (runWhenBrowserIsIdle) {
+      const requestIdleCallback = getRequestIdleCallback();
+      requestIdleCallback(actualCleanup);
+    } else {
+      actualCleanup();
+    }
+  }
+
+  return {
+    runCleanup,
+  };
+}