json-storage-formatter 3.0.1 → 3.0.2

package/README.md

@@ -1,26 +1,10 @@
-const README = `
-
 # json-storage-formatter 🌟
 
 ![Image John Avatar](https://raw.githubusercontent.com/johnny-quesada-developer/global-hooks-example/main/public/avatar2.jpeg)
 
-A **lightweight solution** to store complex JavaScript values as JSON — **without losing their types**. 🚀
-
----
-
-## 🤔 The Problem
-
-When working with tools like **localStorage**, **sessionStorage**, **AsyncStorage**, or even databases like **Redis** or **PostgreSQL (JSON columns)**,  
-we often need to store application state or configuration objects as strings using `JSON.stringify`.
-
-But there’s a catch:  
-`JSON.stringify` has no idea what to do with values like `Date`, `Map`, or `Set`... It just flattens them into empty objects or strings, and when you parse them back with `JSON.parse`, it’s too late.
+A **lightweight solution** to format complex JavaScript objects for string-based storage systems **without losing their types**. 🚀
 
-Let’s see an example.
-
----
-
-### 🔍 Example: Losing Real Data
+## 🤔 The Problem?
 
 ```ts
 const userProfile = {
@@ -45,24 +29,12 @@ console.log(JSON.stringify(userProfile, null, 2));
 }
 ```
 
-What happened?
+When working with tools like **localStorage**, **sessionStorage**, **AsyncStorage**, or even databases like **Redis** or **PostgreSQL (JSON columns)**, we often need to store application state or configuration objects as strings using `JSON.stringify`.
 
-- The **Date** turned into a string.
-- The **Map** disappeared.
-- The **Set** vanished inside the Map.
+_But there’s a catch!:_
 
-If we try to restore it:
-
-```ts
-const parsed = JSON.parse(JSON.stringify(userProfile));
-console.log(parsed.createdAt instanceof Date); // ❌ false
-console.log(parsed.preferences instanceof Map); // ❌ false
-```
-
-When serializing JavaScript objects, we lose important value types —  
-Dates, Sets, Maps, RegExps, and even nested structures.  
-This forces us to write endless **custom parsers and validators** to recover data  
-that could have been automatically restored.
+`JSON.stringify` has no idea what to do with values like `Date`, `Map`, or `Set`...  
+It just flattens them into empty objects or strings, making you lose the original data types or the entire structure.
 
 ---
 
@@ -70,18 +42,18 @@ that could have been automatically restored.
 
 Exposes **two simple functions**:
 
-1. `formatToStore(value)` → safely prepares your data for storage returning the JSON string representation.
+1. `formatToStore(value)` → safely prepares your data for storage, returning a JSON string representation.
 2. `formatFromStore(value)` → restores it to the **exact original shape and types**.
 
 As simple as that.
 
-# Let’s see it a couple of examples
+# Let’s see a couple of examples
 
 ---
 
-## ⚙️ Example: useDashboardConfig hook
+## ⚙️ Example: useDashboardConfig Hook
 
-Let’s create a hook that sync localStorage with react state:
+Let’s create a hook that syncs `localStorage` with React state:
 
 ```ts
 import { formatToStore, formatFromStore } from 'json-storage-formatter';
