XState v5: типізація скінченних автоматів через setup та акторна модель

+-------------------------------------------------------------------------+
|                  АРХІТЕКТУРА ІНФЕРЕНСУ ТИПІВ У XSTATE V5                |
+-------------------------------------------------------------------------+
| [setup({ types: {} as { context, events, input }, actors, actions })]  |
|   |--> Єдина точка декларації контрактів автомата                       |
|   |--> Автоматичний вивід типів без CLI-файлів typegen                  |
+-------------------------------------------------------------------------+
                                    |
                                    v
| [machine = setup(...).createMachine({ ... })]                           |
|   |--> Строга валідація вузлів стану (states: { idle, loading })        |
|   |--> Типізація захисників: ({ context, event }) => boolean            |
|   `-- Типізація ред'юсерів assign: ({ context, event }) => nextContext  |
+-------------------------------------------------------------------------+
                                    |
                                    v
+-------------------------------------------------------------------------+
| [actor = createActor(machine, { input: { initialBudget: 100 } })]       |
|   |-- actor.start()                                                     |
|   |-- actor.send({ type: 'SUBMIT', payload: 'data' })                   |
|   `-- actor.getSnapshot().matches({ active: 'processing' })             |
+-------------------------------------------------------------------------+

Схема взаємодії акторів у XState v5:
+-------------------------------------------------------------+
| Кореневий Актор: CheckoutMachine                            |
|                                                             |
| [Стан: validating]                                          |
|        |                                                    |
|        | invoke: fromPromise(verifyCardApi)                 |
|        v                                                    |
| +---------------------------------------------------------+ |
| | Дочірній Актор: CardVerifier (Promise)                  | |
| | Виконує мережевий запит до платіжного шлюзу             | |
| +---------------------------------------------------------+ |
|        |                                                    |
|        |-- onDone: assign(cardData) -> перехід у [ready]    |
|        `-- onError: assign(error)   -> перехід у [rejected] |
+-------------------------------------------------------------+

import { setup, assign, fromPromise } from 'xstate';

// 1. Опис структур даних контексту, подій та вхідних параметрів
export interface UserSession {
  readonly userId: string;
  readonly email: string;
  readonly role: 'admin' | 'user';
}

export interface AuthContext {
  readonly session: UserSession | null;
  readonly errorMessage: string | null;
  readonly retryCount: number;
}

export type AuthEvent =
  | { type: 'LOGIN'; readonly email: string; readonly pass: string }
  | { type: 'LOGOUT' }
  | { type: 'RETRY' };

export interface AuthInput {
  readonly defaultRetryLimit: number;
}

// 2. Актор асинхронної авторизації
const loginService = fromPromise<
  UserSession,
  { readonly email: string; readonly pass: string }
>(async ({ input }) => {
  const response = await fetch('/api/auth/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(input),
  });

  if (!response.ok) {
    throw new Error(`[AuthError] Невірні облікові дані (${response.status})`);
  }

  return (await response.json()) as UserSession;
});

// 3. Конфігурація через setup() із наскрізною типізацією
export const authMachine = setup({
  types: {
    context: {} as AuthContext,
    events: {} as AuthEvent,
    input: {} as AuthInput,
  },
  actors: {
    loginService,
  },
  guards: {
    canRetry: ({ context }, params: { limit: number }) =>
      context.retryCount < params.limit,
  },
  actions: {
    notifyAdmin: ({ context }) => {
      console.warn(`[Security Alert] Вичерпано спроби входу: ${context.errorMessage}`);
    },
  },
}).createMachine({
  id: 'authentication',
  initial: 'idle',
  context: ({ input }) => ({
    session: null,
    errorMessage: null,
    retryCount: 0,
  }),
  states: {
    idle: {
      on: {
        LOGIN: {
          target: 'authenticating',
          actions: assign({
            errorMessage: () => null,
          }),
        },
      },
    },

    authenticating: {
      invoke: {
        id: 'loginActor',
        src: 'loginService',
        input: ({ event }) => {
          // Дискримінована подія: строго звужена до LOGIN
          if (event.type !== 'LOGIN') {
            throw new Error('Очікувалася подія LOGIN');
          }
          return { email: event.email, pass: event.pass };
        },
        onDone: {
          target: 'authenticated',
          actions: assign({
            session: ({ event }) => event.output,
            retryCount: () => 0,
          }),
        },
        onError: {
          target: 'failure',
          actions: assign({
            errorMessage: ({ event }) =>
              event.error instanceof Error ? event.error.message : 'Невідома помилка',
            retryCount: ({ context }) => context.retryCount + 1,
          }),
        },
      },
    },

    authenticated: {
      on: {
        LOGOUT: {
          target: 'idle',
          actions: assign({
            session: () => null,
          }),
        },
      },
    },

    failure: {
      on: {
        RETRY: [
          {
            guard: { type: 'canRetry', params: { limit: 3 } },
            target: 'idle',
          },
          {
            target: 'locked',
            actions: 'notifyAdmin',
          },
        ],
      },
    },

    locked: {
      type: 'final',
    },
  },
});

import { createActor } from 'xstate';
import { authMachine } from '../machines/authMachine';

export function initializeAuthSystem() {
  // Створення актора з обов'язковою передачею input
  const actor = createActor(authMachine, {
    input: { defaultRetryLimit: 3 },
  });

  // Підписка на переходи станів
  actor.subscribe((snapshot) => {
    console.log(`Поточний стан: ${String(snapshot.value)}`);

    // snapshot.matches() строго типізований за назвами вузлів стану!
    if (snapshot.matches('authenticated')) {
      console.log('Користувача авторизовано:', snapshot.context.session?.email);
    } else if (snapshot.matches('locked')) {
      console.error('Обліковий запис заблоковано через вичерпання спроб');
    }
  });

  actor.start();

  // Відправка строго типізованих подій
  actor.send({
    type: 'LOGIN',
    email: '[email protected]',
    pass: 'Secr3t!P@ssw0rd',
  });

  return actor;
}