Reactive Engine + Vue 3 + SSR: Изоморфная реактивность без компромиссов с Nuxt 4

yarn add @pravosleva/reactive-engine

my-nuxt-app/
├── composables/          # Сюда кладем useEngine.ts
├── plugins/              # Сюда кладем reactiveEngine.ts
├── components/           # Сюда кладем CounterWidget.vue и DashboardClientUI.vue
├── pages/                # Сюда кладем dashboard.vue для Части 2
├── app.vue               # Главная точка входа
└── nuxt.config.ts        # Конфигурация Nuxt

my-nuxt-app/
├── app/                      # <--- Главная папка вашего исходного кода
│   ├── components/           # Сюда кладем CounterWidget.vue и DashboardClientUI.vue
│   ├── composables/          # Сюда создаем useEngine.ts
│   ├── plugins/              # Сюда создаем reactiveEngine.ts
│   ├── pages/                # Сюда создаем dashboard.vue
│   ├── app.config.ts         # Конфигурация приложения Nuxt 4
│   └── app.vue               # Главная точка входа
├── package.json
└── nuxt.config.ts            # Глобальный конфиг (лежит в самом корне проекта)

<template>
  <div style="background-color: #121214; min-height: 100vh; padding: 40px; display: flex; justify-content: center; align-items: center;">
    <!-- Nuxt автоматически найдет и отрендерит компонент из папки app/components/ -->
    <CounterWidget />
  </div>
</template>

// app/plugins/reactiveEngine.ts

import { ReactiveEngine as ReactiveEngine4Vue } from '@pravosleva/reactive-engine/vue'

export default defineNuxtPlugin((nuxtApp) => {
  // Инициализируем Vue-версию движка под текущую сессию/запрос
  const engine = new ReactiveEngine4Vue({
    logger: {
      isEnabled: import.meta.dev,
      instanceName: import.meta.server ? 'nuxt-server-engine' : 'nuxt-client-engine'
    }
  })

  // Прокидываем инстанс во Vue-контекст приложения (для inject)
  nuxtApp.vueApp.provide('RE_ENGINE', engine)

  // Делаем движок доступным через useNuxtApp().$reEngine
  return {
    provide: {
      reEngine: engine
    }
  }
})

// app/composables/useEngine.ts

import { inject } from 'vue'

// Явное указание импорта типа для удовлетворения правил TS/ESLint
import type { ReactiveEngine as ReactiveEngine4Vue } from '@pravosleva/reactive-engine/vue'

export const useEngine = () => {
  const engine = inject<ReactiveEngine4Vue>('RE_ENGINE')
  if (!engine) {
    throw new Error('useEngine должен использоваться строго внутри плагина, где активирован provide')
  }
  return engine
}

<script setup lang="ts">
import { AbstractService } from '@pravosleva/reactive-engine'
import { useEngine } from '~/composables/useEngine'

// 1. Описываем изолированную бизнес-логику (Сервис) 
// Этот код на 100% идентичен тому, что мы пишем в React!
class CounterLogic extends AbstractService {
  public counter = this.engine.signal<number>(0, 'example:vue:counter')
  public doubledCounter = this.engine.computed<number>(() => this.counter.value * 2, 'example:vue:computed')

  public inc = () => {
    this.counter.value += 1
  }
}

// 2. Достаем изолированный инстанс движка из контекста Nuxt 3
const engine = useEngine()

// 3. Внедряем наш сервис из встроенного DI-контейнера ядра
const logic = engine.inject(CounterLogic)

// 4. Оборачиваем сигналы во Vue-реактивные примитивы.
// Метод .use() возвращает стандартный ShallowRef<T> объект.
const counter = engine.use(logic.counter)
const doubledCounter = engine.use(logic.doubledCounter)
</script>

<template>
  <div>
    <div>Vue 3 Signal Example</div>

    <!-- 
      ⚠️ Внимание новичкам! 
      В шаблонах Vue 3 объекты ref/shallowRef разворачиваются автоматически.
      Обращаться к .value внутри тегов {{ }} НЕ нужно — пишем просто имя переменной.
    -->
    <code>{{ counter }} | x2 = {{ doubledCounter }}</code>

    <div>
      <!-- Вешаем слушатель события клика через директиву @click -->
      <button @click="logic.inc">
        INC (Vue)
      </button>
    </div>
  </div>
</template>

// app/services/DashboardMetricsService.ts

import { AbstractService } from '@pravosleva/reactive-engine'

// Интерфейс сырых данных бэкенда
export interface IDashboardData {
  rawUsersCount: number
  rawServerLoad: number
}

// Контракт плоского слепка состояния (Snapshot) для передачи по сети
export interface IDashboardSnapshot {
  'ssr:metrics:users': number
  'ssr:metrics:load': number
}

