From 2ced9c40d36d3ea76afeb6c8eef73c9bdc14c9e7 Mon Sep 17 00:00:00 2001
From: ergou <ma2808203259@hotmail.com>
Date: Thu, 20 Mar 2025 17:11:34 +1100
Subject: [PATCH] feat(storage): Add `debug` option to enable migration logs
 (#1513)

---
 packages/storage/src/__tests__/index.test.ts | 67 ++++++++++++++++++++
 packages/storage/src/index.ts                | 31 ++++++---
 2 files changed, 90 insertions(+), 8 deletions(-)

diff --git a/packages/storage/src/__tests__/index.test.ts b/packages/storage/src/__tests__/index.test.ts
index 52e7a740..a598e4b5 100644
--- a/packages/storage/src/__tests__/index.test.ts
+++ b/packages/storage/src/__tests__/index.test.ts
@@ -871,6 +871,73 @@ describe('Storage Utils', () => {
 
         await expect(item.migrate()).rejects.toThrow(expectedError);
       });
+
+      it('should print migration logs if debug option is true', async () => {
+        await fakeBrowser.storage.local.set({
+          count: 2,
+          count$: { v: 1 },
+        });
+        const migrateToV2 = vi.fn((oldCount) => oldCount * 2);
+        const migrateToV3 = vi.fn((oldCount) => oldCount * 3);
+        const consoleSpy = vi.spyOn(console, 'debug');
+
+        storage.defineItem<number, { v: number }>(`local:count`, {
+          defaultValue: 0,
+          version: 3,
+          migrations: {
+            2: migrateToV2,
+            3: migrateToV3,
+          },
+          debug: true,
+        });
+        await waitForMigrations();
+
+        expect(consoleSpy).toHaveBeenCalledTimes(4);
+        expect(consoleSpy).toHaveBeenCalledWith(
+          `[@wxt-dev/storage] Running storage migration for local:count: v1 -> v3`,
+        );
+        expect(consoleSpy).toHaveBeenCalledWith(
+          `[@wxt-dev/storage] Storage migration processed for version: v2`,
+        );
+        expect(consoleSpy).toHaveBeenCalledWith(
+          `[@wxt-dev/storage] Storage migration processed for version: v3`,
+        );
+        expect(consoleSpy).toHaveBeenCalledWith(
+          `[@wxt-dev/storage] Storage migration completed for local:count v3`,
+          { migratedValue: expect.any(Number) },
+        );
+      });
+      it('should not print migration logs if debug option is undefined or false', async () => {
+        await fakeBrowser.storage.local.set({
+          count: 2,
+          count$: { v: 1 },
+          count2: 2,
+          count2$: { v: 1 },
+        });
+        const migrateToV2 = vi.fn((oldCount) => oldCount * 2);
+        const migrateToV3 = vi.fn((oldCount) => oldCount * 3);
+        const consoleSpy = vi.spyOn(console, 'debug');
+
+        storage.defineItem<number, { v: number }>(`local:count`, {
+          defaultValue: 0,
+          version: 3,
+          migrations: {
+            2: migrateToV2,
+            3: migrateToV3,
+          },
+        });
+
+        storage.defineItem<number, { v: number }>(`local:count2`, {
+          defaultValue: 0,
+          version: 2,
+          migrations: {
+            2: migrateToV2,
+          },
+          debug: false,
+        });
+        await waitForMigrations();
+        expect(consoleSpy).toHaveBeenCalledTimes(0);
+      });
     });
 
     describe('getValue', () => {
diff --git a/packages/storage/src/index.ts b/packages/storage/src/index.ts
index ecda0898..0b0ced7c 100644
--- a/packages/storage/src/index.ts
+++ b/packages/storage/src/index.ts
@@ -267,7 +267,6 @@ function createStorage(): WxtStorage {
           async ([storageArea, updates]) => {
             const driver = getDriver(storageArea as StorageArea);
             const metaKeys = updates.map(({ key }) => getMetaKey(key));
-            console.log(storageArea, metaKeys);
             const existingMetas = await driver.getItems(metaKeys);
             const existingMetaMap = Object.fromEntries(
               existingMetas.map(({ key, value }) => [key, getMetaValue(value)]),
@@ -363,6 +362,7 @@ function createStorage(): WxtStorage {
         version: targetVersion = 1,
         migrations = {},
         onMigrationComplete,
+        debug = false,
       } = opts ?? {};
       if (targetVersion < 1) {
         throw Error(
@@ -387,9 +387,11 @@ function createStorage(): WxtStorage {
           return;
         }
 
-        console.debug(
-          `[@wxt-dev/storage] Running storage migration for ${key}: v${currentVersion} -> v${targetVersion}`,
-        );
+        if (debug === true) {
+          console.debug(
+            `[@wxt-dev/storage] Running storage migration for ${key}: v${currentVersion} -> v${targetVersion}`,
+          );
+        }
         const migrationsToRun = Array.from(
           { length: targetVersion - currentVersion },
           (_, i) => currentVersion + i + 1,
@@ -400,6 +402,11 @@ function createStorage(): WxtStorage {
             migratedValue =
               (await migrations?.[migrateToVersion]?.(migratedValue)) ??
               migratedValue;
+            if (debug === true) {
+              console.debug(
+                `[@wxt-dev/storage] Storage migration processed for version: v${migrateToVersion}`,
+              );
+            }
           } catch (err) {
             throw new MigrationError(key, migrateToVersion, {
               cause: err,
@@ -410,11 +417,14 @@ function createStorage(): WxtStorage {
           { key: driverKey, value: migratedValue },
           { key: driverMetaKey, value: { ...meta, v: targetVersion } },
         ]);
+
+        if (debug === true) {
+          console.debug(
+            `[@wxt-dev/storage] Storage migration completed for ${key} v${targetVersion}`,
+            { migratedValue },
+          );
+        }
         onMigrationComplete?.(migratedValue, targetVersion);
-        console.debug(
-          `[@wxt-dev/storage] Storage migration completed for ${key} v${targetVersion}`,
-          { migratedValue },
-        );
       };
       const migrationsDone =
         opts?.migrations == null
@@ -867,6 +877,11 @@ export interface WxtStorageItemOptions<T> {
    * A map of version numbers to the functions used to migrate the data to that version.
    */
   migrations?: Record<number, (oldValue: any) => any>;
+  /**
+   * Print debug logs, such as migration process.
+   * @default false
+   */
+  debug?: boolean;
   /**
    * A callback function that runs on migration complete.
    */