# 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:
```javascript
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:
```javascript
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:
```javascript
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:

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