export class DashboardMetricsService extends AbstractService {
  // 1. Сигналы-зависимости. snapshotSignal — изоморфный мост гидратации
  public endpoint = this.engine.signal<string>('dashboard-metrics', 'ssr:signal:endpoint')
  private snapshotSignal = this.engine.signal<IDashboardSnapshot | null>(null, 'ssr:signal:snapshot')

  // Объединяем сигналы в единый вычисляемый кортеж зависимостей для ресурса
  private requestDeps = this.engine.computed(() => {
    return [this.endpoint.value, this.snapshotSignal.value] as const
  }, 'ssr:computed:request-deps')

  // 2. Декларативный асинхронный ресурс (Сетевой слой)
  public metricsResource = this.engine.resource<IDashboardData, readonly [string, IDashboardSnapshot | null]>(
    async ([_endpoint, clientSnapshot]) => {
      // ГИДРАТАЦИЯ: Если на клиент прилетел готовый снапшот — мгновенно отдаем его без fetch
      if (clientSnapshot) {
        return {
          rawUsersCount: clientSnapshot['ssr:metrics:users'],
          rawServerLoad: clientSnapshot['ssr:metrics:load']
        }
      }

      // Вызывается на сервере Node.js при SSR ИЛИ при ручном refresh на клиенте
      if (import.meta.server) {
        return { rawUsersCount: 1420, rawServerLoad: 42 }
      }

      // Эмуляция сети для последующих ручных обновлений на клиенте
      await new Promise(resolve => setTimeout(resolve, 100))
      return {
        rawUsersCount: Math.floor(Math.random() * 200) + 1300,
        rawServerLoad: Math.floor(Math.random() * 30) + 20
      }
    },
    this.requestDeps,
    'ssr:resource:metrics'
  )

  // 3. Вычисляемое свойство статуса (Считываем поля .data строго по типам вашего ядра)
  public status = this.engine.computed<string>(() => {
    const data = this.metricsResource.data
    if (!data) return 'STABLE ✅' // Дефолтный статус для серверного кадра при гидратации
    return data.rawServerLoad > 80 ? 'CRITICAL 🔥' : 'STABLE ✅'
  }, 'ssr:computed:status')

  /**
   * Метод гидратации: Переводим сигналы на рельсы прилетевших данных
   */
  public initFromSnapshot(snapshot?: IDashboardSnapshot | null): void {
    if (!snapshot) return
    this.snapshotSignal.value = snapshot
  }

  /**
   * Метод генерации снимка для передачи по сети на сервере
   */
  public getSnapshot(): IDashboardSnapshot {
    const data = this.metricsResource.data
    return {
      'ssr:metrics:users': data?.rawUsersCount ?? 1420,
      'ssr:metrics:load': data?.rawServerLoad ?? 42
    }
  }

  /**
   * Бизнес-метод мутации (Инвалидация через изменение зависимостей ресурса)
   */
  public simulateUserInflow = (): void => {
    this.snapshotSignal.value = null // Снимаем заглушку, открывая шлюз для живой сети
    this.endpoint.value = `dashboard-metrics?refresh=${Date.now()}`
  }
}

<!-- app/pages/dashboard.vue -->
<script setup lang="ts">
import { useEngine } from '~/composables/useEngine'
import { DashboardMetricsService, type IDashboardSnapshot } from '~/services/DashboardMetricsService'

const engine = useEngine()
const metricsService = engine.inject(DashboardMetricsService)

// На этапе SSR блокируем поток сервера Node.js до полного выполнения асинхронного ресурса движка
if (import.meta.server) {
  // Если у вашего ресурса есть promise-геттер загрузки, дожидаемся его выполнения
  // Либо Nuxt автоматически дождется топ-левел await тасок перед генерацией HTML-кадра
}

// Формируем плоский снимок состояния
const sharedSnapshot = useState<IDashboardSnapshot>(
  'engine-state-snapshot',
  () => metricsService.getSnapshot()
)
</script>

<template>
  <main style="max-width: 600px; margin: 0 auto; padding: 40px;">
    <h1 style="color: #ff8a53; font-size: 1.8rem; margin-bottom: 24px;">
      🌊 Мониторинг: Nuxt 4 + ReactiveEngine (Resource SSR)
    </h1>

    <DashboardClientUI :snapshot="sharedSnapshot" />
  </main>
</template>

<!-- app/pages/dashboard.vue -->
<script setup lang="ts">
import { useEngine } from '~/composables/useEngine'
import { DashboardMetricsService, type IDashboardSnapshot } from '~/services/DashboardMetricsService'

