# Signals API 📡

Signals are the heart of SigPro's reactivity system. They are reactive values that automatically track dependencies and notify subscribers when they change. This enables fine-grained updates without virtual DOM diffing.

## Core Concepts

### What is a Signal?

A signal is a function that holds a value and notifies dependents when that value changes. Signals can be:

- **Basic signals** - Hold simple values (numbers, strings, objects)
- **Computed signals** - Derive values from other signals
- **Persistent signals** - Automatically sync with localStorage/sessionStorage

### How Reactivity Works

SigPro uses automatic dependency tracking:

1. When you read a signal inside an effect, the effect becomes a subscriber
2. When the signal's value changes, all subscribers are notified
3. Updates are batched using microtasks for optimal performance
4. Only the exact nodes that depend on changed values are updated

## `$(initialValue)`

Creates a reactive signal. The behavior changes based on the type of `initialValue`:

- If `initialValue` is a **function**, creates a computed signal
- Otherwise, creates a basic signal

```javascript
import { $ } from 'sigpro';

// Basic signal
const count = $(0);

// Computed signal
const firstName = $('John');
const lastName = $('Doe');
const fullName = $(() => `${firstName()} ${lastName()}`);
```

## 📋 API Reference

### Basic Signals

| Pattern | Example | Description |
|---------|---------|-------------|
| Create | `const count = $(0)` | Create signal with initial value |
| Get | `count()` | Read current value |
| Set | `count(5)` | Set new value directly |
| Update | `count(prev => prev + 1)` | Update based on previous value |

### Computed Signals

| Pattern | Example | Description |
|---------|---------|-------------|
| Create | `const total = $(() => price() * quantity())` | Derive value from other signals |
| Get | `total()` | Read computed value (auto-updates) |

### Signal Methods

| Method | Description | Example |
|--------|-------------|---------|
| `signal()` | Gets current value | `count()` |
| `signal(newValue)` | Sets new value | `count(5)` |
| `signal(prev => new)` | Updates using previous value | `count(c => c + 1)` |

## 🎯 Basic Examples

### Counter Signal

```javascript
import { $ } from 'sigpro';

const count = $(0);

console.log(count()); // 0

count(5);
console.log(count()); // 5

count(prev => prev + 1);
console.log(count()); // 6
```

### Object Signal

```javascript
import { $ } from 'sigpro';

const user = $({
  name: 'John',
  age: 30,
  email: 'john@example.com'
});

// Read
console.log(user().name); // 'John'

// Update (immutable pattern)
user({
  ...user(),
  age: 31
});

// Partial update with function
user(prev => ({
  ...prev,
  email: 'john.doe@example.com'
}));
```

### Array Signal

```javascript
import { $ } from 'sigpro';

const todos = $(['Learn SigPro', 'Build an app']);

// Add item
todos([...todos(), 'Deploy to production']);

// Remove item
todos(todos().filter((_, i) => i !== 1));

// Update item
todos(todos().map((todo, i) => 
  i === 0 ? 'Master SigPro' : todo
));
```

## 🔄 Computed Signals

Computed signals automatically update when their dependencies change:

```javascript
import { $ } from 'sigpro';

const price = $(10);
const quantity = $(2);
const tax = $(0.21);

// Computed signals
const subtotal = $(() => price() * quantity());
const taxAmount = $(() => subtotal() * tax());
const total = $(() => subtotal() + taxAmount());

console.log(total()); // 24.2

price(15);
console.log(total()); // 36.3 (automatically updated)

quantity(3);
console.log(total()); // 54.45 (automatically updated)
```

### Computed with Multiple Dependencies

```javascript
import { $ } from 'sigpro';

const firstName = $('John');
const lastName = $('Doe');
const prefix = $('Mr.');

const fullName = $(() => {
  // Computed signals can contain logic
  const name = `${firstName()} ${lastName()}`;
  return prefix() ? `${prefix()} ${name}` : name;
});

console.log(fullName()); // 'Mr. John Doe'

prefix('');
console.log(fullName()); // 'John Doe'
```

### Computed with Conditional Logic

