Коли звичайного TypeScript стає замало

TypeScript чудово ловить описку в полі чи хибний аргумент функції. Він не ловить того, що відбувається під час виконання: виняток глибоко в стеку, відмову стороннього API, гонку під час скасування запиту, забутий finally біля з’єднання з базою.

Типова серверна функція виглядає знайомо: приймає id, звертається до HTTP-клієнта, розбирає JSON, пише в журнал, а за помилки або кидає виняток, або повертає null. За місяць колега не знає, які винятки можливі, чи є кеш і хто відповідає за таймаут. Коментар із поясненням застаріває швидше за код.

Із зростанням системи з’являється кілька паралельних «міні-архітектур»: десь try/catch, десь власноруч зібраний об’єкт результату, десь бібліотека повторів, десь ручний AbortController. Кожен механізм лікує локальний біль, але разом вони не стають спільною мовою команди. Це як експедиція, де кожна група пакує речі за власним списком: ніхто не скаже напевно, чи є на всіх мотузка.

Питання не в тому, чи поганий TypeScript. Питання в тому, чи можна зробити поведінку програми явнішою й перевірюванішою на рівні типів, не відмовляючись від звичних Node і React. Саме тут з’являється Effect.

Що таке Effect і яку задачу він розв’язує

Effect — бібліотека й екосистема для TypeScript. Ядро дає тип обчислення, обробку помилок, впровадження залежностей, керування ресурсами та конкурентність. Навколо — Schema, Stream, Schedule, HTTP, SQL, CLI, спостережуваність і модулі для застосунків зі штучним інтелектом. Це не заміна мови, React чи Node: це спосіб організувати прикладну логіку та інфраструктурні механізми одним набором абстракцій.

Зв’язок із функційним програмуванням існує, але подавати Effect як «обов’язковий культ ФП» шкідливо. На практиці команда пише генератори (Effect.gen) у стилі, близькому до async/await, а композиція та явні типи помилок дають інженерну користь без жаргону про монади на кожному рев’ю.

Effect комплексно охоплює те, що зазвичай збирають із шматків: типізовані помилки, впровадження залежностей без прихованих синглтонів, безпечне звільнення ресурсів, таймаути й повтори, структуровану конкурентність. Окрема утиліта для повторів цього не зробить — вона не має спільної мови з вашим контейнером залежностей і схемами даних.

Програма як значення: тип Effect<A, E, R>

У звичайному коді виклик функції одразу запускає роботу. В Effect ви описуєте обчислення як значення, яке ще не виконано. Його можна передати далі, обгорнути таймаутом, поєднати з іншим обчисленням і підставити інше середовище — усе це до runPromise чи NodeRuntime.runMain.

Три параметри типу (в документації та у виводі компілятора) читаються так:

import { Effect, Schema } from "effect"

class NetworkError extends Schema.TaggedError<NetworkError>()("NetworkError", {
  message: Schema.String
}) {}

// Effect<number, NetworkError, never>
const loadScore = Effect.gen(function* () {
  const ok = Math.random() > 0.2
  if (!ok) {
    return yield* new NetworkError({ message: "upstream timeout" })
  }
  return 42
})

Порівняння зі звичними формами:

Розділення опису та виконання допомагає тестам: ви збираєте той самий граф програми, що й у проді, але підставляєте тестовий Layer. Effect не обіцяє, що зовнішній API завжди чесний. Він обіцяє, що ваш договір про помилки та залежності не сховається в неявних винятках.

Типізовані помилки замість розмитого try/catch

try/catch ловить усе підряд: і «користувача не знайдено», і описку в коді, і обрив сокета. Тип функції при цьому лишається «завжди повертає User», доки хтось не кине виняток. Очікувані бізнес-помилки та несподівані дефекти змішуються.

В Effect очікувані помилки моделюють як типізовані значення — зручно через Schema.TaggedError — і обробляють точково:

import { Effect, Schema } from "effect"

class UserNotFound extends Schema.TaggedError<UserNotFound>()("UserNotFound", {
  id: Schema.String
}) {}

class ValidationFailed extends Schema.TaggedError<ValidationFailed>()(
  "ValidationFailed",
  { message: Schema.String }
) {}

declare const fetchUser: (
  id: string
) => Effect.Effect<{ id: string; email: string }, UserNotFound | ValidationFailed>

