The Reactive Core: $( )

The $ function is the heart of SigPro. It is a Unified Reactive Constructor that handles state, derivations, and side effects through a single, consistent interface.

1. The Constructor: $( input )

Depending on what you pass into $( ), SigPro creates a different type of reactive primitive:

Input Type	Result	Internal Behavior
Value (String, Number, Object...)	Signal	Creates a piece of mutable state.
Function	Computed / Effect	Creates a derived value that tracks dependencies.

---

2. Signal (State)

A Signal is a "box" that holds a value. It provides a getter/setter function to interact with that value.

• When to use: For data that changes over time (counters, user input, toggle states, API data).
• Syntax: const $state = $(initialValue);

Example:

const $name = $("Alice");

// Read the value (Getter)
console.log($name()); // "Alice"

// Update the value (Setter)
$name("Bob"); 

// Update based on previous value
$name(current => current + " Smith");

---

3. Computed (Derived State)

When you pass a function to $( ) that returns a value, SigPro creates a Computed Signal. It automatically tracks which signals are used inside it and re-runs only when they change.

• When to use: For values that depend on other signals (totals, filtered lists, formatted strings).
• Syntax: const $derived = $(() => logic);

Example:

const $price = $(100);
const $qty = $(2);

// Automatically tracks $price and $qty
const $total = $(() => $price() * $qty());

console.log($total()); // 200

$qty(3); // $total updates to 300 automatically

---

4. Effects (Side Effects)

An Effect is a function passed to $( ) that does not return a value (or returns undefined). SigPro treats this as a subscription that performs an action whenever its dependencies change.

• When to use: For DOM manipulations, logging, or syncing with external APIs (LocalStorage, Fetch).
• Syntax: $(() => { action });

Example:

const $theme = $("light");

// This effect runs every time $theme changes
$(() => {
  document.body.className = $theme();
  console.log("Theme updated to:", $theme());
});

$theme("dark"); // Logs: Theme updated to: dark

---

5. Summary Table: Usage Guide

Primitive	Logic Type	Returns Value?	Typical Use Case
Signal	Static	Yes (Mutable)	const $user = $("Guest")
Computed	Read-only	Yes (Automatic)	const $isLoggedIn = $(() => $user() !== "Guest")
Effect	Imperative	No	$(() => localStorage.setItem('user', $user()))

---

💡 Pro Tip: Naming Convention

In SigPro, we use the $ prefix (e.g., $count) for variables that hold a reactive function. This makes it easy to distinguish between a standard variable and a reactive one at a glance:

let count = 0;   // Static
const $count = $(0); // Reactive (Function)