```javascript
import { $ } from 'sigpro';

const user = $({ role: 'admin', permissions: [] });
const isAdmin = $(() => user().role === 'admin');
const hasPermission = $(() => 
  isAdmin() || user().permissions.includes('edit')
);

console.log(hasPermission()); // true

user({ role: 'user', permissions: ['view'] });
console.log(hasPermission()); // false (can't edit)

user({ role: 'user', permissions: ['view', 'edit'] });
console.log(hasPermission()); // true (now has permission)
```

## 🧮 Advanced Signal Patterns

### Derived State Pattern

```javascript
import { $ } from 'sigpro';

// Shopping cart example
const cart = $([
  { id: 1, name: 'Product 1', price: 10, quantity: 2 },
  { id: 2, name: 'Product 2', price: 15, quantity: 1 },
]);

// Derived values
const itemCount = $(() => 
  cart().reduce((sum, item) => sum + item.quantity, 0)
);

const subtotal = $(() => 
  cart().reduce((sum, item) => sum + (item.price * item.quantity), 0)
);

const tax = $(() => subtotal() * 0.21);
const total = $(() => subtotal() + tax());

// Update cart
cart([
  ...cart(),
  { id: 3, name: 'Product 3', price: 20, quantity: 1 }
]);

// All derived values auto-update
console.log(itemCount()); // 4
console.log(total()); // (10*2 + 15*1 + 20*1) * 1.21 = 78.65
```

### Validation Pattern

```javascript
import { $ } from 'sigpro';

const email = $('');
const password = $('');
const confirmPassword = $('');

// Validation signals
const isEmailValid = $(() => {
  const value = email();
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
});

const isPasswordValid = $(() => {
  const value = password();
  return value.length >= 8;
});

const doPasswordsMatch = $(() => 
  password() === confirmPassword()
);

const isFormValid = $(() => 
  isEmailValid() && isPasswordValid() && doPasswordsMatch()
);

// Update form
email('user@example.com');
password('secure123');
confirmPassword('secure123');

console.log(isFormValid()); // true

// Validation messages
const emailError = $(() => 
  email() && !isEmailValid() ? 'Invalid email format' : ''
);
```

### Filtering and Search Pattern

```javascript
import { $ } from 'sigpro';

const items = $([
  { id: 1, name: 'Apple', category: 'fruit' },
  { id: 2, name: 'Banana', category: 'fruit' },
  { id: 3, name: 'Carrot', category: 'vegetable' },
  { id: 4, name: 'Date', category: 'fruit' },
]);

const searchTerm = $('');
const categoryFilter = $('all');

// Filtered items (computed)
const filteredItems = $(() => {
  let result = items();
  
  // Apply search filter
  if (searchTerm()) {
    const term = searchTerm().toLowerCase();
    result = result.filter(item => 
      item.name.toLowerCase().includes(term)
    );
  }
  
  // Apply category filter
  if (categoryFilter() !== 'all') {
    result = result.filter(item => 
      item.category === categoryFilter()
    );
  }
  
  return result;
});

// Stats
const fruitCount = $(() => 
  items().filter(item => item.category === 'fruit').length
);

const vegCount = $(() => 
  items().filter(item => item.category === 'vegetable').length
);

// Update filters
searchTerm('a');
console.log(filteredItems().map(i => i.name)); // ['Apple', 'Banana', 'Carrot', 'Date']

categoryFilter('fruit');
console.log(filteredItems().map(i => i.name)); // ['Apple', 'Banana', 'Date']
```

### Pagination Pattern

