Update to Node.js 22, docs, and add type improvements

- Bump Node.js version to 22 in .nvmrc and docs
- Improve README with clearer usage, dev, and API docs
- Refine JSDoc types and generics in WebStorage class
- Improve type safety and documentation throughout

Author: georapbox

.nvmrc

@@ -1 +1 @@
-20
+22

CHANGELOG.md

@@ -35,12 +35,18 @@
 - Removed support for error callback functions in all methods (`getItem`, `setItem`, `removeItem`, `clear`, `keys`, `length`, `iterate`). Errors must now be handled via the returned tuple.
 - Internal `_keyPrefix` and `_driver` fields are now private class fields (`#keyPrefix`, `#driver`). They are no longer accessible outside the class.
 
+## NEW FEATURES
+
+- Export type declaration files (`.d.ts`) for TypeScript users, ensuring better type safety and autocompletion support in TypeScript projects.
+
 ### INTERNAL CHANGES
 
 - Rewrite to use native class private fields.
 - Internal noopStorage fallback now fully conforms to the Storage interface.
 - Drop Jest in favor of @web/test-runner and Playwright for testing.
 - Drop rollup in favor of esbuild for bundling.
+- Update Node.js version requirement to 22.x.x.
+- Update dependencies to their latest versions.
 
 ## v2.1.0 (2021-01-26)
 

README.md

@@ -7,11 +7,11 @@
 
 # WebStorage
 
-WebStorage is a lightweight JavaScript library that improves how you work with `localStorage` or `sessionStorage` by providing a clean, consistent API. It supports storing and retrieving any serializable value (not just strings) by automatically handling JSON encoding and decoding internally.
+`WebStorage` is a lightweight JavaScript library that improves how you work with `localStorage` or `sessionStorage` by providing a clean, consistent API. It supports storing and retrieving any serializable value (not just strings) by automatically handling JSON encoding and decoding internally.
 
-A key feature of WebStorage is its use of namespacing via a configurable key prefix (default: `'web-storage/'`). This ensures that all stored items are scoped to your application, preventing collisions with other data in storage. For example, using a prefix like `'my-app/'` means calling clear() will only remove items with that prefix—leaving unrelated data untouched.
+A key feature of `WebStorage` is its use of namespacing via a configurable key prefix (default: `'web-storage/'`). This ensures that all stored items are scoped to your application, preventing collisions with other data in storage. For example, using a prefix like `'my-app/'` means calling clear() will only remove items with that prefix—leaving unrelated data untouched.
 
-WebStorage is also designed with error handling in mind. Instead of throwing exceptions, all methods return a `[result, error]` tuple-style value allowing you to handle errors gracefully—or ignore them entirely—without needing `try...catch`.
+`WebStorage` is also designed with error handling in mind. Instead of throwing exceptions, all methods return a `[result, error]` tuple-style value allowing you to handle errors gracefully—or ignore them entirely—without needing `try...catch`.
 
 ## Install
 
@@ -33,7 +33,7 @@ import { WebStorage } from '@georapbox/web-storage';
 
 ### new WebStorage(options = {})
 
-Creates a new instance of the WebStorage with the specified options. The following options can be set:
+Creates a new instance of the `WebStorage` with the specified options. The following options can be set:
 
 | Option | Type | Default | Description |
 | ------ | ---- | ------- | ----------- |
