feat: support cloudflare options with setItem

[Hebilicious]

🔗 Linked issue

Resolves #32

First part of #236

❓ Type of change

• 📖 Documentation (updates to the documentation, readme or JSdoc annotations)
• 🐞 Bug fix (a non-breaking change that fixes an issue)
• 👌 Enhancement (improving an existing functionality like performance)
• ✨ New feature (a non-breaking change that adds functionality)
• 🧹 Chore (updates to the build process or auxiliary tools and libraries)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)

📚 Description

This PR allows the ability to pass options to the setItem method while using the cloudflare driver :

await storage.setItem("key", "value", 
{ 
  expiration: 1578435000, 
  expiration_ttl: 300, // http driver
  expirationTtl: 300, // binding driver
  base64: false,
  metadata: { someMetadataKey: "someMetadataValue" }
});

• implements the cloudflare options such as metadata, expiring keys, etc.
  • Forward the 3rd argument (options) to the cloudflare-kv-bindingand cloudflare-kv-http drivers setItem method.
  • Changes the put implementation of the cloudflare-kv-http to use the bulk API (to support all options).

Options "API design"

For now I'm leverage the 3rd argument of the setItem method, but I was thinking that we could require users to pass them nested under a key ({ cloudflare: {} }), or use a 4th argument, in-case we want to keep the 3rd argument open for unstorage specific options... Thoughts ?

📝 Checklist

• I have linked an issue or discussion.
• I have updated the documentation accordingly.

[nuxt-studio]

✅ Live Preview ready!

Name	Edit	Preview	Latest Commit
unstorage	Edit on Studio ↗︎	View Live Preview	ee82649

[codecov]

Codecov Report

Merging #255 (42112e3) into main (e41a1df) will increase coverage by 0.56%.
Report is 1 commits behind head on main.
The diff coverage is 93.04%.

@@            Coverage Diff             @@
##             main     #255      +/-   ##
==========================================
+ Coverage   77.96%   78.52%   +0.56%     
==========================================
  Files          29       29              
  Lines        3417     3483      +66     
  Branches      521      522       +1     
==========================================
+ Hits         2664     2735      +71     
+ Misses        752      747       -5     
  Partials        1        1              

Files Changed	Coverage Δ
src/drivers/http.ts	85.56% <85.71%> (ø)
src/drivers/cloudflare-kv-binding.ts	84.46% <89.47%> (+0.74%)	⬆️
src/drivers/cloudflare-kv-http.ts	89.57% <93.33%> (+5.10%)	⬆️
src/drivers/cloudflare-r2-binding.ts	77.57% <100.00%> (ø)
src/types.ts	100.00% <100.00%> (ø)

📢 Have feedback on the report? Share it here.

[Hebilicious]

Refactor with namespace

[Hebilicious]

Added a generic ttl parameters, as well as a default ttl configurable in the options.
Also added namespaced options under the kebabcased driver name : cloudflareKvBinding and cloudflareKvHttp.
Since they are different we can't use the same key.

I noticed that you didn't nest the cloudflare r2 options under a key, so for now we need to be more explicit with any. This should be fixed in another PR.

There's also a bunch of new bugs that this PR fixes in r2 and http, as we were using any before.

@pi0 I think we need multiple PRs:

1. Refactor TransactionOptions into 2 new types that are more explicit, SetItemOptions and GetItemOptions, and have the generic ttl?: number, and fix the type bugs without changing behaviours.
2. Refactor R2 with a nested key (id say make the breaking change as its only 4d old, would give full type safety, and we discussed this already)
3. Add the SetItemOptions for cfkvb and cfkvhttp according to this PR.

[pi0]

Refactor TransactionOptions into 2 new types that are more explicit, SetItemOptions and GetItemOptions, and have the generic ttl?: number, and fix the type bugs without changing behaviours.

As i mentioned in other PR, it would make sense to support one kind of options interface (even if some option keys are not used by read operation). Particulary for ttl that should be also supported for passive key expiration for drivers not supporting ttl.

Refactor R2 with a nested key (id say make the breaking change as its only 4d old, would give full type safety, and we discussed this already)

👍🏼

[Hebilicious]

@pi0 Should we still introduce ttl in a separated PR #271 (TransactionOptions) ? It causes some minor issues with some existing presets, hence why its cleaner separately.
But if you prefer just doing everything through this one I'm fine either way.

[pi0]

If it is only for type, surely we can add ttl? type to generic TransactionOptions in this PR 👍🏼

[Hebilicious]

@pi0 I would be happy to revisit splitting TransactionOptions once it's actually needed. For now I've implemented everything in this PR according to your requirements.
http and r2 needs to be slightly tweaked because we are no longer using any for TransactionOptions. This doesn't affect the runtime.

[pi0]

Thanks for the updates. As an update, i still need to double check all changes there are too many changes some are unrelated to the feature we want to add.

[Hebilicious]

Thanks for the updates. As an update, i still need to double check all changes there are too many changes some are unrelated to the feature we want to add.

@pi0 I had to change these things :

• API endpoint : according to the docs the regular api endpoint doesn't support ttl, only the bulk endpoint does
• updating the types: blast radius in the other cloudflare types
• Switching to ofetch.native: is done so that the tests in test: update kv-http tests to latest msw #256 work

[pi0]

PR is stalled and with too many changes, have to rework this.

(but again really appreciate your previous help on this ❤️ )