```javascript
import { $ } from 'sigpro';

const allItems = $([...Array(100).keys()].map(i => `Item ${i + 1}`));
const currentPage = $(1);
const itemsPerPage = $(10);

// Paginated items (computed)
const paginatedItems = $(() => {
  const start = (currentPage() - 1) * itemsPerPage();
  const end = start + itemsPerPage();
  return allItems().slice(start, end);
});

// Pagination metadata
const totalPages = $(() => 
  Math.ceil(allItems().length / itemsPerPage())
);

const hasNextPage = $(() => 
  currentPage() < totalPages()
);

const hasPrevPage = $(() => 
  currentPage() > 1
);

const pageRange = $(() => {
  const current = currentPage();
  const total = totalPages();
  const delta = 2;
  
  let range = [];
  for (let i = Math.max(2, current - delta); 
       i <= Math.min(total - 1, current + delta); 
       i++) {
    range.push(i);
  }
  
  if (current - delta > 2) range = ['...', ...range];
  if (current + delta < total - 1) range = [...range, '...'];
  
  return [1, ...range, total];
});

// Navigation
const nextPage = () => {
  if (hasNextPage()) currentPage(c => c + 1);
};

const prevPage = () => {
  if (hasPrevPage()) currentPage(c => c - 1);
};

const goToPage = (page) => {
  if (page >= 1 && page <= totalPages()) {
    currentPage(page);
  }
};
```

## 🔧 Advanced Signal Features

### Signal Equality Comparison

Signals use `Object.is` for change detection. Only notify subscribers when values are actually different:

```javascript
import { $ } from 'sigpro';

const count = $(0);

// These won't trigger updates:
count(0); // Same value
count(prev => prev); // Returns same value

// These will trigger updates:
count(1); // Different value
count(prev => prev + 0); // Still 0? Actually returns 0? Wait...
// Be careful with functional updates!
```

### Batch Updates

Multiple signal updates are batched into a single microtask:

```javascript
import { $ } from 'sigpro';

const firstName = $('John');
const lastName = $('Doe');
const fullName = $(() => `${firstName()} ${lastName()}`);

$.effect(() => {
  console.log('Full name:', fullName());
});
// Logs: 'Full name: John Doe'

// Multiple updates in same tick - only one effect run!
firstName('Jane');
lastName('Smith');
// Only logs once: 'Full name: Jane Smith'
```

### Infinite Loop Protection

SigPro includes protection against infinite reactive loops:

```javascript
import { $ } from 'sigpro';

const a = $(1);
const b = $(2);

// This would create a loop, but SigPro prevents it
$.effect(() => {
  a(b()); // Reading b
  b(a()); // Reading a - loop detected!
});
// Throws: "SigPro: Infinite reactive loop detected."
```

## 📊 Performance Characteristics

| Operation | Complexity | Notes |
|-----------|------------|-------|
| Signal read | O(1) | Direct value access |
| Signal write | O(n) | n = number of subscribers |
| Computed read | O(1) or O(m) | m = computation complexity |
| Effect run | O(s) | s = number of signal reads |

## 🎯 Best Practices

### 1. Keep Signals Focused

```javascript
// ❌ Avoid large monolithic signals
const state = $({
  user: null,
  posts: [],
  theme: 'light',
  notifications: []
});

// ✅ Split into focused signals
const user = $(null);
const posts = $([]);
const theme = $('light');
const notifications = $([]);
```

### 2. Use Computed for Derived State

```javascript
// ❌ Don't compute in templates/effects
$.effect(() => {
  const total = items().reduce((sum, i) => sum + i.price, 0);
  updateUI(total);
});

// ✅ Compute with signals
const total = $(() => items().reduce((sum, i) => sum + i.price, 0));
$.effect(() => updateUI(total()));
```

### 3. Immutable Updates

```javascript
// ❌ Don't mutate objects/arrays
const user = $({ name: 'John' });
user().name = 'Jane'; // Won't trigger updates!

// ✅ Create new objects/arrays
user({ ...user(), name: 'Jane' });

// ❌ Don't mutate arrays
const todos = $(['a', 'b']);
todos().push('c'); // Won't trigger updates!

// ✅ Create new arrays
todos([...todos(), 'c']);
```

### 4. Functional Updates for Dependencies

```javascript
// ❌ Avoid if new value depends on current
count(count() + 1);

// ✅ Use functional update
count(prev => prev + 1);
```

### 5. Clean Up Effects

```javascript
import { $ } from 'sigpro';

const userId = $(1);

// Effects auto-clean in pages, but you can stop manually
const stop = $.effect(() => {
  fetchUser(userId());
});

// Later, if needed
stop();
```

