add wrap option

Author: robin-drexler

README.md

@@ -48,7 +48,8 @@ Creates a cleanup function to wrap existing values and remove expired ones.
 - `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)
+  - `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)
 
 **Returns:** An object with a `runCleanup()` method
 
@@ -57,28 +58,57 @@ Creates a cleanup function to wrap existing values and remove expired ones.
 ```javascript
 import { cleanupFactory } from "expirix";
 
-// Create cleanup that runs when browser is idle
+// Create cleanup that runs when browser is idle (default behavior)
 const cleanup = cleanupFactory(localStorage, {
   expiresInSeconds: 3600, // 1 hour
-  runWhenBrowserIsIdle: true,
 });
 
 // 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
 
-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.
+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
+// Cleanup will run when browser is idle (default behavior)
 const idleCleanup = cleanupFactory(localStorage, {
   expiresInSeconds: 3600,
-  runWhenBrowserIsIdle: true,
 });
 
 idleCleanup.runCleanup(); // Schedules cleanup for when browser is idle
+
+// To run cleanup immediately instead:
+const immediateCleanup = cleanupFactory(localStorage, {
+  expiresInSeconds: 3600,
+  runWhenBrowserIsIdle: false,
+});
 ```
 
 **requestIdleCallback Polyfill:**

src/cleanup.mjs

@@ -35,31 +35,29 @@ function getRequestIdleCallback() {
 
 /**
  * @param {Storage} originalStorage - The storage object (localStorage or sessionStorage)
- * @param {{ expiresInSeconds?: number, runWhenBrowserIsIdle?: boolean }} [options={}] - Configuration options
+ * @param {{ expiresInSeconds?: number, runWhenBrowserIsIdle?: boolean, wrapUnwrappedItems?: boolean }} [options={}] - Configuration options
  * @returns {{ runCleanup: () => void }}
  */
 export function cleanupFactory(
   originalStorage,
-  { expiresInSeconds, runWhenBrowserIsIdle = false } = {}
+  {
+    expiresInSeconds,
+    runWhenBrowserIsIdle = true,
+    wrapUnwrappedItems = 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++) {
+      // 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) {
-          keys.push(key);
-        }
-      }
+        if (key === null) continue;
 
-      // Process each key
-      keys.forEach((key) => {
         const value = originalStorage.getItem(key);
-        if (!value) return;
+        if (!value) continue;
 
         try {
           const parsed = JSON.parse(value);
@@ -70,21 +68,24 @@ export function cleanupFactory(
               originalStorage.removeItem(key);
             }
             // If not expired, leave it as is
-          } else {
-            // Not a wrapped value yet, wrap it
+          } 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
-          originalStorage.setItem(
-            key,
-            JSON.stringify(createWrappedItem(value, expiresInSeconds))
-          );
+          // 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) {