@@ -104,7 +76,6 @@ const useDashboardConfig = () => {
 
   const saveConfig = (newConfig: DashboardConfig) => {
     localStorage.setItem('dashboard-config', formatToStore(newConfig));
-
     setConfig(newConfig);
   };
 
@@ -125,7 +96,7 @@ const example: DashboardConfig = {
 
 ---
 
-## 🌐 Example: Sync dashboard queries through URL (Dashboards / Reports)
+## 🌐 Example: Sync Dashboard Queries Through URL (Dashboards / Reports)
 
 This pattern is common in dashboards, where filters are shared via URL.  
 You can safely serialize complex filters (with Dates, Sets, Maps, etc.) and encode them for sharing.
@@ -155,8 +126,9 @@ const useUrlQuery = () => {
   const updateQuery = (newQuery: DashboardQuery) => {
     const encoded = btoa(formatToStore(newQuery));
 
-    // encode the json as base64 to make it URL-safe
-    window.history.replaceState(null, '', `${location.pathname}?query=${encoded}`);
+    // encode the JSON as base64 to make it URL-safe
+    // avoids breaking query strings with +, /, or = characters
+    window.history.replaceState(null, '', `\${location.pathname}?query=\${encoded}`);
 
     setQuery(newQuery);
   };
@@ -165,12 +137,15 @@ const useUrlQuery = () => {
 };
 ```
 
-The examples above are in react but the library is framework-agnostic and can be used anywhere in JavaScript or TypeScript projects.
+The examples above use React, but the library itself is **framework-agnostic**  
+and can be used anywhere in JavaScript or TypeScript projects.
+
+---
 
 ## 🧩 Why It’s Useful
 
 This becomes incredibly powerful when your app needs to **sync complex state**
-to a string-based storage layer — like when syncing to **localStorage**, **Redis**, or **a shared dashboard URL**.
+to a string-based storage layer — like when syncing to **localStorage**, **Redis**, or a **shared dashboard URL**.
 
 Instead of being limited by what JSON can handle,
 you can now serialize **any structure** — Maps, Sets, nested objects, or Dates —
@@ -194,7 +169,7 @@ The `$t` field stores the **type**, and `$v` holds the actual value.
 When using `formatFromStore`, it reads that metadata and recreates your data structure  
 exactly as it was before — even if it’s deeply nested.
 
-Resulting on:
+Resulting in:
 
 ```ts
 new Map([['key', new Date('2024-10-01T10:30:00.000Z')]]);
@@ -220,6 +195,9 @@ Restores the serialized object back to its original types.
 const result = formatFromStore<Map<string, unknown>>(objectWithMetadata);
 ```
 
+Both functions work directly with strings,  
+so you can safely use them with localStorage, AsyncStorage, or URLs.
+
 ---
 
 ## 🧰 Utility Functions
@@ -236,13 +214,14 @@ const result = formatFromStore<Map<string, unknown>>(objectWithMetadata);
 
 ## ⚖️ Comparison
 
-| Behavior         | JSON.stringify  | json-storage-formatter |
-| ---------------- | --------------- | ---------------------- |
-| **Date**         | Becomes string  | ✅ Restored as Date    |
-| **Set**          | Lost completely | ✅ Restored as Set     |
-| **Map**          | Lost completely | ✅ Restored as Map     |
-| **Nested types** | Broken          | ✅ Preserved           |
-| **Performance**  | Fast            | ⚡ Nearly identical    |
+| Behavior      | JSON.stringify  | json-storage-formatter   |
+| ------------- | --------------- | ------------------------ |
+| **Date**      | Becomes string  | ✅ Restored as Date      |
+| **Set**       | Lost completely | ✅ Restored as Set       |
+| **Map**       | Lost completely | ✅ Restored as Map       |
+| **Undefined** | Omitted         | ✅ Restored as undefined |
+| **Regexp**    | Lost completely | ✅ Restored as RegExp    |
+| **Error**     | Lost completely | ✅ Restored as Error     |
 
 ---
 
@@ -252,9 +231,15 @@ const result = formatFromStore<Map<string, unknown>>(objectWithMetadata);
 npm install json-storage-formatter
 ```
 
+or
+
+```bash
+yarn add json-storage-formatter
+```
+
 ---
 
 ## 🎯 Ready to Try It?
 
 📘 **NPM:** [json-storage-formatter](https://www.npmjs.com/package/json-storage-formatter)  
-Serialize, store, and restore **any JavaScript data type** without losing its identity — lightweight, fast, and fully type-safe. ✨
+Serialize, store, and restore **any JavaScript data type** without losing its identity — lightweight, fast. ✨

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "json-storage-formatter",
-  "version": "3.0.1",
+  "version": "3.0.2",
   "description": "Package for json stringify objects without losing data types",
   "main": "./bundle.js",
   "types": "./index.d.ts",