Storage Item Serialization and Validation

[aklinker1]

Feature Request

When defineing storage items, getting values, or setting values, we should support serialization options for converting storage to and from a specific data type:

const enabledSites = storage.defineItem<Set<string>, {}, string[]>("enabledSites", {
  schema: {
    // Convert usable value to storage compatible value
    serialize: (set) => [...set],
    // Convert storage compatible value to usable type
    deserialize: (array) => new Set(array),
  },
});

const set = await enabledSites.getValue();
set.has("google.com")

A natural extension to this is to support various other popular data serialization and validation libraries, like Zod and TypeBox.

import { z } from 'zod';

const themePreference: WxtStorageItem<"light" | "dark" | "system"> = storage.defineItem("themePreference", {
  schema: z.enum(["light", "dark", "system"]),
});

import { Type } from '@sinclair/typebox';
import { Value } from '@sinclair/typebox';

const themePreference: WxtStorageItem<"light" | "dark" | "system"> = storage.defineItem("themePreference", {
  schema: (value) => Value.Parse(
    Type.Union([Type.Literal("light"), Type.Literal("dark"), Type.Literal("system")]),
    value,
  ),
});

Is your feature request related to a bug?

#1123

What are the alternatives?

Write a wrapper around storage.defineItem yourself.

Additional context

N/A

[Timeraa]

Would be nice with arktype

[aklinker1]

Would be nice with arktype

Hadn't heard of that one before... I'll give it a go sometime, looks really cool! I see you're a sponsor 😉

Should be easy enough to support, just a function, or if something goes terribly wrong, we can always use the assert function they show integrating with tRPC.

type StorageItemSchema<TValue, TStored> =
  // Manual serialization functions
  | { serialize(value: TValue): TStored, deserialize(stored: TStored): TValue }
  // Zod
  | { parse(stored: TStored): TValue }
  // Arktypes & Typebox
  | (stored: TStored) => TValue

[aklinker1]

Will also need to decide what happens when validation fails... Do we do nothing? Return the default value? Throw the error? Overwrite the bad value or leave it as-is? How do we integrate a logger for error reporters to hook into? Some questions to answer...

[Timeraa]

Not quite sure how you'd design the api around it but might be nice to have the option to decide what happens, like either hook into an event and if it's not hooked into we reset it or something?

[Timeraa]

Would be nice with arktype

Hadn't heard of that one before... I'll give it a go sometime, looks really cool! I see you're a sponsor 😉

Should be easy enough to support, just a function, or if something goes terribly wrong, we can always use the assert function they show integrating with tRPC.

type StorageItemSchema<TValue, TStored> =
  // Manual serialization functions
  | { serialize(value: TValue): TStored, deserialize(stored: TStored): TValue }
  // Zod
  | { parse(stored: TStored): TValue }
  // Arktypes & Typebox
  | (stored: TStored) => TValue

I love arktype, it's super fast and gives the best usable types in the editor imo haha

[aklinker1]

One more addition: an alternative to Plasmo's secure storage. I don't think calling it "secure" is the right move, in reality, it's just 2-way encoded with a "secret" key that's shipped with the extension. So we could easily add an equivalent API:

const encodeAtRest = createStorageEncoder("key");

export const example = defineStorageItem("local:example", {
  schema: encodeAtRest(z.String())
});

Doesn't need to be apart of the initial feature, and that's just an idea of what the API might look like. Could be a separate field unrelated to schema as well.