// 1. На сервере Nuxt сам выполняет асинхронный запрос и блокирует поток до его резолва
const { data: serverMetrics } = await useAsyncData('dashboard-ssr-fetch', async () => {
  // В реальном проекте здесь будет обращение к вашему бэкенду/базе
  return {
    rawUsersCount: 1420,
    rawServerLoad: 42
  }
})

const engine = useEngine()
const metricsService = engine.inject(DashboardMetricsService)

// 2. Превращаем результат запроса Nuxt в плоский слепок (Snapshot)
const initialSnapshot: IDashboardSnapshot = {
  'ssr:metrics:users': serverMetrics.value?.rawUsersCount ?? 1420,
  'ssr:metrics:load': serverMetrics.value?.rawServerLoad ?? 42
}

// 3. Записываем snapshot в кэш сервиса прямо на сервере, чтобы getSnapshot() отработал корректно
metricsService.initFromSnapshot(initialSnapshot)

// 4. Упаковываем в изоморфный буфер для передачи в браузер
const sharedSnapshot = useState<IDashboardSnapshot>('engine-state-snapshot', () => initialSnapshot)
</script>

<template>
  <main style="max-width: 600px; margin: 0 auto; padding: 40px;">
    <h1 style="color: #ff8a53; font-size: 1.8rem; margin-bottom: 24px;">
      🌊 Мониторинг: Nuxt 4 + ReactiveEngine (Resource SSR)
    </h1>
    
    <DashboardClientUI :snapshot="sharedSnapshot" />
  </main>
</template>

<!-- app/components/DashboardClientUI.vue -->
<script setup lang="ts">
import { computed } from 'vue'
import { useEngine } from '~/composables/useEngine'
import { DashboardMetricsService, type IDashboardSnapshot, type IDashboardData } from '~/services/DashboardMetricsService'

interface IDashboardProps {
  snapshot: IDashboardSnapshot | null
}

const props = defineProps<IDashboardProps>()

const engine = useEngine()
const logic = engine.inject(DashboardMetricsService)

// Инициализируем мост гидратации до запуска эффектов
logic.initFromSnapshot(props.snapshot)

// Строим реактивный мост во Vue со строгими типами вашего ядра (без any)
const resourceState = engine.use(logic.metricsResource)
const status = engine.use(logic.status)

// Бесшовный прокси-фоллбэк (Ликвидация микро-мерцания верстки).
// Если ресурс сбросился в null в момент гидратации эффектов, мы подставляем данные из props.snapshot напрямую. Экран застывает намертво без морганий.
const metricsData = computed<IDashboardData | null>(() => {
  const currentResourceData = resourceState.value?.data

  if (currentResourceData) {
    return currentResourceData
  }

  if (props.snapshot) {
    return {
      rawUsersCount: props.snapshot['ssr:metrics:users'],
      rawServerLoad: props.snapshot['ssr:metrics:load']
    }
  }

  return null
})
</script>

<template>
  <div style="background: rgba(255,255,255,0.05); padding: 24px; border-radius: 12px; border: 1px solid rgba(255,255,255,0.1); display: flex; flex-direction: column; gap: 16px;">
    <h3 style="margin: 0; color: #00b7ff;">
      Ресурс гидрирован на базе нативного fetcher-транзита:
    </h3>

    <!-- TypeScript строго проверяет наличие полей внутри объекта metricsData -->
    <div
      v-if="metricsData"
      style="font-size: 1.1rem; font-family: monospace;"
    >
      <div>Активных сессий: <code style="color: #00ffcc; font-weight: bold;">{{ metricsData.rawUsersCount }}</code></div>
      <div style="margin-top: 8px;">
        Нагрузка на CPU: <code style="color: #00ffcc; font-weight: bold;">{{ metricsData.rawServerLoad }}%</code>
      </div>
      <div style="margin-top: 8px;">
        Статус системы: <code style="color: #ffcb6b; font-weight: bold;">{{ status }}</code>
      </div>

      <!-- Аккуратный индикатор фонового рефреша сети -->
      <div
        v-if="resourceState && resourceState.loading"
        style="color: #ff8a53; font-size: 0.85rem; margin-top: 12px; font-style: italic;"
      >
        🔄 Обновление данных из сети...
      </div>
    </div>

    <div
      v-else
      style="color: #ff5370;"
    >
      Критическая ошибка: данные сервера потеряны
    </div>

    <div>
      <button
        style="padding: 10px 16px; border: none; background: #ff8a53; color: #fff; font-weight: bold; border-radius: 6px; cursor: pointer;"
        @click="logic.simulateUserInflow"
      >
        Обновить ресурс (Мутировать зависимость)
      </button>
    </div>
  </div>
</template>