RedGin Store

A Lightweight, Reactive, and Persistent State Management for Web Components.

RedGin Store is a surgically optimized Pub/Sub state manager designed specifically for the RedGin Library. It provides global reactivity with zero Virtual DOM overhead, built-in LocalStorage persistence, and automatic microtask batching.

---

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.

---

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

npm i redgin-store

Via CDN

<script type="module" src="https://cdn.jsdelivr.net/npm/redgin-store@latest/dist/redgin-store.min.js"></script>

Quick Start

1. Define your Store Create a singleton instance. Pass a storageKey as the second argument to enable persistence.

// store.ts
// store.ts
import { Store } from 'redgin-store';

const initialState = { 
  cart: [], 
  user: 'Guest' 
};

// 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
});

2. Connect to a RedGin Component Use onInit to subscribe and disconnectedCallback to clean up.

import { RedGin, watch, getset, html, on } from "redgin";
import { store } from "./store";

class ShoppingCart extends RedGin {
  global = getset(store.state);
  private _unsub?: () => void;

  onInit() {
    // Subscribe and save the cleanup function
    this._unsub = store.subscribe(newState => this.global = newState);
  }

  disconnectedCallback() {
    // CRITICAL: Unplug from store to prevent memory leaks
    if (this._unsub) this._unsub();
    super.disconnectedCallback();
  }

  render() {
    return html`
      <div>
        <h3>Items: ${watch(['global'], () => this.global.cart.length)}</h3>
        <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:

store.set('user', 'Admin', 'Auth_Service');
// Console: 🔴 RedGin Store: user by Auth_Service updated to: Admin

API Reference

new Store(initialState, storageKey?)

Parameter	Type	Description
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, label?)

Updates a specific top-level key in the state. Triggers a batched notification to all subscribers.

• 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)

Registers a listener. Returns an unsubscribe function

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:

store.set('user', 'Admin');
store.set('theme', 'dark');
store.set('cart', []);

The UI will only re-render once at the end of the execution block, preventing expensive layout thrashing.

Help

Need help? Open an issue in: ISSUES

Contributing

Want to improve and add feature? Fork the repo, add your changes and send a pull request.