Skip to content

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