chore: Add JSDOC comments and fix grammatical errors

drivers/idb.ts

@@ -1,12 +1,26 @@
+/**
+ * Class representing an IndexedDB storage, with a simplified API.
+ *
+ * @template T - The type of the value to be stored.
+ */
 export default class indexedDB<T> {
   private defaultDb;
   private defaultVersion;
   private defaultObjectStore;
+  /**
+   * Creates an instance of the IndexedDB storage.
+   */
   constructor() {
     this.defaultDb = "svelte-persisted-store";
     this.defaultVersion = 1;
     this.defaultObjectStore = "keyvaluepairs";
   }
+  /**
+   * Retrieves an item from the IndexedDB storage.
+   *
+   * @param key - The key of the item to retrieve.
+   * @returns A promise that resolves with the retrieved item or null if the item does not exist.
+   */
   public getItem(key: string): Promise<string | null> {
     return new Promise((resolve, reject) => {
       const request = window.indexedDB.open(
@@ -24,6 +38,13 @@ export default class indexedDB<T> {
       };
     });
   }
+  /**
+   * Stores an item in the IndexedDB storage.
+   *
+   * @param key - The key under which to store the item.
+   * @param value - The value to store.
+   * @returns A promise that resolves when the operation is complete.
+   */
   public setItem(key: string, value: T): Promise<void> {
     return new Promise((resolve, reject) => {
       const request = window.indexedDB.open(

index.ts

@@ -15,19 +15,31 @@ const stores: Stores = {
   indexedDB: {},
 };
 
-/** @deprecated `writable()` has been renamed to `localState(())` */
+/**
+ * @deprecated `writable()` has been renamed to `persisted()`
+ * @param {string} key - The key for the store.
+ * @param {StoreType} initialValue - The initial value for the store.
+ * @param {Options<StoreType, SerializerType>} options - The options for the store.
+ * @returns {Persisted<StoreType>} - The persisted store.
+ */
 export function writable<StoreType, SerializerType = StoreType>(
   key: string,
   initialValue: StoreType,
   options?: Options<StoreType, SerializerType>
 ): Persisted<StoreType> {
   console.warn(
-    "writable() has been deprecated. Please use localState(()) instead.\n\nchange:\n\nimport { writable } from 'svelte-persisted-store-idb'\n\nto:\n\nimport { persisted } from 'svelte-persisted-store-idb'"
+    "writable() has been deprecated. Please use localState() instead.\n\nchange:\n\nimport { writable } from 'svelte-persisted-store'\n\nto:\n\nimport { persisted } from 'svelte-persisted-store'"
   );
   return persisted<StoreType, SerializerType>(key, initialValue, options);
 }
 
-/** @deprecated `persisted()` has been deprecated. */
+/**
+ * @deprecated `persisted()` has been deprecated.
+ * @param {string} key - The key for the store.
+ * @param {StoreType} initialValue - The initial value for the store.
+ * @param {DeprecatedOptions<StoreType, SerializerType>} options - The options for the store.
+ * @returns {Persisted<StoreType>} - The persisted store.
+ */
 export function persisted<StoreType, SerializerType = StoreType>(
   key: string,
   initialValue: StoreType,
@@ -46,7 +58,13 @@ export function persisted<StoreType, SerializerType = StoreType>(
       throw new Error("Invalid storage type. Please use 'local' or 'session'");
   }
 }
-
+/**
+ * Creates a local state.
+ * @param {string} key - The key for the store.
+ * @param {StoreType} initialValue - The initial value for the store.
+ * @param {Options<StoreType, SerializerType>} options - The options for the store.
+ * @returns {Persisted<StoreType>} - The persisted store.
+ */
 export function localState<StoreType, SerializerType = StoreType>(
   key: string,
   initialValue: StoreType,
@@ -57,7 +75,13 @@ export function localState<StoreType, SerializerType = StoreType>(
     storage: "local",
   });
 }
-
+/**
+ * Creates a session state.
+ * @param {string} key - The key for the store.
+ * @param {StoreType} initialValue - The initial value for the store.
+ * @param {Options<StoreType, SerializerType>} options - The options for the store.
+ * @returns {Persisted<StoreType>} - The persisted store.
+ */
 export function sessionState<StoreType, SerializerType = StoreType>(
   key: string,
   initialValue: StoreType,
@@ -68,7 +92,12 @@ export function sessionState<StoreType, SerializerType = StoreType>(
     storage: "session",
   });
 }
-
+/**
+ * Creates an IndexedDB state.
+ * @param {string} key - The key for the store.
+ * @param {T} initialValue - The initial value for the store.
+ * @returns {Promise<Persisted<T> | AsyncPersisted<T>>} - The persisted store.
+ */
 export async function indexedDBState<T>(
   key: string,
   initialValue: T

types/options.ts

@@ -1,21 +1,48 @@
 import type { Serializer, StorageType } from "./storage";
 
+/**
+ * Options interface with optional properties for customizing the store behavior.
+ *
+ * @template StoreType - The type of the store.
+ * @template SerializerType - The type of the serializer.
+ */
 export interface Options<StoreType, SerializerType> {
+  /** Optional serializer for custom serialization logic. */
   serializer?: Serializer<SerializerType>;
+  /** If true, synchronizes the store across multiple tabs. */
   syncTabs?: boolean;
+  /** Callback function to handle errors. */
   onError?: (e: unknown) => void;
+  /** Callback function to handle write errors. */
   onWriteError?: (e: unknown) => void;
+  /** Callback function to handle parse errors. */
   onParseError?: (newValue: string | null, e: unknown) => void;
+  /** Function to process values before reading from the store. */
   beforeRead?: (val: SerializerType) => StoreType;
+  /** Function to process values before writing to the store. */
   beforeWrite?: (val: StoreType) => SerializerType;
 }
 
+/**
+ * Options interface with required storage property.
+ *
+ * @template StoreType - The type of the store.
+ * @template SerializerType - The type of the serializer.
+ */
 export interface OptionsWithRequiredStorage<StoreType, SerializerType>
   extends Options<StoreType, SerializerType> {
+  /** Required storage type. */
   storage: StorageType;
 }
 
+/**
+ * Deprecated options interface with optional storage property.
+ *
+ * @template StoreType - The type of the store.
+ * @template SerializerType - The type of the serializer.
+ */
 export interface DeprecatedOptions<StoreType, SerializerType>
   extends Options<StoreType, SerializerType> {
+  /** Optional storage type. */
   storage?: StorageType;
 }

types/storage.ts

@@ -1,6 +1,28 @@
+/**
+ * Defines the storage types that were available before the introduction of IndexedDB support.
+ * This type is associated with the deprecated `persisted()` function.
+ */
 export type StorageType = "local" | "session";
 
+/**
+ * Interface representing a serializer.
+ *
+ * @template T - The type of the object to be serialized/deserialized.
+ */
 export interface Serializer<T> {
+  /**
+   * Parses a string and returns an object of type T.
+   *
+   * @param text - The string to parse.
+   * @returns The parsed object.
+   */
   parse(text: string): T;
+
+  /**
+   * Converts an object of type T to a string.
+   *
+   * @param object - The object to stringify.
+   * @returns The stringified object.
+   */
   stringify(object: T): string;
 }

types/store.ts

@@ -1,35 +1,76 @@
 import { type Writable } from "svelte/store";
 
+/**
+ * Type representing an updater function.
+ *
+ * @template T - The type of the value to be updated.
+ */
 export type Updater<T> = (value: T) => T;
+
+/**
+ * Interface representing the different types of stores.
+ */
 export interface Stores {
+  /** Local storage dictionary. */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   local: StoreDict<any>;
+  /** Session storage dictionary. */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   session: StoreDict<any>;
+  /** IndexedDB storage dictionary. */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   indexedDB: StoreDict<any>;
 }
 
+/**
+ * Type representing a dictionary of persisted stores.
+ *
+ * @template T - The type of the value in the store.
+ */
 export type StoreDict<T> = {
   [key: string]: Persisted<T> | AsyncPersisted<T>;
 };
+
+/**
+ * Interface representing an asynchronous persisted store.
+ *
+ * @template T - The type of the value in the store.
+ */
 export interface AsyncPersisted<T> extends Writable<T> {
+  /**
+   * Asynchronously sets the value of the store.
+   *
+   * @param value - The new value.
+   */
   set: (this: void, value: T) => Promise<void>;
+  /** Asynchronously resets the store to its initial value. */
   reset: () => Promise<void>;
+  /**
+   * Asynchronously updates the value of the store using a callback function.
+   *
+   * @param callback - The updater function.
+   */
   update: (callback: Updater<T>) => Promise<void>;
 }
 
+/**
+ * Interface representing a persisted store.
+ *
+ * @template T - The type of the value in the store.
+ */
 export interface Persisted<T> extends Writable<T> {
+  /**
+   * Sets the value of the store.
+   *
+   * @param value - The new value.
+   */
   set: (this: void, value: T) => void;
+  /** Resets the store to its initial value. */
   reset: () => void;
+  /**
+   * Updates the value of the store using a callback function.
+   *
+   * @param callback - The updater function.
+   */
   update: (callback: Updater<T>) => void;
 }
-
-export interface Stores {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  local: StoreDict<any>;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  session: StoreDict<any>;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  indexedDB: StoreDict<any>;
-}