@@ -53,7 +53,7 @@ const myStore = new WebStorage({
 
 ### WebStorage.createInstance(options = {})
 
-Same as the constructor, but returns a new instance of `WebStorage`. This is a convenience method to create an instance without using the `new` keyword.
+Creates and returns a new `WebStorage` instance, just like the constructor. This convenience method allows you to instantiate without using the `new` keyword.
 
 **Example**
 
@@ -108,7 +108,7 @@ const [saved, error] = myStore.setItem('somekey', { foo: 'bar' });
 
 #### Note on value serialization
 
-WebStorage uses `JSON.stringify()` internally to serialize values before saving them. While this supports most common JavaScript types, some special values are silently converted:
+`WebStorage` uses `JSON.stringify()` internally to serialize values before saving them. While this supports most common JavaScript types, some special values are silently converted:
 
 - `NaN`, `Infinity`, `-Infinity`, and `undefined` → become null
 - Functions and symbols → are omitted or stored as `null/undefined`
@@ -202,6 +202,9 @@ const [len, error] = myStore.length();
 
 Iterates over all saved items in storage for a specific datastore and execute a callback function for each key-value pair.
 
+> [!IMPORTANT]
+> `iterate` does not guarantee the order of iteration. The order may vary depending on the browser implementation and storage driver used.
+
 **Throws:** `TypeError` - Throws if `callback` is not a function.  
 **Returns:** `[boolean, Error | null]` - Returns an array with two elements: the first is `true` if the iteration was successful, or `false` if it was not, and the second is `null` if no error occurred, or an `Error` object if an error occurred.
 
@@ -219,34 +222,63 @@ const [iterated, error] = myStore.iterate((value, key) => {
 
 ## Development
 
+Below are the instructions for setting up the development environment.
+
+### Prerequisites
+
+- Node.js (v22.x.x)
+- npm (v10.x.x)
+
+### Installation
+
+Clone the repository and install the dependencies:
+
+```sh
+$ git clone [email protected]:georapbox/web-storage.git
+$ cd web-storage
+$ npm install
+```
+
 ### Build for development
 
+Build the library for development and watch for any changes to the source files:
+
 ```sh
 $ npm run dev
 ```
 
-Builds the library for development and watches for any changes.
-
 ### Build for production
 
+Build the library for production. This will create a minified version of the library in the `dist` directory.
+
 ```sh
 $ npm run build
 ```
 
-Builds the library for production; the output is minified and optimized for production use in the `dist` folder.
-
 ### Test
 
+Run the tests to ensure everything is working correctly:
+
 ```sh
 $ npm test
 ```
 
-Runs the library tests. For coverage report, run:
+### Test with coverage
+
+Generate a test coverage report. This will run the tests and generate a coverage report in the `coverage` directory.
 
 ```sh
 $ npm run test:coverage
 ```
 
+### Linting
+
+Run the linter to check for any code style issues:
+
+```sh
+$ npm run lint
+```
+
 ## Changelog
 
 For API updates and breaking changes, check the [CHANGELOG][changelog].

src/web-storage.js

@@ -18,7 +18,7 @@
  * A tuple representing either a successful value or an error.
  *
  * @template T
- * @typedef {[T, Error | null]} Result
+ * @typedef {[T | null, Error | null]} Result<T>
  */
 
 const DEFAULT_DRIVER = 'localStorage';
@@ -97,11 +97,43 @@ class WebStorage {
     this.#keyPrefix = opts.keyPrefix.trim();
   }
 
+  /**
+   * Checks if `storageType` is supported and is available.
+   * Storage might be unavailable due to no browser support or due to being full or due to browser privacy settings.
+   *
+   * @param {WebStorageType} storageType - The storage type; available values "localStorage" or "sessionStorage".
+   * @returns {boolean} - Returns `true` if `storage` available; otherwise `false`.
+   */
+  static isAvailable(storageType) {
+    try {
+      const storage = window[storageType];
+      const testKey = STORAGE_TEST_KEY;
+
+      storage.setItem(testKey, 'test');
+      storage.getItem(testKey);
+      storage.removeItem(testKey);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Creates a new instance of WebStorage with the provided options.
+   *
+   * @param {WebStorageOptions} [options] - The options to configure the WebStorage instance.
+   * @returns {WebStorage} - Returns a new instance of WebStorage.
+   */
+  static createInstance(options) {
+    return new WebStorage(options);
+  }
+
   /**
    * Saves an item to storage with the specified key.
    *
+   * @template T
    * @param {string} key - The key under which to store the item.
-   * @param {any} value - The item to save to the selected storage.
+   * @param {T} value - The item to save to the selected storage.
    * @throws {TypeError} - Throws if `key` is not a string.
    * @returns {Result<boolean>} - Returns an array with two elements: the first is `true` if the item was saved successfully, or `false` if it was not, and the second is `null` if no error occurred, or an `Error` object if an error occurred.
    */
@@ -123,9 +155,10 @@ class WebStorage {
   /**
    * Gets the saved item for the specified key from the storage for a specific datastore.
    *
+   * @template T
    * @param {string} key - The key of the item to retrieve.
    * @throws {TypeError} - Throws if `key` is not a string.
-   * @returns {Result<unknown>} - Returns an array with two elements: the first is the value of the saved item, and the second is `null` if no error occurred, or an `Error` object if an error occurred.
+   * @returns {Result<T>} - Returns an array with two elements: the first is the value of the saved item, and the second is `null` if no error occurred, or an `Error` object if an error occurred.
    */
   getItem(key) {
     if (typeof key !== 'string') {
@@ -134,7 +167,7 @@ class WebStorage {
 
     try {
       const raw = this.#driver.getItem(this.#keyPrefix + key);
-      return raw === null ? [null, null] : [JSON.parse(raw), null];
+      return raw === null ? [null, null] : [/** @type {T} */ (JSON.parse(raw)), null];
     } catch (error) {
       return [null, error instanceof Error ? error : new Error(String(error))];
     }
@@ -188,6 +221,7 @@ class WebStorage {
         const unprefixedKey = removePrefix(key, this.#keyPrefix);
         result.push(unprefixedKey);
       });
+
       return [result, null];
     } catch (error) {
       return [[], error instanceof Error ? error : new Error(String(error))];
@@ -201,13 +235,19 @@ class WebStorage {
    */
   length() {
     const [keys, err] = this.keys();
-    return err ? [0, err] : [keys.length, null];
+
+    if (!Array.isArray(keys) || err) {
+      return [0, err];
+    }
+
+    return [keys.length, null];
   }
 
   /**
    * Iterates over all saved items in storage for a specific datastore and execute a callback function for each key-value pair.
    *
-   * @param {(value: any, key: string) => void} iteratorCallback - The callback function to execute for each key-value pair.
+   * @template T
+   * @param {(value: T, key: string) => void} iteratorCallback - The callback function to execute for each key-value pair.
    * @throws {TypeError} - Throws if `iteratorCallback` is not a function.
    * @returns {Result<boolean>} - Returns an array with two elements: the first is `true` if the iteration was successful, or `false` if it was not, and the second is `null` if no error occurred, or an `Error` object if an error occurred.
    */
@@ -219,9 +259,10 @@ class WebStorage {
     try {
       this.#iterateStorage((key, value) => {
         const unprefixedKey = removePrefix(key, this.#keyPrefix);
-        const parsedValue = JSON.parse(value);
-        iteratorCallback.call(this, parsedValue, unprefixedKey);
+        const parsedValue = /** @type {T} */ (value === null ? null : JSON.parse(value));
+        iteratorCallback(parsedValue, unprefixedKey);
       });
+
       return [true, null];
     } catch (error) {
       return [false, error instanceof Error ? error : new Error(String(error))];
@@ -231,7 +272,7 @@ class WebStorage {
   /**
    * Iterates over all keys in the storage and executes a callback function for each key-value pair.
    *
-   * @param {(key: string, value: any) => void} callback - The callback function to execute for each key-value pair.
+   * @param {(key: string, value: string | null) => void} callback - The callback function to execute for each key-value pair.
    */
   #iterateStorage(callback) {
     const keys = Object.keys(this.#driver);
@@ -244,37 +285,6 @@ class WebStorage {
       }
     }
   }
-
-  /**
-   * Checks if `storageType` is supported and is available.
-   * Storage might be unavailable due to no browser support or due to being full or due to browser privacy settings.
-   *
-   * @param {WebStorageType} storageType - The storage type; available values "localStorage" or "sessionStorage".
-   * @returns {boolean} - Returns `true` if `storage` available; otherwise `false`.
-   */
-  static isAvailable(storageType) {
-    try {
-      const storage = window[storageType];
-      const testKey = STORAGE_TEST_KEY;
-
-      storage.setItem(testKey, 'test');
-      storage.getItem(testKey);
-      storage.removeItem(testKey);
-      return true;
-    } catch {
-      return false;
-    }
-  }
-
-  /**
-   * Creates a new instance of WebStorage with the provided options.
-   *
-   * @param {WebStorageOptions} [options] - The options to configure the WebStorage instance.
-   * @returns {WebStorage} - Returns a new instance of WebStorage.
-   */
-  static createInstance(options) {
-    return new WebStorage(options);
-  }
 }
 
 export { WebStorage };