## 🚀 Real-World Examples

### Form State Management

```javascript
import { $ } from 'sigpro';

// Form state
const formData = $({
  username: '',
  email: '',
  age: '',
  newsletter: false
});

// Touched fields (for validation UI)
const touched = $({
  username: false,
  email: false,
  age: false
});

// Validation rules
const validations = {
  username: (value) => 
    value.length >= 3 ? null : 'Username must be at least 3 characters',
  email: (value) => 
    /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value) ? null : 'Invalid email',
  age: (value) => 
    !value || (value >= 18 && value <= 120) ? null : 'Age must be 18-120'
};

// Validation signals
const errors = $(() => {
  const data = formData();
  const result = {};
  
  Object.keys(validations).forEach(field => {
    const error = validations[field](data[field]);
    if (error) result[field] = error;
  });
  
  return result;
});

const isValid = $(() => Object.keys(errors()).length === 0);

// Field helpers
const fieldProps = (field) => ({
  value: formData()[field],
  error: touched()[field] ? errors()[field] : null,
  onChange: (e) => {
    const value = e.target.type === 'checkbox' ? e.target.checked : e.target.value;
    formData({
      ...formData(),
      [field]: value
    });
  },
  onBlur: () => {
    touched({
      ...touched(),
      [field]: true
    });
  }
});

// Form submission
const submitAttempts = $(0);
const isSubmitting = $(false);

const handleSubmit = async () => {
  submitAttempts(s => s + 1);
  
  if (!isValid()) {
    // Mark all fields as touched to show errors
    touched(Object.keys(formData()).reduce((acc, field) => ({
      ...acc,
      [field]: true
    }), {}));
    return;
  }
  
  isSubmitting(true);
  try {
    await saveForm(formData());
    // Reset form on success
    formData({ username: '', email: '', age: '', newsletter: false });
    touched({ username: false, email: false, age: false });
  } finally {
    isSubmitting(false);
  }
};
```

### Todo App with Filters

```javascript
import { $ } from 'sigpro';

// State
const todos = $([
  { id: 1, text: 'Learn SigPro', completed: true },
  { id: 2, text: 'Build an app', completed: false },
  { id: 3, text: 'Write docs', completed: false }
]);

const filter = $('all'); // 'all', 'active', 'completed'
const newTodoText = $('');

// Computed values
const filteredTodos = $(() => {
  const all = todos();
  
  switch(filter()) {
    case 'active':
      return all.filter(t => !t.completed);
    case 'completed':
      return all.filter(t => t.completed);
    default:
      return all;
  }
});

const activeCount = $(() => 
  todos().filter(t => !t.completed).length
);

const completedCount = $(() => 
  todos().filter(t => t.completed).length
);

const hasCompleted = $(() => completedCount() > 0);

// Actions
const addTodo = () => {
  const text = newTodoText().trim();
  if (text) {
    todos([
      ...todos(),
      {
        id: Date.now(),
        text,
        completed: false
      }
    ]);
    newTodoText('');
  }
};

const toggleTodo = (id) => {
  todos(todos().map(todo =>
    todo.id === id 
      ? { ...todo, completed: !todo.completed }
      : todo
  ));
};

const deleteTodo = (id) => {
  todos(todos().filter(todo => todo.id !== id));
};

const clearCompleted = () => {
  todos(todos().filter(todo => !todo.completed));
};

const toggleAll = () => {
  const allCompleted = activeCount() === 0;
  todos(todos().map(todo => ({
    ...todo,
    completed: !allCompleted
  })));
};
```

### Shopping Cart

