json-storage-formatter 3.0.0 → 3.0.1

package/README.md

@@ -1,131 +1,260 @@
-# json-storage-formatter
+const README = `
 
-Package for json stringify objects without losing data types. The transformation of the data includes extra metadata into the resulted string which later on is used to restored all the data structures to the their origninal forms.
+# json-storage-formatter 🌟
 
-The library suppors Sets, Maps, Objects, Arrays, and Primitive data like Dates
+![Image John Avatar](https://raw.githubusercontent.com/johnny-quesada-developer/global-hooks-example/main/public/avatar2.jpeg)
 
-# API
+A **lightweight solution** to store complex JavaScript values as JSON — **without losing their types**. 🚀
 
-The main methods of the library are **formatToStore** and **formatFromStore**
+---
 
-## formatToStore
+## 🤔 The Problem
 
-Format an object to be stored as JSON
+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`.
 
-```TS
-const objectWithMetadata = formatToStore(object);
+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.
+
+Let’s see an example.
+
+---
+
+### 🔍 Example: Losing Real Data
+
+```ts
+const userProfile = {
+  id: 42,
+  createdAt: new Date('2024-10-01T10:30:00Z'),
+  preferences: new Map([
+    ['theme', 'dark'],
+    ['languages', new Set(['en', 'es'])],
+  ]),
+};
+
+console.log(JSON.stringify(userProfile, null, 2));
+```
 
-// The result can be JSON.stringify
-console.log(objectWithMetadata);
-/*
+**Console Output:**
+
+```json
 {
-    $t: 'map',
-    $v: [
-        [
-        'key1',
-        {
-            $t: 'date',
-            $v: '2021-05-08T13:30:00.000Z',
-        },
-        ],
-        [
-        'key2',
-        {
-            $t: 'set',
-            $v: [
-            {
-                $t: 'map',
-                $v: [
-                [
-                    'key1',
-                    {
-                    $t: 'date',
-                    $v: '2021-05-08T13:30:00.000Z',
-                    },
-                ],
-                ],
-            },
-            ],
-        },
-        ],
-    ],
+  "id": 42,
+  "createdAt": "2024-10-01T10:30:00.000Z",
+  "preferences": {}
 }
-*/
+```
+
+What happened?
 
-// you can also stringify directly the result by specifying it on the configuration parameter
-const objectString = formatToStore(object, { stringify: true });
+- The **Date** turned into a string.
+- The **Map** disappeared.
+- The **Set** vanished inside the Map.
 
-console.log(objectString); // {"$t":"map","$v":[["key1",{"$t":"date","$v":"2021-05-08T13:30:00.000Z"}],["key2",{"$t":"set","$v":[{"$t":"map","$v":[["key1",{"$t":"date","$v":"2021-05-08T13:30:00.000Z"}]]}]}]]}
+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
 ```
 
-## formatFromStore<T>
+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.
 
-Format a value with possible metadata to his original form, it also supports Map, Set, Arrays
+---
 
-```TS
-const object = formatFromStore<Map<string, unknown>>(objectWithMetadata);
+## 💡 What json-storage-formatter Does
 
-// Original types of the object with metadata
-console.log(object);
+Exposes **two simple functions**:
 
-/*
-// the result will be the same than executing the following code
-const formatFromStoreResultExample = new Map([
-    ['key1', new Date('2021-05-08T13:30:00.000Z')],
-    [
-        'key2',
-        new Set([new Map([['key1', new Date('2021-05-08T13:30:00.000Z')]])]),
-    ],
-]);
-    */
-```
+1. `formatToStore(value)` → safely prepares your data for storage returning the JSON string representation.
+2. `formatFromStore(value)` → restores it to the **exact original shape and types**.
+
+As simple as that.
 
-## clone
+# Let’s see it a couple of examples
 