const program = fetchUser("42").pipe(
  Effect.catchTag("UserNotFound", (e) =>
    Effect.succeed({ id: e.id, email: "[email protected]" })
  ),
  Effect.catchTag("ValidationFailed", (e) =>
    Effect.fail(e) // передаємо далі вздовж архітектури
  )
)

Помилки проходять крізь рівні архітектури як дані: контролер може перетворити UserNotFound на HTTP 404, а ValidationFailed — на 400, не вгадуючи за текстом Error.message. Повтори та запасні варіанти (Effect.retry, політика через Schedule) чіпляють до тих збоїв, які має сенс повторювати, — зазвичай це мережа, а не «запис не знайдено».

Практичний сюжет: отримати користувача з API. Можливі відсутність запису, помилка мережі та помилка перевірки тіла відповіді. У типі це видно коду, що викликає; у Promise<User> — ні.

Асинхронність, конкурентність і скасування

Promise та Effect обидва описують асинхронну роботу, але по-різному. Promise стартує в момент створення; Effect — коли його запускає середовище виконання. Promise погано описує складені політики (таймаут + повтор + скасування дочірніх задач) як єдиний тип. Effect дає комбінатори й модель структурованої конкурентності: життєвий цикл дочірніх операцій прив’язано до батьківської.

Типові задачі:

• обмежити очікування (Effect.timeout);
• повторити за тимчасового збою (Effect.retry + Schedule);
• запустити кілька запитів і дочекатися всіх або першого;
• перервати роботу, коли клієнт скасував HTTP-запит.

Під час скасування важливо не лише «перестати чекати», а й звільнити ресурси. Якщо відкрито з’єднання чи файл, фіналізатор мусить спрацювати. Тут конкурентність сходиться з керуванням ресурсами: скасування — штатний шлях, а не надія, що збирач сміття закриє сокет.

Гарантії знову чесні: Effect упорядковує ваш код. Якщо зовнішній SDK ігнорує AbortSignal, бібліотека дива не вчинить — але ви принаймні чітко бачите, де закінчується ваша відповідальність.

Сервіси та шари: залежності як частина типу

Глобальний клієнт бази чи «синглтон на модулі» ускладнює тести: доводиться підміняти імпорти, чистити стан між кейсами, пам’ятати порядок ініціалізації. Effect пропонує інший хід: сервіс — це договір, а реалізація — окремий Layer.

import { Context, Effect, Layer, Schema } from "effect"

class DbError extends Schema.TaggedError<DbError>()("DbError", {
  message: Schema.String
}) {}

export class UserRepo extends Context.Service<
  UserRepo,
  {
    findById: (
      id: string
    ) => Effect.Effect<{ id: string; email: string }, DbError>
  }
>()("myapp/UserRepo") {
  static readonly layer = Layer.effect(
    UserRepo,
    Effect.gen(function* () {
      const findById = Effect.fn("UserRepo.findById")(function* (id: string) {
        // жива реалізація: SQL, HTTP, кеш…
        return { id, email: `${id}@example.com` }
      })
      return UserRepo.of({ findById })
    })
  )

  static readonly layerTest = Layer.succeed(
    UserRepo,
    UserRepo.of({
      findById: (id) => Effect.succeed({ id, email: "[email protected]" })
    })
  )
}

const getEmail = Effect.gen(function* () {
  const repo = yield* UserRepo
  const user = yield* repo.findById("u-1")
  return user.email
})

// прод
const live = getEmail.pipe(Effect.provide(UserRepo.layer))
// тест
const test = getEmail.pipe(Effect.provide(UserRepo.layerTest))

Шари компонуються: репозиторій залежить від конфігурації та HTTP-клієнта, сервіс користувачів — від репозиторію й зовнішнього API. У типі R видно, чого бракує, доки ви не надали повний граф. Це і є впровадження залежностей без прихованої магії контейнера, що шукає все за рядками.

Schema: перевірка даних на межах системи

Типи TypeScript стираються під час компіляції. JSON від партнера, тіло HTTP-запиту, змінні оточення, відповідь мовної моделі — усе це по суті unknown, навіть якщо ви написали as User. Потрібна перевірка під час виконання, узгоджена з внутрішніми моделями.