```javascript
import { $ } from 'sigpro';

// Products catalog
const products = $([
  { id: 1, name: 'Laptop', price: 999, stock: 5 },
  { id: 2, name: 'Mouse', price: 29, stock: 20 },
  { id: 3, name: 'Keyboard', price: 79, stock: 10 },
  { id: 4, name: 'Monitor', price: 299, stock: 3 }
]);

// Cart state
const cart = $({});
const selectedProduct = $(null);
const quantity = $(1);

// Computed cart values
const cartItems = $(() => {
  const items = [];
  Object.entries(cart()).forEach(([productId, qty]) => {
    const product = products().find(p => p.id === parseInt(productId));
    if (product) {
      items.push({
        ...product,
        quantity: qty,
        subtotal: product.price * qty
      });
    }
  });
  return items;
});

const itemCount = $(() => 
  cartItems().reduce((sum, item) => sum + item.quantity, 0)
);

const subtotal = $(() => 
  cartItems().reduce((sum, item) => sum + item.subtotal, 0)
);

const tax = $(() => subtotal() * 0.10);
const shipping = $(() => subtotal() > 100 ? 0 : 10);
const total = $(() => subtotal() + tax() + shipping());

const isCartEmpty = $(() => itemCount() === 0);

// Cart actions
const addToCart = (product, qty = 1) => {
  const currentQty = cart()[product.id] || 0;
  const newQty = currentQty + qty;
  
  if (newQty <= product.stock) {
    cart({
      ...cart(),
      [product.id]: newQty
    });
    return true;
  }
  return false;
};

const updateQuantity = (productId, newQty) => {
  const product = products().find(p => p.id === productId);
  if (newQty <= product.stock) {
    if (newQty <= 0) {
      removeFromCart(productId);
    } else {
      cart({
        ...cart(),
        [productId]: newQty
      });
    }
  }
};

const removeFromCart = (productId) => {
  const newCart = { ...cart() };
  delete newCart[productId];
  cart(newCart);
};

const clearCart = () => cart({});

// Stock management
const productStock = (productId) => {
  const product = products().find(p => p.id === productId);
  if (!product) return 0;
  const inCart = cart()[productId] || 0;
  return product.stock - inCart;
};

const isInStock = (productId, qty = 1) => {
  return productStock(productId) >= qty;
};
```

## 📈 Debugging Signals

### Logging Signal Changes

```javascript
import { $ } from 'sigpro';

// Wrap a signal to log changes
const withLogging = (signal, name) => {
  return (...args) => {
    if (args.length) {
      const oldValue = signal();
      const result = signal(...args);
      console.log(`${name}:`, oldValue, '->', signal());
      return result;
    }
    return signal();
  };
};

// Usage
const count = withLogging($(0), 'count');
count(5); // Logs: "count: 0 -> 5"
```

### Signal Inspector

```javascript
import { $ } from 'sigpro';

// Create an inspectable signal
const createInspector = () => {
  const signals = new Map();
  
  const createSignal = (initialValue, name) => {
    const signal = $(initialValue);
    signals.set(signal, { name, subscribers: new Set() });
    
    // Wrap to track subscribers
    const wrapped = (...args) => {
      if (!args.length && activeEffect) {
        const info = signals.get(wrapped);
        info.subscribers.add(activeEffect);
      }
      return signal(...args);
    };
    
    return wrapped;
  };
  
  const getInfo = () => {
    const info = {};
    signals.forEach((data, signal) => {
      info[data.name] = {
        subscribers: data.subscribers.size,
        value: signal()
      };
    });
    return info;
  };
  
  return { createSignal, getInfo };
};

// Usage
const inspector = createInspector();
const count = inspector.createSignal(0, 'count');
const doubled = inspector.createSignal(() => count() * 2, 'doubled');

console.log(inspector.getInfo());
// { count: { subscribers: 0, value: 0 }, doubled: { subscribers: 0, value: 0 } }
```

## 📊 Summary

| Feature | Description |
|---------|-------------|
| **Basic Signals** | Hold values and notify on change |
| **Computed Signals** | Auto-updating derived values |
| **Automatic Tracking** | Dependencies tracked automatically |
| **Batch Updates** | Multiple updates batched in microtask |
| **Infinite Loop Protection** | Prevents reactive cycles |
| **Zero Dependencies** | Pure vanilla JavaScript |

---

> **Pro Tip:** Signals are the foundation of reactivity in SigPro. Master them, and you've mastered 80% of the library!