-Deep clone an object, it also suppors Map, Set, Arrays.
-The formatters clones the objects to avoid modify the parameter reference
+---
+
+## ⚙️ Example: useDashboardConfig hook
+
+Let’s create a hook that sync localStorage with react state:
 
 ```ts
-const clone: <T>(obj: T) => T;
+import { formatToStore, formatFromStore } from 'json-storage-formatter';
+
+type DashboardConfig = {
+  theme: 'light' | 'dark' | 'system';
+  widgets: Map<string, WidgetConfig>;
+  hiddenWidgets: Set<string>;
+  lastCustomizedAt: Date;
+};
+
+const useDashboardConfig = () => {
+  const [config, setConfig] = useState<DashboardConfig>(() => {
+    const json = localStorage.getItem('dashboard-config');
+
+    if (json) return formatFromStore<DashboardConfig>(json);
+
+    return getDefaultDashboardConfig();
+  });
+
+  const saveConfig = (newConfig: DashboardConfig) => {
+    localStorage.setItem('dashboard-config', formatToStore(newConfig));
+
+    setConfig(newConfig);
+  };
+
+  return { config, saveConfig };
+};
+
+// Even if the config contains Maps, Sets, or Dates, they will be preserved.
+const example: DashboardConfig = {
+  theme: 'dark',
+  widgets: new Map([
+    ['weather', { location: 'New York', units: 'metric' }],
+    ['stocks', { symbols: ['AAPL', 'GOOGL'] }],
+  ]),
+  hiddenWidgets: new Set(['news']),
+  lastCustomizedAt: new Date(),
+};
 ```
 
-## isNil
+---
 
-Check if a value is null or undefined
+## 🌐 Example: Sync dashboard queries through URL (Dashboards / Reports)
 
-```ts
-const isNil: (value: unknown) => boolean;
+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.
+
+```tsx
+import { formatToStore, formatFromStore } from 'json-storage-formatter';
+
+type DashboardQuery = {
+  dateRange: { from: Date; to: Date };
+  selectedCategories: Set<string>;
+  additionalSettings: Map<string, unknown>;
+};
+
+const useUrlQuery = () => {
+  const [query, setQuery] = useState<DashboardQuery>(() => {
+    const params = new URLSearchParams(location.search);
+    const storedQuery = params.get('query');
+
+    if (storedQuery) {
+      // decode from base64 and restore types
+      return formatFromStore<DashboardQuery>(atob(storedQuery));
+    }
+
+    return getDefaultDashboardQuery();
+  });
+
+  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}`);
+
+    setQuery(newQuery);
+  };
+
+  return { query, updateQuery };
+};
 ```
 
-## isNumber
+The examples above are in react but the library is framework-agnostic and can be used anywhere in JavaScript or TypeScript projects.
 
-Check if a value is a number
+## 🧩 Why It’s Useful
 
-```ts
-const isNumber: (value: unknown) => boolean;
+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**.
+
+Instead of being limited by what JSON can handle,
+you can now serialize **any structure** — Maps, Sets, nested objects, or Dates —
+and restore it back without losing context or meaning.
+
+---
+
+## 🧠 How It Works
+
+Under the hood, `formatToStore` adds small metadata markers to every special value.  
+Each piece of data gets a structure like this:
+
+```json
+{
+  "$t": "map",
+  "$v": [["key", { "$t": "date", "$v": "2024-10-01T10:30:00.000Z" }]]
+}
 ```
 
-## isBoolean
+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.
 
-Check if a value is a boolean
+Resulting on:
 
 ```ts
-const isBoolean: (value: unknown) => boolean;
+new Map([['key', new Date('2024-10-01T10:30:00.000Z')]]);
 ```
 
-## isString
+---
+
+## ⚙️ API Reference
 
-Check if a value is a string
+### 🟣 formatToStore
+
+Converts any value into a JSON-safe structure with internal type metadata.
 
 ```ts
-const isString: (value: unknown) => boolean;
+const objectWithMetadata = formatToStore(object);
 ```
 
-## isDate
+### 🔵 formatFromStore<T>
 
-Check if a value is a Date
+Restores the serialized object back to its original types.
 
 ```ts
-const isDate: (value: unknown) => boolean;
+const result = formatFromStore<Map<string, unknown>>(objectWithMetadata);
+```
+
+---
+
+## 🧰 Utility Functions
+
+| Function      | Description                              | Example                       |
+| ------------- | ---------------------------------------- | ----------------------------- |
+| **isNil**     | Checks if value is `null` or `undefined` | `isNil(null); // true`        |
+| **isNumber**  | Checks if value is a number              | `isNumber(42); // true`       |
+| **isBoolean** | Checks if value is a boolean             | `isBoolean(false); // true`   |
+| **isString**  | Checks if value is a string              | `isString('hi'); // true`     |
+| **isDate**    | Checks if value is a Date                | `isDate(new Date()); // true` |
+
+---
+
+## ⚖️ 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    |
+
+---
+
+## 📦 Installation
+
+```bash
+npm install 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. ✨

package/package.json

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