json-storage-formatter 3.0.2 → 3.0.3

package/README.md

@@ -1,10 +1,22 @@
 # json-storage-formatter 🌟
 
-![Image John Avatar](https://raw.githubusercontent.com/johnny-quesada-developer/global-hooks-example/main/public/avatar2.jpeg)
+<div align="center">
+  <img src="https://raw.githubusercontent.com/johnny-quesada-developer/global-hooks-example/main/public/avatar2.jpeg" width="100" alt="John Avatar" />
+
+  <br />
+  <b>Type-safe serialization for any JavaScript object.<br />
+  Store and restore Maps, Sets, Dates, RegExps, Errors, and more.<br />
+  <br />
+  <i>One line. No data loss. No headaches.</i> 🚀</b>
+  <br /><br />
+  <a href="https://www.npmjs.com/package/json-storage-formatter"><img src="https://img.shields.io/npm/v/json-storage-formatter.svg" /></a>
+  <a href="https://www.npmjs.com/package/json-storage-formatter"><img src="https://img.shields.io/npm/dm/json-storage-formatter.svg" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/npm/l/json-storage-formatter.svg" /></a>
+</div>
 
-A **lightweight solution** to format complex JavaScript objects for string-based storage systems **without losing their types**. 🚀
+---
 
-## 🤔 The Problem?
+## 🎯 The Problem
 
 ```ts
 const userProfile = {
@@ -29,35 +41,127 @@ console.log(JSON.stringify(userProfile, null, 2));
 }
 ```
 
-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`.
+**JSON.stringify** loses all type information for Dates, Maps, Sets, RegExps, and more. Your data is flattened, and restoring it is impossible.
 
-_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, making you lose the original data types or the entire structure.
+<div align="center">
+<b>json-storage-formatter lets you serialize <i>any</i> JavaScript value for storage,<br />
+and restore it to its original type — <i>automatically</i>.</b>
+</div>
 
 ---
 
-## 💡 What json-storage-formatter Does
+## 🚀 Why Use This Library?
 
-Exposes **two simple functions**:
+## 🟢 Quick Start
 
-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**.
+### Instantly Store and Restore Complex Data
 
-As simple as that.
+```ts
+import { formatToStore, formatFromStore } from 'json-storage-formatter';
+
+// Imagine you want to save this to localStorage, a URL, or a DB:
+const userProfile = {
+  id: 42,
+  createdAt: new Date('2024-10-01T10:30:00Z'),
+  preferences: new Map([
+    ['theme', 'dark'],
+    ['languages', new Set(['en', 'es'])],
+  ]),
+};
+
+// Serialize for storage (preserves all types!)
+const stored = formatToStore(userProfile);
+localStorage.setItem('profile', stored);
+
+// ...later, or in another environment:
+const loaded = localStorage.getItem('profile');
+const restored = formatFromStore<typeof userProfile>(loaded);
+
+// restored.createdAt is a Date
+// restored.preferences is a Map with a Set inside
+```
+
+// Works for any structure: deeply nested, with Dates, Sets, Maps, RegExps, Errors, undefined, NaN, etc.
+
+---
+
+## 🟣 Complex Types Example
+
+```ts
+const complex = {
+  date: new Date('2024-10-01T10:30:00Z'),
+  set: new Set(['a', 'b']),
+  map: new Map([
+    ['x', 1],
+    ['y', 2],
+  ]),
+  regex: /abc/i,
+  error: new Error('fail'),
+  undef: undefined,
+  nan: NaN,
+  inf: Infinity,
+};
 
-# Let’s see a couple of examples
+const stored = formatToStore(complex);
+const restored = formatFromStore<typeof complex>(stored);
+// All types are preserved!
+```
 
 ---
 
-## ⚙️ Example: useDashboardConfig Hook
+### 🔒 Type-Safe Storage
 
-Let’s create a hook that syncs `localStorage` with React state:
+Store and restore Maps, Sets, Dates, RegExps, Errors, and more — not just plain objects.
 
 ```ts
 import { formatToStore, formatFromStore } from 'json-storage-formatter';
 
+const original = new Map([
+  ['created', new Date('2024-10-01T10:30:00Z')],
+  ['tags', new Set(['a', 'b'])],
+]);
+
+const json = formatToStore(original); // string for storage
+const restored = formatFromStore<Map<string, unknown>>(json);
+```
+
+### ⚡ No Boilerplate
+
+Just call `formatToStore` before saving, and `formatFromStore` when loading. No config, no setup, no custom revivers.
+
+```ts
+localStorage.setItem('profile', formatToStore(profile));
+const profile = formatFromStore(localStorage.getItem('profile'));
+```
+
+---
+
+## 🛠️ How It Works
+
+`formatToStore` adds a tiny type marker to every special value:
+
+```json
+{
+  "$t": "map",
+  "$v": [["key", { "$t": "date", "$v": "2024-10-01T10:30:00.000Z" }]]
+}
+```
+
+When you call `formatFromStore`, it reads those markers and reconstructs the original types — even deeply nested.
+
+---
+
+## ✨ Real-World Examples
+
+### 1️⃣ React: Syncing Complex State to localStorage
+
+```tsx
+import { useState } from 'react';
+import { formatToStore, formatFromStore } from 'json-storage-formatter';
+
+type WidgetConfig = { location: string; units: string };
 type DashboardConfig = {
   theme: 'light' | 'dark' | 'system';
   widgets: Map<string, WidgetConfig>;
@@ -65,13 +169,10 @@ type DashboardConfig = {
   lastCustomizedAt: Date;
 };
 
-const useDashboardConfig = () => {
+function useDashboardConfig() {
   const [config, setConfig] = useState<DashboardConfig>(() => {
     const json = localStorage.getItem('dashboard-config');
-
-    if (json) return formatFromStore<DashboardConfig>(json);
-
-    return getDefaultDashboardConfig();
+    return json ? formatFromStore<DashboardConfig>(json) : getDefaultDashboardConfig();
   });
 
   const saveConfig = (newConfig: DashboardConfig) => {
@@ -80,14 +181,14 @@ const useDashboardConfig = () => {
   };
 
   return { config, saveConfig };
-};
+}
 
-// Even if the config contains Maps, Sets, or Dates, they will be preserved.
+// Usage
 const example: DashboardConfig = {
   theme: 'dark',
   widgets: new Map([
     ['weather', { location: 'New York', units: 'metric' }],
-    ['stocks', { symbols: ['AAPL', 'GOOGL'] }],
+    ['stocks', { location: 'NASDAQ', units: 'USD' }],
   ]),
   hiddenWidgets: new Set(['news']),
   lastCustomizedAt: new Date(),
@@ -96,12 +197,10 @@ const example: DashboardConfig = {
 
 ---
 
-## 🌐 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.
+### 2️⃣ React: Syncing Filters via URL (Shareable Dashboard Queries)
 
 ```tsx
+import { useState } from 'react';
 import { formatToStore, formatFromStore } from 'json-storage-formatter';
 
 type DashboardQuery = {
@@ -110,93 +209,60 @@ type DashboardQuery = {
   additionalSettings: Map<string, unknown>;
 };
 
-const useUrlQuery = () => {
+function useUrlQuery() {
   const [query, setQuery] = useState<DashboardQuery>(() => {
-    const params = new URLSearchParams(location.search);
+    const params = new URLSearchParams(window.location.search);
     const storedQuery = params.get('query');
-
-    if (storedQuery) {
-      // decode from base64 and restore types
-      return formatFromStore<DashboardQuery>(atob(storedQuery));
-    }
-
-    return getDefaultDashboardQuery();
+    return storedQuery ? formatFromStore<DashboardQuery>(atob(storedQuery)) : getDefaultDashboardQuery();
   });
 
   const updateQuery = (newQuery: DashboardQuery) => {
     const encoded = btoa(formatToStore(newQuery));
-
-    // 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}`);
-
+    window.history.replaceState(null, '', `${window.location.pathname}?query=${encoded}`);
     setQuery(newQuery);
   };
 
   return { query, updateQuery };
-};
+}
 ```
 
-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**.
-
-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:
+### 3️⃣ Framework-Agnostic: Node.js/Backend Example
 
-```json
-{
-  "$t": "map",
-  "$v": [["key", { "$t": "date", "$v": "2024-10-01T10:30:00.000Z" }]]
-}
-```
+```js
+// Save and load any structure in Redis, PostgreSQL, or files
+const { formatToStore, formatFromStore } = require('json-storage-formatter');
 
-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.
+const session = {
+  userId: 123,
+  expires: new Date(),
+  permissions: new Set(['read', 'write']),
+};
 
-Resulting in:
+// Store in Redis
+redis.set('session:123', formatToStore(session));
 
-```ts
-new Map([['key', new Date('2024-10-01T10:30:00.000Z')]]);
+// Later...
+const raw = await redis.get('session:123');
+const restored = formatFromStore(raw);
+// restored.expires is a Date, restored.permissions is a Set
 ```
 
 ---
 
-## ⚙️ API Reference
+## 🧩 Supported Types
 
-### 🟣 formatToStore
-
-Converts any value into a JSON-safe structure with internal type metadata.
-
-```ts
-const objectWithMetadata = formatToStore(object);
-```
-
-### 🔵 formatFromStore<T>
-
-Restores the serialized object back to its original types.
-
-```ts
-const result = formatFromStore<Map<string, unknown>>(objectWithMetadata);
-```
-
-Both functions work directly with strings,  
-so you can safely use them with localStorage, AsyncStorage, or URLs.
+| Type         | Supported? | Restored As     |
+| ------------ | ---------- | --------------- |
+| Date         | ✅         | Date            |
+| Set          | ✅         | Set             |
+| Map          | ✅         | Map             |
+| RegExp       | ✅         | RegExp          |
+| Error        | ✅         | Error           |
+| undefined    | ✅         | undefined       |
+| NaN/Infinity | ✅         | number          |
+| Function     | ❌         | (not supported) |
 
 ---
 
@@ -231,15 +297,35 @@ so you can safely use them with localStorage, AsyncStorage, or URLs.
 npm install json-storage-formatter
 ```
 
-or
-
 ```bash
 yarn add json-storage-formatter
 ```
 
 ---
 
-## 🎯 Ready to Try It?
+## 📝 API Reference
+
+### formatToStore(value)
+
+Converts any value into a JSON-safe string with type metadata.
+
+### formatFromStore<T>(string)
+
+Restores the serialized string back to its original types.
+
+---
+
+## 💡 Pro Tips
+
+- Use with any storage: localStorage, sessionStorage, AsyncStorage, Redis, PostgreSQL JSON columns, URLs, etc.
+- Works with deeply nested structures.
+- Framework-agnostic: use in React, Node.js, or vanilla JS/TS.
+
+---
 
-📘 **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. ✨
+<div align="center">
+<b>Serialize, store, and restore <i>any</i> JavaScript data type —<br />
+without losing its identity. Lightweight. Fast. Reliable.</b>
+<br /><br />
+<a href="https://www.npmjs.com/package/json-storage-formatter">⭐ Try it on NPM</a>
+</div>

package/package.json

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