wxt 0.12.4 → 0.13.0

package/dist/storage.d.cts

@@ -1,15 +1,188 @@
-import { Driver, Storage } from 'unstorage';
-export * from 'unstorage';
-
+declare const storage: WxtStorage;
+interface WxtStorage {
+    /**
+     * Get an item from storage, or return `null` if it doesn't exist.
+     *
+     * @example
+     * await storage.getItem<number>("local:installDate");
+     */
+    getItem<T>(key: string, opts?: GetItemOptions<T>): Promise<T | null>;
+    /**
+     * Get multiple items from storage. There is no guarentee of order in the returned array.
+     *
+     * @example
+     * await storage.getItems(["local:installDate", "session:someCounter"]);
+     */
+    getItems(keys: Array<string | {
+        key: string;
+        options?: GetItemOptions<any>;
+    }>): Promise<Array<{
+        key: string;
+        value: any;
+    }>>;
+    /**
+     * Return an object containing metadata about the key. Object is stored at `key + "$"`. If value
+     * is not an object, it returns an empty object.
+     *
+     * @example
+     * await storage.getMeta("local:installDate");
+     */
+    getMeta<T extends Record<string, unknown>>(key: string): Promise<T>;
+    /**
+     * Set a value in storage. Setting a value to `null` or `undefined` is equivalent to calling
+     * `removeItem`.
+     *
+     * @example
+     * await storage.setItem<number>("local:installDate", Date.now());
+     */
+    setItem<T>(key: string, value: T | null): Promise<void>;
+    /**
+     * Set multiple values in storage. If a value is set to `null` or `undefined`, the key is removed.
+     *
+     * @example
+     * await storage.setItem([
+     *   { key: "local:installDate", value: Date.now() },
+     *   { key: "session:someCounter, value: 5 },
+     * ]);
+     */
+    setItems(values: Array<{
+        key: string;
+        value: any;
+    }>): Promise<void>;
+    /**
+     * Sets metadata properties. If some properties are already set, but are not included in the
+     * `properties` parameter, they will not be removed.
+     *
+     * @example
+     * await storage.setMeta("local:installDate", { appVersion });
+     */
+    setMeta<T extends Record<string, unknown>>(key: string, properties: T | null): Promise<void>;
+    /**
+     * Removes an item from storage.
+     *
+     * @example
+     * await storage.removeItem("local:installDate");
+     */
+    removeItem(key: string, opts?: RemoveItemOptions): Promise<void>;
+    /**
+     * Remove a list of keys from storage.
+     */
+    removeItems(keys: Array<string | {
+        key: string;
+        options?: RemoveItemOptions;
+    }>): Promise<void>;
+    /**
+     * Remove the entire metadata for a key, or specific properties by name.
+     *
+     * @example
+     * // Remove all metadata properties from the item
+     * await storage.removeMeta("local:installDate");
+     *
+     * // Remove only specific the "v" field
+     * await storage.removeMeta("local:installDate", "v")
+     */
+    removeMeta(key: string, properties?: string | string[]): Promise<void>;
+    /**
+     * Return all the items in storage.
+     */
+    snapshot(base: string, opts?: SnapshotOptions): Promise<Record<string, unknown>>;
+    /**
+     * Restores the results of `snapshot`. If new properties have been saved since the snapshot, they are
+     * not overridden. Only values existing in the snapshot are overritten.
+     */
+    restoreSnapshot(base: string, data: any): Promise<void>;
+    /**
+     * Watch for changes to a specific key in storage.
+     */
+    watch<T>(key: string, cb: WatchCallback<T>): Unwatch;
+    /**
+     * Remove all watch listeners.
+     */
+    unwatch(): void;
+    /**
+     * Define a constant with utilities for reading/writing to a single value in storage.
+     *
+     * @example
+     * export const installDate = storage.defineItem<number>("local:installDate");
+     */
+    defineItem<TValue, TMetadata extends Record<string, unknown> = {}>(key: string, options?: WxtStorageItemOptions<TValue>): WxtStorageItem<TValue, TMetadata>;
+}
+interface WxtStorageItem<TValue, TMetadata extends Record<string, unknown>> {
+    /**
+     * Get the latest value from storage.
+     */
+    getValue(): Promise<TValue>;
+    /**
+     * Get metadata.
+     */
+    getMeta(): Promise<NullablePartial<TMetadata>>;
+    /**
+     * Set the value in storage.
+     */
+    setValue(value: TValue | null): Promise<void>;
+    /**
+     * Set metadata properties.
+     */
+    setMeta(properties: NullablePartial<TMetadata>): Promise<void>;
+    /**
+     * Remove the value from storage.
+     */
+    removeValue(opts?: RemoveItemOptions): Promise<void>;
+    /**
+     * Remove all metadata or certain properties from metadata.
+     */
+    removeMeta(properties?: string[]): Promise<void>;
+    /**
+     * Listen for changes to the value in storage.
+     */
+    watch(cb: WatchCallback<TValue>): Unwatch;
+}
+interface GetItemOptions<T> {
+    /**
+     * Value returned from `getValue` when it would otherwise return null.
+     */
+    defaultValue?: T;
+}
+interface RemoveItemOptions {
+    /**
+     * Optionally remove metadata when deleting a key.
+     *
+     * @default false
+     */
+    removeMeta?: boolean;
+}
+interface SnapshotOptions {
+    /**
+     * Exclude a list of keys. The storage area prefix should be removed since the snapshot is for a
+     * specific storage area already.
+     */
+    excludeKeys?: string[];
+}
+interface WxtStorageItemOptions<T> extends GetItemOptions<T> {
+    /**
+     * Provide a version number for the storage item to enable migrations. When changing the version
+     * in the future, migration functions will be ran on application startup.
+     */
+    version?: number;
+    /**
+     * A map of version numbers to the functions used to migrate the data to that version.
+     */
+    migrations?: Record<number, (oldValue: any) => any>;
+}
 /**
- * @module wxt/storage
+ * Same as `Partial`, but includes `| null`. It makes all the properties of an object optional and
+ * nullable.
  */
