redgin-store 0.1.2 → 0.1.4

package/README.md

@@ -1,25 +1,31 @@
 # RedGin Store
-A Lightweight, Reactive, and Persistent State Management for Web Components.
-RedGin Store is a surgically optimized Pub/Sub state manager designed to complement the [RedGin Library](https://www.npmjs.com/package/redgin). It provides global reactivity with zero Virtual DOM overhead, built-in LocalStorage persistence, and automatic batching.
 
+**A Lightweight, Reactive, and Persistent State Management for Web Components.**
 
-# The Pain Points
-Building complex Web Components usually leads to three major headaches:
-Prop Drilling: Passing data through five layers of nested components just to update a header.
-Zombie Listeners (Memory Leaks): Global event listeners that stay in RAM after a component is destroyed, leading to "ghost" updates and performance degradation.
-State Loss on Refresh: Disappearing shopping carts or user sessions because the state only lives in volatile memory.
-Redundant Re-renders: Most stores trigger a full UI update on every change. If you update the user, you shouldn't re-render the productList.
+RedGin Store is a surgically optimized Pub/Sub state manager designed specifically for the [RedGin Library](https://www.npmjs.com). It provides global reactivity with **zero Virtual DOM overhead**, built-in **LocalStorage persistence**, and **automatic microtask batching**.
 
+---
 
-# Purpose & Features
-RedGin Store was built to provide Single Source of Truth that is:
-* 🚀 Surgically Reactive: Leverages queueMicrotask to batch multiple updates into a single tick.
-* 💾 Persistent by Design: Optional LocalStorage integration—hydrate your state automatically on page load.
-* 🛡️ Memory Safe: Implements the Auto-Unsubscribe Pattern to ensure components are garbage-collected when removed from the DOM.
-* ⚛️ Immutable & Type-Safe: Uses reference-based dirty checking to ensure high-performance updates.
-* 📦 Zero Dependencies: Extremely small footprint (~1kb).
+## The Pain Points
+Building complex Web Components usually leads to several major headaches:
+*   **Prop Drilling:** Passing data through five layers of nested components just to update a single value.
+*   **Zombie Listeners (Memory Leaks):** Global store listeners that stay in RAM after a component is destroyed, leading to "ghost" updates and performance degradation.
+*   **State Loss on Refresh:** Disappearing shopping carts or user sessions because the state only lives in volatile memory.
+*   **Redundant Re-renders:** Most stores trigger a full UI update on every change. If you update the `user`, you shouldn't re-render the `productList`.
 
-# Installation
+---
+
+## Purpose & Features
+RedGin Store provides a **Single Source of Truth** that is:
+*   🚀 **Surgically Reactive:** Leverages `queueMicrotask` to batch multiple updates into a single tick.
+*   💾 **Persistent by Design:** Optional LocalStorage integration—hydrate your state automatically on page load.
+*   🛡️ **Memory Safe:** Returns an **Unsubscribe function** to ensure components are garbage-collected when removed from the DOM.
+*   🔍 **Built-in Debugger:** Concise console logging that **auto-detects** which component triggered the update.
+*   📦 **Zero Dependencies:** Extremely small footprint (~1kb).
+
+---
+
+## Installation
 
 ### Via npm
 ```bash
@@ -39,16 +45,19 @@ Create a singleton instance. Pass a storageKey as the second argument to enable
 
 ```ts
 // store.ts
-import { Store } from './redgin-store';
+// store.ts
+import { Store } from 'redgin-store';
 
 const initialState = { 
   cart: [], 
-  user: 'Guest',
-  theme: 'light' 
+  user: 'Guest' 
 };
 
-// 'market_storage' is the key used in LocalStorage
-export const store = new Store(initialState, 'market_storage');
+// Second argument is the Options Object
+export const store = new Store(initialState, {
+  storageKey: 'my_market_app', // Syncs state to LocalStorage
+  debug: true                  // Enables component-trace logging
+});
 
 ```
 
@@ -57,7 +66,7 @@ export const store = new Store(initialState, 'market_storage');
 Use onInit to subscribe and disconnectedCallback to clean up.
 
 ```ts
-import { RedGin, watch, getset, html } from "redgin";
+import { RedGin, watch, getset, html, on } from "redgin";
 import { store } from "./store";
 
 class ShoppingCart extends RedGin {
@@ -65,7 +74,7 @@ class ShoppingCart extends RedGin {
   private _unsub?: () => void;
 
   onInit() {
-    // Subscribe and store the cleanup function
+    // Subscribe and save the cleanup function
     this._unsub = store.subscribe(newState => this.global = newState);
   }
 
@@ -75,24 +84,36 @@ class ShoppingCart extends RedGin {
     super.disconnectedCallback();
   }
 
-  addItem() {
-    const newItem = { id: Date.now(), name: 'New Item' };
-    // Update global state
-    store.set('cart', [...this.global.cart, newItem]);
-  }
-
   render() {
     return html`
       <div>
         <h3>Items: ${watch(['global'], () => this.global.cart.length)}</h3>
-        <button onclick="${() => this.addItem()}">Add Item</button>
+        <button ${on('click', () => store.set('cart', [...this.global.cart, { id: Date.now() }]))}>
+          Add Item
+        </button>
       </div>
     `;
   }
 }
 
+customElements.define('shopping-cart', ShoppingCart);
+
+```
+
+# Surgical Logging
+When debug: true is enabled, RedGin Store auto-detects the component instance using the RedGin Context Bridge. Your console will show exactly who triggered the change in a concise, one-line format:
+
+`🔴 RedGin Store: cart by <shopping-cart> updated to: [{id: 12345}]`
+
+For async actions or external scripts where context might be lost, you can provide a manual label:
+
+```ts
+store.set('user', 'Admin', 'Auth_Service');
+// Console: 🔴 RedGin Store: user by Auth_Service updated to: Admin
 ```
 
+
+
 ### API Reference
 `new Store(initialState, storageKey?)`
 
@@ -100,11 +121,15 @@ class ShoppingCart extends RedGin {
 | :--- | :--- | :--- |
 | `initialState` | Object | The starting data for your store. |
 | `storageKey` | string | (Optional) The key name for LocalStorage persistence |
+| `debug` | boolen | (Optional) Enables styled console logs with source tracking |
 
-`store.set(key, value)`
+`store.set(key, value, label?)`
 
 Updates a specific top-level key in the state. Triggers a batched notification to all subscribers.
-* Note: Use immutable patterns (spread operator) for arrays and objects to ensure reactivity.
+
+* key: The property name in your state.
+* value: The new value (must use immutable patterns like [...arr] for reactivity).
+* label: (Optional) A string to identify the source in logs
 
 `store.subscribe(callback)`
 
@@ -115,6 +140,10 @@ const unsub = store.subscribe(state => console.log(state));
 unsub(); // Stop listening
 ```
 
+`store.clear()`
+Wipes the LocalStorage data and reloads the page to reset the application state.
+
+
 # Performance Tip: Batching
 RedGin Store uses Microtask Batching. If you execute:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "redgin-store",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "type": "module",
   "main": "./dist/redgin-store.min.js",
   "module": "./dist/redgin-store.min.js",