Upload docs
This commit is contained in:
@@ -1,46 +1,45 @@
|
||||
# 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.
|
||||
The `$` function is the heart of **SigPro**. It is a **Unified Reactive Constructor** that handles state, derivations, and automatic persistence through a single, consistent interface.
|
||||
|
||||
## 1. The Constructor: `$( input )`
|
||||
## 1. The Constructor: `$( input, [key] )`
|
||||
|
||||
Depending on what you pass into `$( )`, SigPro creates a different type of reactive primitive:
|
||||
Depending on the arguments you pass, SigPro creates different reactive primitives:
|
||||
|
||||
| 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. |
|
||||
| Argument | Type | Required | Description |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **input** | `Value` / `Function` | **Yes** | Initial state or reactive logic. |
|
||||
| **key** | `string` | No | If provided, the signal **persists** in `localStorage`. |
|
||||
|
||||
---
|
||||
|
||||
## 2. Signal (State)
|
||||
## 2. Signal (State & Persistence)
|
||||
|
||||
A **Signal** is a "box" that holds a value. It provides a getter/setter function to interact with that value.
|
||||
A **Signal** is a reactive "box" for data. SigPro now supports **Native Persistence**: if you provide a second argument (the `key`), the signal will automatically sync with `localStorage`.
|
||||
|
||||
* **When to use:** For data that changes over time (counters, user input, toggle states, API data).
|
||||
* **Syntax:** `const $state = $(initialValue);`
|
||||
* **Standard:** `const $count = $(0);`
|
||||
* **Persistent:** `const $theme = $("light", "app-theme");` (Restores value on page reload).
|
||||
|
||||
### Example:
|
||||
```javascript
|
||||
const $name = $("Alice");
|
||||
const $user = $("Guest", "session-user"); // Automatically saved/loaded
|
||||
|
||||
// Read the value (Getter)
|
||||
console.log($name()); // "Alice"
|
||||
// Read (Getter)
|
||||
console.log($user());
|
||||
|
||||
// Update the value (Setter)
|
||||
$name("Bob");
|
||||
// Update (Setter + Auto-save to Disk)
|
||||
$user("Alice");
|
||||
|
||||
// Update based on previous value
|
||||
$name(current => current + " Smith");
|
||||
// Functional Update
|
||||
$user(prev => prev.toUpperCase());
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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 you pass a **function** that **returns a value**, SigPro creates a **Computed Signal**. It tracks dependencies and recalculates only when necessary.
|
||||
|
||||
* **When to use:** For values that depend on other signals (totals, filtered lists, formatted strings).
|
||||
* **Syntax:** `const $derived = $(() => logic);`
|
||||
|
||||
### Example:
|
||||
@@ -48,54 +47,56 @@ When you pass a **function** to `$( )` that **returns a value**, SigPro creates
|
||||
const $price = $(100);
|
||||
const $qty = $(2);
|
||||
|
||||
// Automatically tracks $price and $qty
|
||||
// Auto-tracks $price and $qty
|
||||
const $total = $(() => $price() * $qty());
|
||||
|
||||
console.log($total()); // 200
|
||||
|
||||
$qty(3); // $total updates to 300 automatically
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Effects (Side Effects)
|
||||
## 4. Effects (Reactive Actions)
|
||||
|
||||
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.
|
||||
An **Effect** is a function that **does not return a value**. It performs an action (side effect) whenever the signals it "touches" change.
|
||||
|
||||
* **When to use:** For DOM manipulations, logging, or syncing with external APIs (LocalStorage, Fetch).
|
||||
* **When to use:** Logging, manual DOM tweaks, or syncing with external APIs.
|
||||
* **Syntax:** `$(() => { action });`
|
||||
|
||||
### Example:
|
||||
```javascript
|
||||
const $theme = $("light");
|
||||
const $status = $("online");
|
||||
|
||||
// This effect runs every time $theme changes
|
||||
// Runs every time $status changes
|
||||
$(() => {
|
||||
document.body.className = $theme();
|
||||
console.log("Theme updated to:", $theme());
|
||||
console.log("System status is now:", $status());
|
||||
});
|
||||
|
||||
$theme("dark"); // Logs: Theme updated to: dark
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Summary Table: Usage Guide
|
||||
|
||||
| Primitive | Logic Type | Returns Value? | Typical Use Case |
|
||||
| Primitive | Logic Type | Persistence? | 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()))` |
|
||||
|
||||
|
||||
| **Signal** | Mutable State | **Yes** (Optional) | `$(0, 'counter')` |
|
||||
| **Computed** | Derived / Read-only | No | `$(() => $a() + $b())` |
|
||||
| **Effect** | Imperative Action | No | `$(() => alert($msg()))` |
|
||||
|
||||
---
|
||||
|
||||
## 💡 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:
|
||||
## 💡 Pro Tip: The Power of Native Persistence
|
||||
|
||||
In SigPro, you don't need external plugins for basic storage. By using the `key` parameter in a Signal, you gain:
|
||||
1. **Zero Boilerplate:** No more `JSON.parse(localStorage.getItem(...))`.
|
||||
2. **Instant Hydration:** The value is restored **before** the UI renders, preventing "flicker".
|
||||
3. **Atomic Safety:** Data is saved to disk exactly when the signal changes, ensuring your app state is always safe.
|
||||
|
||||
---
|
||||
|
||||
### Naming Convention
|
||||
We use the **`$` prefix** (e.g., `$count`) for reactive functions to distinguish them from static variables at a glance:
|
||||
|
||||
```javascript
|
||||
let count = 0; // Static
|
||||
const $count = $(0); // Reactive (Function)
|
||||
let count = 0; // Static
|
||||
const $count = $(0); // Reactive Signal
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user