The Reactive Core: `$( )`

The $ function is a Unified Reactive Constructor. It detects the type of input you provide and returns the appropriate reactive primitive.

1. Signals (Atomic State)

A Signal is the simplest form of reactivity. It holds a single value (string, number, boolean, null).

Option A: Standard Signal (RAM)

Ideal for volatile state that shouldn't persist after a page refresh.

const $count = $(0); 

// Usage:
$count();           // Getter: returns 0
$count(10);         // Setter: updates to 10
$count(c => c + 1); // Functional update: updates to 11

Option B: Persistent Signal (Disk)

By adding a key, SigPro links the signal to localStorage.

// Syntax: $(initialValue, "storage-key")
const $theme = $("light", "app-theme"); 

// It restores the value from disk automatically on load.
// When you update it, it saves to disk instantly:
$theme("dark"); // localStorage.getItem("app-theme") is now "dark"

2. Stores (Reactive Objects)

A Store is a proxy that wraps an Object. SigPro makes every property reactive recursively. You access and set properties as if they were individual signals.

Option A: Standard Store (RAM)

const user = $({ 
  name: "Alice", 
  profile: { bio: "Developer" } 
});

// Getter: Call the property as a function
console.log(user.name()); // "Alice"

// Setter: Pass the value to the property function
user.name("Bob"); 

// Nested updates work exactly the same:
user.profile.bio("Architect");

Option B: Persistent Store (Disk)

The most powerful way to save complex state. The entire object tree is serialized to JSON and kept in sync with the disk.

const settings = $({ 
  volume: 50, 
  notifications: true 
}, "user-settings");

// Any change in the object triggers a disk sync:
settings.volume(100); // The whole JSON is updated in localStorage

3. Stores (Reactive Arrays)

When you pass an Array, SigPro tracks changes to the list. You can use standard methods or access indexes as reactive getters.

const $list = $(["Item 1", "Item 2"]);

// Get by index
console.log($list[0]()); // "Item 1"

// Update by index
$list[0]("Updated Item");

// Note: For adding/removing items, use standard array methods 
// which SigPro makes reactive (push, pop, splice, etc.)

4. Computed (Derived Logic)

A Computed Signal is a read-only value that depends on other signals. It is defined by passing a function that returns a value.

const $price = $(100);
const $tax = $(0.21);

// This function HAS a return statement
const $total = $(() => {
  return $price() * (1 + $tax());
});

// Usage (Read-only):
console.log($total()); // 121

$price(200);
console.log($total()); // 242 (Auto-updated)

5. Effects (Reactive Actions)

An Effect is used for side-effects. It is defined by passing a function that does NOT return a value. It runs once immediately and then re-runs whenever its dependencies change.

const $name = $("Alice");

// This function has NO return statement (Side-effect)
$(() => {
  console.log("The name changed to:", $name());
  document.title = `Profile: ${$name()}`;
});

$name("Bob"); // Triggers the console.log and updates document.title

6. Summary: Input Mapping

If you pass...	SigPro creates a...	Access Method
A Value	Signal	`$var()` / `$var(val)`
An Object	Store	`obj.prop()` / `obj.prop(val)`
An Array	Array Store	`arr[i]()` / `arr.push()`
Function (returns)	Computed	`$comp()` (Read-only)
Function (no return)	Effect	Automatically executed

💡 Naming Convention: The `$` Prefix

To keep your code clean, always prefix your reactive variables with $. This tells you at a glance that you need to call it as a function to get its value.

const name = "Static";   // Just a string
const $name = $("Alice"); // A Reactive Signal

4.0 KiB Raw Blame History

The Reactive Core: $( )