Модуль Schema задає структуру, декодує вхід і кодує вихід. Помилка розбору стає частиною того самого каналу помилок, що й решта програми, а не окремим звіринцем, де винятки Zod живуть в одному куті, а try/catch — в іншому. (Zod чудово почувається в проєктах без Effect; див. порівняння нижче.)

import { Effect, Schema } from "effect"

const UserDto = Schema.Struct({
  id: Schema.String,
  email: Schema.String
})

type UserDto = typeof UserDto.Type

const parseUser = (input: unknown) =>
  Schema.decodeUnknown(UserDto)(input)

const program = Effect.gen(function* () {
  const raw: unknown = JSON.parse('{"id":"1","email":"[email protected]"}')
  return yield* parseUser(raw)
})

Життєвий сценарій: сервер «трохи змінив» поле або прислав число замість рядка. Схема падає явно на межі; усередину домену не протікає напіврозібраний об’єкт. Той самий підхід працює для конфігурації — у дусі матеріалу про валідацію змінних оточення в TypeScript, тільки вбудований у спільну модель Effect.

Ресурси та короткий погляд на екосистему

Файли, пули з’єднань, сокети й підписки не можна «забути» після помилки чи скасування. Effect використовує Scope і фіналізатори (Effect.acquireRelease та пов’язані API): захоплення та звільнення зв’язано так, що вихід із області видимості — зокрема через переривання — запускає очищення. Це передбачуваніше за ручний try/finally, який легко обійти раннім return в іншому шарі або загубити під час рефакторингу.

Коротко про сусідні модулі — не каталог API, а мапа, куди дивитися далі:

• Stream — потоки даних, де повільний споживач сам стримує швидке джерело (стрічки подій, посторінкове завантаження).
• Schedule — розклади повторів і періодичних задач.
• Журнали й трасування — спостереження за тим самим графом ефектів.
• HTTP / SQL / CLI / AI — прикладні пакети екосистеми v4 зі спільною версією.

Підключати модуль має сенс, коли задача вже є, а не «бо в екосистемі гарно». Експедиція не тягне каное через пустелю.

Наскрізний приклад: сервіс користувача

Спершу впізнаваний TypeScript на Promise. Потім — той самий сценарій на Effect. Задача: взяти користувача із зовнішнього API, перевірити JSON, вкластися в таймаут, за тимчасового збою повторити запит, а в тесті підмінити мережу.

Звичайний TypeScript

type User = { id: string; email: string }

class UserNotFoundError extends Error {
  constructor(readonly id: string) {
    super(`User ${id} not found`)
  }
}

async function fetchUserJson(id: string): Promise<unknown> {
  const res = await fetch(`https://api.example.com/users/${id}`)
  if (res.status === 404) throw new UserNotFoundError(id)
  if (!res.ok) throw new Error(`HTTP ${res.status}`)
  return res.json()
}

function parseUser(data: unknown): User {
  if (
    typeof data !== "object" ||
    data === null ||
    typeof (data as User).id !== "string" ||
    typeof (data as User).email !== "string"
  ) {
    throw new Error("invalid user payload")
  }
  return data as User
}

async function getUser(id: string): Promise<User> {
  const controller = new AbortController()
  const timer = setTimeout(() => controller.abort(), 2000)
  try {
    // спрощено: повтори, AbortSignal і розбір зазвичай розмазані по допоміжних функціях
    const raw = await fetchUserJson(id)
    return parseUser(raw)
  } finally {
    clearTimeout(timer)
  }
}

Інфраструктура (таймаут, повтор, перевірка, тестова підміна fetch) швидко розповзається. Договір про помилки читається лише з тексту винятків.

Той самий сценарій на Effect

import { Context, Effect, Layer, Schedule, Schema } from "effect"

class UserNotFound extends Schema.TaggedError<UserNotFound>()("UserNotFound", {
  id: Schema.String
}) {}

class NetworkError extends Schema.TaggedError<NetworkError>()("NetworkError", {
  message: Schema.String
}) {}

const User = Schema.Struct({
  id: Schema.String,
  email: Schema.String
})
type User = typeof User.Type

export class UserApi extends Context.Service<
  UserApi,
  {
    getById: (
      id: string
    ) => Effect.Effect<User, UserNotFound | NetworkError>
  }
>()("myapp/UserApi") {
  static readonly layerTest = Layer.succeed(
    UserApi,
    UserApi.of({
      getById: (id) => Effect.succeed({ id, email: "[email protected]" })
    })
  )
}