+type NullablePartial<T> = {
+    [key in keyof T]+?: T[key] | undefined | null;
+};
+/**
+ * Callback called when a value in storage is changed.
+ */
+type WatchCallback<T> = (newValue: T | null, oldValue: T | null) => void;
+/**
+ * Call to remove a watch listener
+ */
+type Unwatch = () => void;
 
-interface WebExtensionDriverOptions {
-    storageArea: 'sync' | 'local' | 'managed' | 'session';
-}
-declare const webExtensionDriver: (opts: WebExtensionDriverOptions) => Driver;
-type StorageValue = null | string | number | boolean | object;
-declare const storage: Storage<StorageValue>;
-
-export { type StorageValue, type WebExtensionDriverOptions, storage, webExtensionDriver };
+export { type GetItemOptions, type NullablePartial, type RemoveItemOptions, type SnapshotOptions, type Unwatch, type WatchCallback, type WxtStorage, type WxtStorageItem, type WxtStorageItemOptions, storage };

package/dist/storage.d.ts

@@ -1,15 +1,188 @@
-import { Driver, Storage } from 'unstorage';
-export * from 'unstorage';
-
+declare const storage: WxtStorage;
+interface WxtStorage {
+    /**
+     * Get an item from storage, or return `null` if it doesn't exist.
+     *
+     * @example
+     * await storage.getItem<number>("local:installDate");
+     */
+    getItem<T>(key: string, opts?: GetItemOptions<T>): Promise<T | null>;
+    /**
+     * Get multiple items from storage. There is no guarentee of order in the returned array.
+     *
+     * @example
+     * await storage.getItems(["local:installDate", "session:someCounter"]);
+     */
+    getItems(keys: Array<string | {
+        key: string;
+        options?: GetItemOptions<any>;
+    }>): Promise<Array<{
+        key: string;
+        value: any;
+    }>>;
+    /**
+     * Return an object containing metadata about the key. Object is stored at `key + "$"`. If value
+     * is not an object, it returns an empty object.
+     *
+     * @example
+     * await storage.getMeta("local:installDate");
+     */
+    getMeta<T extends Record<string, unknown>>(key: string): Promise<T>;
+    /**
+     * Set a value in storage. Setting a value to `null` or `undefined` is equivalent to calling
+     * `removeItem`.
+     *
+     * @example
+     * await storage.setItem<number>("local:installDate", Date.now());
+     */
+    setItem<T>(key: string, value: T | null): Promise<void>;
+    /**
+     * Set multiple values in storage. If a value is set to `null` or `undefined`, the key is removed.
+     *
+     * @example
+     * await storage.setItem([
+     *   { key: "local:installDate", value: Date.now() },
+     *   { key: "session:someCounter, value: 5 },
+     * ]);
+     */
+    setItems(values: Array<{
+        key: string;
+        value: any;
+    }>): Promise<void>;
+    /**
+     * Sets metadata properties. If some properties are already set, but are not included in the
+     * `properties` parameter, they will not be removed.
+     *
+     * @example
+     * await storage.setMeta("local:installDate", { appVersion });
+     */
+    setMeta<T extends Record<string, unknown>>(key: string, properties: T | null): Promise<void>;
+    /**
+     * Removes an item from storage.
+     *
+     * @example
+     * await storage.removeItem("local:installDate");
+     */
+    removeItem(key: string, opts?: RemoveItemOptions): Promise<void>;
+    /**
+     * Remove a list of keys from storage.
+     */
+    removeItems(keys: Array<string | {
+        key: string;
+        options?: RemoveItemOptions;
+    }>): Promise<void>;
+    /**
+     * Remove the entire metadata for a key, or specific properties by name.
+     *
+     * @example
+     * // Remove all metadata properties from the item
+     * await storage.removeMeta("local:installDate");
+     *
+     * // Remove only specific the "v" field
+     * await storage.removeMeta("local:installDate", "v")
+     */
+    removeMeta(key: string, properties?: string | string[]): Promise<void>;
+    /**
+     * Return all the items in storage.
+     */
+    snapshot(base: string, opts?: SnapshotOptions): Promise<Record<string, unknown>>;
+    /**
+     * Restores the results of `snapshot`. If new properties have been saved since the snapshot, they are
+     * not overridden. Only values existing in the snapshot are overritten.
+     */
+    restoreSnapshot(base: string, data: any): Promise<void>;
+    /**
+     * Watch for changes to a specific key in storage.
+     */
+    watch<T>(key: string, cb: WatchCallback<T>): Unwatch;
+    /**
+     * Remove all watch listeners.
+     */
+    unwatch(): void;
+    /**
+     * Define a constant with utilities for reading/writing to a single value in storage.
+     *
+     * @example
+     * export const installDate = storage.defineItem<number>("local:installDate");
+     */
+    defineItem<TValue, TMetadata extends Record<string, unknown> = {}>(key: string, options?: WxtStorageItemOptions<TValue>): WxtStorageItem<TValue, TMetadata>;
+}
+interface WxtStorageItem<TValue, TMetadata extends Record<string, unknown>> {
+    /**
+     * Get the latest value from storage.
+     */
+    getValue(): Promise<TValue>;
+    /**
+     * Get metadata.
+     */
+    getMeta(): Promise<NullablePartial<TMetadata>>;
+    /**
+     * Set the value in storage.
+     */
+    setValue(value: TValue | null): Promise<void>;
+    /**
+     * Set metadata properties.
+     */
+    setMeta(properties: NullablePartial<TMetadata>): Promise<void>;
+    /**
+     * Remove the value from storage.
+     */
+    removeValue(opts?: RemoveItemOptions): Promise<void>;
+    /**
+     * Remove all metadata or certain properties from metadata.
+     */
+    removeMeta(properties?: string[]): Promise<void>;
+    /**
+     * Listen for changes to the value in storage.
+     */
+    watch(cb: WatchCallback<TValue>): Unwatch;
+}
+interface GetItemOptions<T> {
+    /**
+     * Value returned from `getValue` when it would otherwise return null.
+     */
+    defaultValue?: T;
+}
+interface RemoveItemOptions {
+    /**
+     * Optionally remove metadata when deleting a key.
+     *
+     * @default false
+     */
+    removeMeta?: boolean;
+}
+interface SnapshotOptions {
+    /**
+     * Exclude a list of keys. The storage area prefix should be removed since the snapshot is for a
+     * specific storage area already.
+     */
+    excludeKeys?: string[];
+}
+interface WxtStorageItemOptions<T> extends GetItemOptions<T> {
+    /**
+     * Provide a version number for the storage item to enable migrations. When changing the version
+     * in the future, migration functions will be ran on application startup.
+     */
+    version?: number;
+    /**
+     * A map of version numbers to the functions used to migrate the data to that version.
+     */
+    migrations?: Record<number, (oldValue: any) => any>;
+}
 /**
- * @module wxt/storage
+ * Same as `Partial`, but includes `| null`. It makes all the properties of an object optional and
+ * nullable.
  */
+type NullablePartial<T> = {
+    [key in keyof T]+?: T[key] | undefined | null;
+};
+/**
+ * Callback called when a value in storage is changed.
+ */
+type WatchCallback<T> = (newValue: T | null, oldValue: T | null) => void;
+/**
+ * Call to remove a watch listener
+ */
+type Unwatch = () => void;
 
-interface WebExtensionDriverOptions {
-    storageArea: 'sync' | 'local' | 'managed' | 'session';
-}
-declare const webExtensionDriver: (opts: WebExtensionDriverOptions) => Driver;
-type StorageValue = null | string | number | boolean | object;
-declare const storage: Storage<StorageValue>;
-
-export { type StorageValue, type WebExtensionDriverOptions, storage, webExtensionDriver };
+export { type GetItemOptions, type NullablePartial, type RemoveItemOptions, type SnapshotOptions, type Unwatch, type WatchCallback, type WxtStorage, type WxtStorageItem, type WxtStorageItemOptions, storage };