@alaq/nucleus — The Engine

Реактивное ядро вселенной Alak. Проактивный контейнер для управления потоками данных (электронами).

Nucleus (Нуклон) — это фундаментальный строительный блок экосистемы Alak. Это не просто переменная или observable, это активный агент (двигатель), который управляет:

1. Хранением значения.
2. Маршрутизацией обновлений (электронов) к подписчикам.
3. Вычислением производных состояний (quarks).

В метафоре "Облака Электронов", Nucleus — это орбиталь, которая определяет, где находится энергия (данные) и куда она движется.

Установка

npm install @alaq/nucleus

Философия: Функция как Контейнер

В отличие от классов или объектов, Nucleus — это функция. Это позволяет использовать его максимально лаконично:

• Вызов без аргументов count() — это getter (получить значение).
• Вызов с аргументом count(5) — это setter (установить значение/запустить электрон).

Основные концепции

1. Nucleus (Ядро)

Базовая единица состояния.

• Хранилище: Содержит текущее значение.
• Маршрутизатор: При изменении значения, nucleus "выстреливает" событие всем подписчикам.
• Ленивость: Если nucleus вычисляемый, он может пересчитываться только при запросе.

2. Подписка (Binding)

Связь между nucleus и функцией-реакцией.

• .up(fn): "Проснуться". Вызывает fn сразу с текущим значением и подписывается на будущие обновления.
• .next(fn): "Ожидать". Игнорирует текущее значение, вызывает fn только при следующем обновлении.
• .once(fn): "Один раз". Подписывается, срабатывает один раз и сразу отписывается.

3. Кварки (Computed Nucleus)

Nucleus, который зависит от других nucle'ов.

• Создается через .from(...).
• Автоматически отслеживает зависимости.
• Умное обновление: пересчитывается только если изменились зависимости.

Примеры использования

Базовое использование (Счетчик)

import { N } from '@alaq/nucleus'

// 1. Создание: Энергетический уровень 0
const count = N(0)

// 2. Подписка: Реакция на изменение энергии
const listener = (val) => {
  console.log(`Энергия: ${val}`)
}
count.up(listener)
// -> "Энергия: 0"

// 3. Воздействие: Добавление энергии
count(10)
// -> "Энергия: 10"

// 4. Геттер: Проверка уровня
console.log(count.value) // 10
console.log(count())     // 10

// 5. Очистка
count.down(listener) // Отписка

Реактивная Математика (Quarks)

Создание зависимых потоков данных. Если изменится price или tax, total обновится автоматически.

import { N } from '@alaq/nucleus'

const price = N(100)
const tax = N(0.2) // 20%

// Кварк: зависит от price и tax
const total = N().from(price, tax).map(([p, t]) => {
  return p * (1 + t)
})

total.up(v => console.log('Итого:', v))
// -> "Итого: 120"

price(200)
// -> "Итого: 240" (пересчиталось автоматически)

Асинхронные потоки (Async Getters)

Nucleus может быть шлюзом к асинхронным данным (API, БД).

import { N } from '@alaq/nucleus'

const userId = N(1)
const userData = N()

// Определяем, как добывать данные
userData.setGetter(async () => {
  console.log('Загрузка...')
  const res = await fetch(`/api/users/${userId()}`)
  return res.json()
}, true) // true = reactive (зависит от других N внутри)

// Триггер: при изменении userId, userData перезапросит данные
userId.up(() => userData()) 

userData.up(user => console.log('Пользователь:', user.name))

API Reference

Создание

• N(initialValue): Создать обычный nucleus.

Подписка и Чтение

• nucleus(): Получить значение (как функция).
• nucleus.value: Получить значение (свойство).
• nucleus.up(cb): Подписаться + немедленный вызов.
• nucleus.next(cb): Подписаться на следующее изменение.
• nucleus.down(cb): Отписаться.
• nucleus.once(cb): Подписаться на одно изменение.

Трансформация и Зависимости

• .from(n1, n2, ...): Установить источники зависимости.
• .map(cb): Преобразовать значение (для computed).
• .filter(cb): Пропустить обновление, если cb вернет false.

Управление поведением

• .stateless(): Не хранить значение. Работает как Event Emitter.
• .finite(): Испускать событие только если значение изменилось (по умолчанию вкл для примитивов).
• .decay(): "Распад". Уничтожить nucleus, очистить память, удалить все связи.

Лицензия: TVR