Функції твердження (asserts) та предикати типів (Type Guards)

+-------------------------------------------------------------------------+
|                  МЕХАНІЗМИ ЗВУЖЕННЯ НЕПЕРЕВІРЕНИХ ДАНИХ                 |
+-------------------------------------------------------------------------+
| [Вхід: rawPayload: unknown]                                             |
+-------------------------------------------------------------------------+
       |
       +------------------------------------+
       |                                    |
       v (Type Guard: Галуження)            v (Assertion Function: Інваріант)
+---------------------------------+  +------------------------------------+
| if (isUser(rawPayload)) {       |  | assertIsUser(rawPayload);          |
|   // rawPayload звужено до User |  | // rawPayload звужено до User      |
|   // всередині цього блоку      |  | // прямо в поточному скоупі!       |
| } else {                        |  |                                    |
|   // обробка помилки            |  | (При збої — негайний throw)        |
| }                               |  |                                    |
+---------------------------------+  +------------------------------------+

Механіка звуження через asserts:
function process(input: unknown) {
  // input має тип: unknown
  
  assertIsNonNullObject(input);
  // input звужено до: Record<string, unknown>
  
  assertHasProperty(input, 'id');
  // input звужено до: Record<string, unknown> & { id: unknown }
  
  assertIsString(input.id);
  // input.id звужено до: string!
  
  console.log(input.id.toUpperCase()); // Абсолютно безпечно!
}

/**
 * Стверджує істинність довільної логічної умови.
 */
export function assert(condition: unknown, message?: string): asserts condition {
  if (!condition) {
    throw new Error(message ?? '[InvariantViolation] Умова твердження хибна');
  }
}

/**
 * Стверджує, що значення визначене і не є null або undefined.
 */
export function assertDefined<T>(
  val: T,
  message?: string
): asserts val is NonNullable<T> {
  if (val === null || val === undefined) {
    throw new TypeError(
      message ?? `[InvariantViolation] Очікувалося визначене значення, отримано: ${String(val)}`
    );
  }
}

/**
 * Стверджує, що значення є непорожнім об'єктом (не null і не масив).
 */
export function assertIsObject(
  val: unknown,
  message?: string
): asserts val is Record<string, unknown> {
  if (typeof val !== 'object' || val === null || Array.isArray(val)) {
    throw new TypeError(
      message ?? `[InvariantViolation] Очікувався об'єкт, отримано: ${typeof val}`
    );
  }
}

import { assert, assertIsObject, assertDefined } from '../utils/assertions';

export interface UserProfile {
  readonly id: string;
  readonly email: string;
  readonly role: 'admin' | 'editor' | 'viewer';
  readonly age?: number;
}

/**
 * Користувацький предикат типу (Type Guard).
 */
export function isUserProfile(val: unknown): val is UserProfile {
  try {
    assertIsUserProfile(val);
    return true;
  } catch {
    return false;
  }
}

/**
 * Функція твердження доменного контракту (Assertion Function).
 */
export function assertIsUserProfile(val: unknown): asserts val is UserProfile {
  assertIsObject(val, "Профіль користувача повинен бути непорожнім об'єктом");

  assert(
    typeof val.id === 'string' && val.id.trim().length > 0,
    'Ідентифікатор користувача id зобов’язаний бути непорожнім рядком'
  );

  assert(
    typeof val.email === 'string' && val.email.includes('@'),
    'Email має некоректний формат'
  );

  assert(
    val.role === 'admin' || val.role === 'editor' || val.role === 'viewer',
    `Неприпустима роль: ${String(val.role)}`
  );

  if ('age' in val && val.age !== undefined) {
    assert(
      typeof val.age === 'number' && Number.isInteger(val.age) && val.age >= 0,
      'Вік age зобов’язаний бути невід’ємним цілим числом'
    );
  }
}

// Приклад використання в контролері:
export function handleUpdateUser(rawBody: unknown): void {
  // До перевірки rawBody має тип unknown
  assertIsUserProfile(rawBody);

  // Прямо тут rawBody СИНХРОННО звужено до UserProfile!
  console.log(`Оновлення профілю: ${rawBody.id}, роль: ${rawBody.role.toUpperCase()}`);
}

/**
 * Типобезпечний предикат для виключення null та undefined з масивів.
 */
export function isNonNullable<T>(val: T): val is NonNullable<T> {
  return val !== null && val !== undefined;
}

// Приклад роботи:
const rawList: ReadonlyArray<string | null | undefined> = ['alpha', null, 'beta', undefined];

// ❌ ПРОБЛЕМА: filter(Boolean) залишає тип (string | null | undefined)[]
const badFiltered = rawList.filter(Boolean);

// ✅ РІШЕННЯ: filter(isNonNullable) повертає чистий string[]
const safeList: ReadonlyArray<string> = rawList.filter(isNonNullable);