feat(storage): Support storage items in batch functions

[Timeraa]

This pull request includes significant updates to the storage API documentation and implementation to support bulk operations and improve clarity. The most important changes include the addition of bulk operation methods in the documentation, corrections to grammar and phrasing, and enhancements to the WxtStorage interface to support these new methods.

Documentation Updates:

• Added a new section on bulk operations in docs/guide/extension-apis/storage.md, detailing methods like getItems, getItemMetas, setItemValues, setItemMetas, and removeItems.
• Corrected grammar and phrasing issues in various parts of the storage API documentation, improving readability and accuracy. [1] [2] [3]

Code Enhancements:

• Enhanced the createStorage function in packages/wxt/src/storage.ts to include new methods for bulk operations: getItemMetas, setItemValues, setItemMetas, and removeItems. [1] [2] [3] [4]
• Updated the WxtStorage interface to support the new bulk operation methods, ensuring type safety and consistency. [1] [2] [3]
• Improved the getItems method to maintain the order of keys and handle different key types more efficiently.

These changes collectively enhance the functionality and usability of the storage API, making it more powerful and easier to use for developers.

[netlify[bot]]

✅ Deploy Preview for creative-fairy-df92c4 ready!

Name	Link
🔨 Latest commit	a78b7d931a9168cbe272bcfdfa73359c8f1f3197
🔍 Latest deploy log	https://app.netlify.com/sites/creative-fairy-df92c4/deploys/6723085961420100082f17e9
😎 Deploy Preview	https://deploy-preview-990--creative-fairy-df92c4.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[pkg-pr-new[bot]]

Open in Stackblitz

@wxt-dev/auto-icons

pnpm add https://pkg.pr.new/@wxt-dev/auto-icons@990

@wxt-dev/i18n

pnpm add https://pkg.pr.new/@wxt-dev/i18n@990

@wxt-dev/module-react

pnpm add https://pkg.pr.new/@wxt-dev/module-react@990

@wxt-dev/module-solid

pnpm add https://pkg.pr.new/@wxt-dev/module-solid@990

@wxt-dev/module-svelte

pnpm add https://pkg.pr.new/@wxt-dev/module-svelte@990

@wxt-dev/module-vue

pnpm add https://pkg.pr.new/@wxt-dev/module-vue@990

@wxt-dev/unocss

pnpm add https://pkg.pr.new/@wxt-dev/unocss@990

wxt

pnpm add https://pkg.pr.new/wxt@990

commit: a78b7d9

[Timeraa]

Can you add tests? Specifically making sure the minimal number of storage calls are added.

Otherwise this is looking great! Thanks for adding this

Will do! Did the PR on a sleepless night

[aklinker1]

Haha I noticed you got it out like as soon as you asked about it on discord lol.

[Timeraa]

Now... I was reviewing the code, and noticed something. We already have some batch APIs:

await storage.getItems(["local:installDate", "session:someCounter"]);

What about instead of adding new functions, just adding them to the existing APIs:

const installDate = storage.defineItem(...);



await storage.getItems([installDate, "session:someCounter"]);

That way they use the same style, arrays instead of objects.

Yeah that sounds like a better idea

[Timeraa]

@Timeraa this is a big PR and your latest changes don't really match what I was asking for in this comment: #990 (review)

Would you mind if I implemented the changes for getItems so you have a better idea what direction I think we should go in?

Go ahead! Was just thinking that made the most sense and is the least breaking in that regard

[aklinker1]

Here's what my changes would look like if I updated the getItems and removeItems functions: https://github.com/wxt-dev/wxt/compare/batch-item-change-suggestions

The setter and metadata functions will be more complex, I'm not entirely sure how to type them to continue using the array syntax, but we should keep using arrays when possible, since that's how all the existing functions are written.

Only exception to that would be watch... where arrays vs objects would have different behaviors (like in vue's watch function).

// Watch multiple values with a single callback:
storage.watch([item1, item2], ([newItem1, newItem2], [oldItem1, oldItem2]) => {
  // ...
});

// Watch multiple values, each with their own callbacks
storage.watch({
  [item1.key]: (newValue, oldValue) => {
    // ...
  },
  "local:item2": (newValue, oldValue) => {
    // ...
  },
});
// or
storage.watch([
  [item1, (newValue, oldValue) => {
    // ...
  }],
  ["local:item2", (newValue, oldValue) => {
    // ...
  }],
]);

Not sure how I want the watch function to work, so I would put that in it's own PR where we can discuss it separately.

[Timeraa]

Here's what my changes would look like if I updated the getItems and removeItems functions: https://github.com/wxt-dev/wxt/compare/batch-item-change-suggestions

The setter and metadata functions will be more complex, I'm not entirely sure how to type them to continue using the array syntax, but we should keep using arrays when possible, since that's how all the existing functions are written.

Only exception to that would be watch... where arrays vs objects would have different behaviors (like in vue's watch function).

// Watch multiple values with a single callback:
storage.watch([item1, item2], ([newItem1, newItem2], [oldItem1, oldItem2]) => {
  // ...
});

// Watch multiple values, each with their own callbacks
storage.watch({
  [item1.key]: (newValue, oldValue) => {
    // ...
  },
  "local:item2": (newValue, oldValue) => {
    // ...
  },
});
// or
storage.watch([
  [item1, (newValue, oldValue) => {
    // ...
  }],
  ["local:item2", (newValue, oldValue) => {
    // ...
  }],
]);

Not sure how I want the watch function to work, so I would put that in it's own PR where we can discuss it separately.

Thanks, I'll implement it like you described and split the watch into another PR later!

[Timeraa]

Looking closer at it @aklinker1, wouldn't it make more sense if getItems returns an array of just the values since you can just use the array index since the order should be the same as the one how you passed it

const [item1value, item2value, item3value] = await storage.getItems(item1definition,item2definition,item3definition)

[aklinker1]

Yes, but two comments:

1. That's a breaking change. Lets wait to do that until storage has been pulled out of wxt, and is a separate package.
2. Even though the jsdoc I wrote says "The return order is guaranteed to be the same as the order requested"... I don't think that's true looking at the current implementation. So looking up the key you want to use is kinda required right now.

[Timeraa]

Yes, but two comments:

1. That's a breaking change. Lets wait to do that until storage has been pulled out of wxt, and is a separate package.
2. Even though the jsdoc I wrote says "The return order is guaranteed to be the same as the order requested"... I don't think that's true looking at the current implementation. So looking up the key you want to use is kinda required right now.

Okay! I'll fix the 2. point though!

[Timeraa]

Okay I think I implemented it right now? Hope I didn't over-read something

[Timeraa]

@aklinker1 Anything about this, need to fix the docs now since that changed but everything else looking good?

[aklinker1]

Gonna merge, if there are problems, let's fix in another PR.

[codecov[bot]]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 82.47%. Comparing base (0318a34) to head (a78b7d9). Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #990      +/-   ##
==========================================
+ Coverage   81.96%   82.47%   +0.50%     
==========================================
  Files         127      127              
  Lines        6670     6767      +97     
  Branches     1107     1135      +28     
==========================================
+ Hits         5467     5581     +114     
+ Misses       1189     1172      -17     
  Partials       14       14              

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

[aklinker1]

Released in https://github.com/wxt-dev/wxt/releases/tag/wxt-v0.19.14