Update documentation, adding note for value serialization

Author: georapbox

CHANGELOG.md

@@ -5,17 +5,18 @@
 ### BREAKING CHANGES
 
 - The `WebStorage` module is now exclusively available as an ES module (ESM), aligning with the modern JavaScript module standard. Additionally, it is no longer the default export — you must import it using a named import.  
-**v2.x.x**
-```js
-import WebStorage from '@georapbox/web-storage';
-```
-
-**v3.x.x**
-```js
-import { WebStorage } from '@georapbox/web-storage';
-```
+  **v2.x.x**
+  ```js
+  import WebStorage from '@georapbox/web-storage';
+  ```
+  
+  **v3.x.x**
+  ```js
+  import { WebStorage } from '@georapbox/web-storage';
+  ```
 - All API methods now return `[value, error]` tuple-like values instead of accepting error callbacks.
-  This allows developers to handle errors in a clean, synchronous style without using `try/catch` or providing callbacks. For example:  
+  This allows developers to handle errors in a clean, synchronous style without using `try/catch` or providing callbacks. For example:
+  
   **v2.x.x**
   ```js
   const value = storage.getItem('key', value, (err) => {

README.md

@@ -83,44 +83,66 @@ WebStorage.isAvailable('localStorage');
 
 ## Instance methods
 
-### getItem(key)
+### setItem(key, value)
 
-Gets the saved item for the specified key from the storage for a specific datastore.
+Saves an item to storage with the specified key. You can store items of any of the following data types as long as data can be serialized to JSON.
+
+- String
+- Number
+- Array
+- Object
 
 **Throws:** `TypeError` - Throws if `key` is not a string.  
-**Returns:** `[any, Error | null]` - 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:** `[boolean, Error | null]` - 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.
 
 | Param | Type | Default | Description |
 | ----- | ---- | ------- | ----------- |
-| key | `string` | - | The key of the item to retrieve. |
+| key | `string` | - | The key under which to store the item. |
+| value | `any` | - | The item to save to the selected storage. |
 
 **Usage**
 
 ```js
-const [value, error] = myStore.getItem('somekey');
+const [saved, error] = myStore.setItem('somekey', { foo: 'bar' });
 ```
 
-### setItem(key, value)
+#### Note on value serialization
 
-Saves an item to storage with the specified key. You can store items of any of the following data types as long as data can be serialized to JSON.
+WebStorage uses `JSON.stringify()` internally to serialize values before saving them. While this supports most common JavaScript types, some special values are silently converted:
 
-- String
-- Number
-- Array
-- Object
+- `NaN`, `Infinity`, `-Infinity`, and `undefined` → become null
+- Functions and symbols → are omitted or stored as `null/undefined`
+- Circular references → will throw a `TypeError`
+
+For example:
+
+```js
+storage.setItem('foo', NaN);
+// Will be stored as: "null"
+
+storage.getItem('foo');
+// => [null, null]
+```
+
+**Why this matters:**
+
+If you store special or non-JSON-safe values, they may not round-trip exactly as expected. This is a deliberate design decision to keep the API simple and compatible with `Storage` constraints. If needed, consider manually encoding such values before storing them.
+
+### getItem(key)
+
+Gets the saved item for the specified key from the storage for a specific datastore.
 
 **Throws:** `TypeError` - Throws if `key` is not a string.  
-**Returns:** `[boolean, Error | null]` - 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.
+**Returns:** `[any, Error | null]` - 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.
 
 | Param | Type | Default | Description |
 | ----- | ---- | ------- | ----------- |
-| key | `string` | - | The key under which to store the item. |
-| value | `any` | - | The item to save to the selected storage. |
+| key | `string` | - | The key of the item to retrieve. |
 
 **Usage**
 
 ```js
-const [saved, error] = myStore.setItem('somekey', { foo: 'bar' });
+const [value, error] = myStore.getItem('somekey');
 ```
 
 ### removeItem(key)

src/web-storage.js

@@ -98,45 +98,45 @@ class WebStorage {
   }
 
   /**
-   * Gets the saved item for the specified key from the storage for a specific datastore.
+   * Saves an item to storage with the specified key.
    *
-   * @param {string} key - The key of the item to retrieve.
+   * @param {string} key - The key under which to store the item.
+   * @param {any} value - The item to save to the selected storage.
    * @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<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.
    */
-  getItem(key) {
+  setItem(key, value) {
     if (typeof key !== 'string') {
-      throw new TypeError("Failed to execute 'getItem' on 'Storage': The first argument must be a string.");
+      throw new TypeError("Failed to execute 'setItem' on 'Storage': The first argument must be a string.");
     }
 
     try {
-      const raw = this.#driver.getItem(this.#keyPrefix + key);
-      return raw === null ? [null, null] : [JSON.parse(raw), null];
+      const storageKey = this.#keyPrefix + key;
+      const safeValue = value == null || typeof value === 'function' ? null : value;
+      this.#driver.setItem(storageKey, JSON.stringify(safeValue));
+      return [true, null];
     } catch (error) {
-      return [null, error instanceof Error ? error : new Error(String(error))];
+      return [false, error instanceof Error ? error : new Error(String(error))];
     }
   }
 
   /**
-   * Saves an item to storage with the specified key.
+   * Gets the saved item for the specified key from the storage for a specific datastore.
    *
-   * @param {string} key - The key under which to store the item.
-   * @param {any} value - The item to save to the selected storage.
+   * @param {string} key - The key of the item to retrieve.
    * @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.
+   * @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.
    */
-  setItem(key, value) {
+  getItem(key) {
     if (typeof key !== 'string') {
-      throw new TypeError("Failed to execute 'setItem' on 'Storage': The first argument must be a string.");
+      throw new TypeError("Failed to execute 'getItem' on 'Storage': The first argument must be a string.");
     }
 
     try {
-      const storageKey = this.#keyPrefix + key;
-      const safeValue = value == null || typeof value === 'function' ? null : value;
-      this.#driver.setItem(storageKey, JSON.stringify(safeValue));
-      return [true, null];
+      const raw = this.#driver.getItem(this.#keyPrefix + key);
+      return raw === null ? [null, null] : [JSON.parse(raw), null];
     } catch (error) {
-      return [false, error instanceof Error ? error : new Error(String(error))];
+      return [null, error instanceof Error ? error : new Error(String(error))];
     }
   }
 

test/web-storage.test.js

@@ -75,6 +75,7 @@ describe('WebStorage', () => {
     store.setItem('p7', Infinity);
     store.setItem('p8', -Infinity);
     store.setItem('p9', -0);
+    store.setItem('p10', [{ foo: 'bar' }, 'foo', [1, 2, 3]]);
 
     expect(store.getItem('p1')).to.deep.equal([{ foo: 'bar' }, null]);
     expect(store.getItem('p2')).to.deep.equal([[1, 2, 3], null]);
@@ -85,6 +86,7 @@ describe('WebStorage', () => {
     expect(store.getItem('p7')).to.deep.equal([null, null]);
     expect(store.getItem('p8')).to.deep.equal([null, null]);
     expect(store.getItem('p9')).to.deep.equal([0, null]);
+    expect(store.getItem('p10')).to.deep.equal([[{ foo: 'bar' }, 'foo', [1, 2, 3]], null]);
   });
 
   it('Should remove a saved item by its key', () => {