const loadUser = Effect.fn("loadUser")(function* (id: string) {
  const api = yield* UserApi
  return yield* api.getById(id).pipe(
    Effect.timeout("2 seconds"),
    Effect.retry({ times: 2, schedule: Schedule.exponential("100 millis") }),
    Effect.catchTag("TimeoutError", () =>
      Effect.fail(new NetworkError({ message: "timeout" }))
    )
  )
})

const testProgram = loadUser("u-1").pipe(Effect.provide(UserApi.layerTest))

Порівняння за осями, які ми окреслили раніше:

Для навчального CRUD виграш Effect може не окупити навчання. Для сервісу з кількома залежностями й суворими тестами — навпаки.

Як впроваджувати Effect і з чим його порівнюють

Найбільша користь — у бекенді та сервісах із багатьма зовнішніми залежностями, де вже болять тести, повтори й розрізнена обробка помилок. Впроваджувати краще поступово: новий модуль або межа API на Effect, решта — на Promise. Міст — ManagedRuntime та явні адаптери на краю (HTTP-обробник викликає runtime.runPromise(program)).

Не кожній невеликій програмі потрібен Effect. Скрипт на сто рядків, вітрина з простим CRUD, прототип на вихідні — звичайний TypeScript буде чеснішим. Складність навчання команди реальна: потрібні спільні правила (як оголошувати помилки, як різати шари, де закінчується Effect). Без домовленостей бібліотека перетворюється на звіринець стилів.

Інструменти не завжди конкурують. TanStack Query в офлайн-сценаріях розв’язує задачу UI-кешу й синхронізації — іншу, ніж Effect на сервері. Zod може лишитися на фронтенді, поки серверна частина переходить на Schema. fp-ts ближчий філософськи, але Effect цілить у прикладну «операційну» повноту (ресурси, конкурентність, шари).

Поруч за темою договорів TypeScript: обмеження узагальнених типів, tRPC і спільні типи клієнта та сервера, довге життя архітектури.

Чи варто вивчати Effect у 2026 році

Перед стартом корисні впевнений TypeScript (узагальнені типи, об’єднання, звуження типів), досвід з асинхронним кодом і розуміння, навіщо вам впровадження залежностей та перевірка на межах. Абстракції спершу незвичні: «програма як значення» і канал R потребують кількох робочих днів, а не одного туторіалу.

Пробувати Effect в наявному проєкті має сенс, якщо біль уже є: крихкі тести через синглтони, різні стилі повторів, витоки під час скасування, дірки на межі JSON. Якщо болю нема — бібліотека стане самоціллю.

Що простіше традиційними засобами: тонкі обгортки, одноразові скрипти, UI-стан на клієнті (там часто важливіші клієнтський кеш запитів чи сховище стану). Зрілість екосистеми оцінюйте за випуском v4, єдиною версією пакетів, документацією та активністю офіційного репозиторію. Сумісність зі стеком перевіряйте на малому пілоті: один сервіс, один тестовий шар, один адаптер до Express, Fastify чи Hono — і ретроспектива за два тижні.

Часті питання

Далі за темою

• Валідація змінних оточення в TypeScript
• Як обмеження узагальнених типів TypeScript запобігають помилкам
• tRPC у 2026: типобезпечний повний стек
• Офлайн у React: TanStack Query, IndexedDB і черга вихідних
• Як проєктувати систему, яка проживе 10 років
• Як проєктувати сучасну корпоративну облікову систему в 2026 році
• 7 прихованих вразливостей у Node.js-застосунках

Зовнішні джерела: офіційна документація, вихідний код на GitHub, міграція v3 → v4.

Висновок

Effect корисний не як добірка функцій із короткими іменами, а як спосіб явно описати помилки, залежності, ресурси та конкурентність. Цінність особливо помітна там, де складність застосунку вже не дозволяє надійно тримати ці механізми розрізненими рішеннями.

Цього тижня: оберіть один сервіс із зовнішнім API, опишіть його помилки тегами, винесіть клієнт у Context.Service, напишіть layerTest і проженіть один сценарій без моку глобального fetch. Якщо команді стало легше читати договір — експедицію зібрано правильно; якщо ні, залиште Promise і зафіксуйте, якого болю ще бракувало для зміни інструмента.