Effect-TS: англійська для функціональних шаблонів програмування в TypeScript

Effect-TS — це бібліотека TypeScript для написання безпечних для типів програм виробничого рівня, що використовують функціональні шаблони програмування. Він забезпечує структурований підхід до обробки помилок, управління залежностями і контролю побічних ефектів. Словник, який наведено у цьому повідомленні, призначено для розробників ESL, які бажають вільно читати документацію Effect, брати участь у перегляді коду і пояснювати функціональні поняття англійською мовою своїм колегам.

---

Тип ефекту і Core Primitives

** Тип ефекту ** — центральна абстракція в Effect- TS, що представляє обчислення, яке може закінчитися успіхом зі значенням, зазнавати невдачі з помилкою типу або вимагати послуги від середовища; записується як Effect.Effect<Success, Error, Requirements>.

• “Кожен виклик бази даних у нашій службі обгортається у тип Effect, отже компілятор змушує нас обробляти як випадки успіху, так і всі можливі режими невдачі.” *

** succeed ** — функція, яка створює ефект, який негайно створює значення без виконання будь- яких побічних ефектів; еквівалент Promise.resolve у коді, орієнтованому на ефект.

“Ми використовуємо Effect.succeed(cachedUser), коли користувач вже знаходиться в пам’ яті, щоб уникнути потрапляння в базу даних.”

** fail ** — функція, яка створює ефект, що представляє типовану помилку; на відміну від викидання винятку, тип помилки буде відстежено у підписі типу ефекту і його слід обробляти явно.

“Коли користувача не знайдено, ми повертаємо Effect.fail(new UserNotFoundError(id)) щоб компілятор переконувався, що кожен виклик адресує цей випадок помилки.”

---

Composition

** pipe ** — функція, яка приймає значення і передає його за допомогою ряду перетворень у порядку зліва направо; це основний спосіб складання операцій з ефектами без глибинного вкладення.

“Ми використовуємо pipe для з’ єднання запиту бази даних, перевірки прав доступу і перетворення відповіді у єдиний вираз, який можна прочитати.”

** gen function ** — синтаксис, заснований на генераторі (Effect. gen), який надає вам змогу писати послідовний код ефекту за допомогою yield, що робить його схожим на async/ await, зберігаючи при цьому повний рівень безпеки типів.

• “Команда віддає перевагу стилю gen function, тому що новим членам команди його легше читати, ніж глибоко вкладені ланцюжки трубок.” *

** match ** — оператор, який обробляє як успішні, так і невдалі канали ефекту за один крок, подібно до введення команди switch у результаті.

“Ми використовуємо Effect.match для перетворення введеної помилки на код стану HTTP і тіло перед надсиланням відповіді клієнту.”

---

Обробка помилок

** catchAll ** — оператор, який захоплює будь- яку помилку у ефекті і виконує функцію відновлення, що дозволяє конвеєру продовжувати роботу, а не поширювати помилку.

• “Ми додали catchAll на межі платіжної служби, щоб записувати помилку у журнал і повертати резервну відповідь, коли постачальник платежу недоступний.” *

** теґована помилка ** — клас помилок з властивістю _tag, доступною тільки для читання, що надає змогу Effect- TS розрізняти різні типи помилок у об’ єднанні; необхідний для повної обробки помилок.

• “Використовуючи помилки з мітками, компілятор точно вказує нам, які варіанти помилок має обробляти обробник catchAll.” *

** defect ** — неочікувана, невідновлювана помилка (наприклад, помилка програмування або стан відсутності пам’ яті), яку Effect обробляє окремо від очікуваних типованих помилок; дефекти поширюються на верхній рівень і призведуть до аварії волокна.

• “Ми зарезервували дефекти для справді несподіваних умов і використовували типові помилки для будь- якої помилки, від якої викликаючий може розумно бажати відновлення.” *

---

Ін’єкція залежності

** Служба ** — інтерфейс, оголошений символом Context.Tag, який позначає можливості, необхідні коду вашого ефекту, наприклад, клієнт бази даних або відправник електронної пошти; служби надаються на межі програми.

• “Ми оголосили інтерфейс EmailService і використовували його у логіці підтвердження замовлення без імпортування будь- якої конкретної реалізації.” *

** Шар ** — опис того, як побудувати одну або декілька служб і їх залежностей; Шари складаються разом, щоб утворити повний графік залежностей вашої програми.

• “Шар виробництва підключає до мережі справжнього клієнта бази даних, а шар тестування замінює реалізацію у пам’ яті, отже тести виконуються без реального з’ єднання з базою даних.” *

** provide ** — операція, яка задовольняє вимоги до обслуговування ефекту за допомогою надання шару або конкретного значення обслуговування, створюючи ефект, який не вимагає нічого від середовища.

“Ми викликаємо Effect.provide(AppLayer) на вхідній точці програми, щоб ввести всі служби і створити самостійний ефект, який ми можемо запустити.”

---

Планування і повторні спроби

** Розклад ** — правила, які можна використовувати багаторазово, які описують, коли і як часто повторювати або повторювати спробу ефекту, зокрема, експоненційне відхилення, коливання і максимальну кількість спроб.

• “Ми додали до зовнішнього виклику API розклад з експоненційним відступом, щоб перехідні помилки мережі повторювалися до п’ яти разів, перш ніж ефект зазнає постійної невдачі.” *

---

Practice

Знайти приклад Effect- TS, який використовує як ** pipe **, так і ** Layer **. Спробуйте переписати ту ж саму логіку за допомогою стилю ** gen function **. Англійською мовою поясніть колегі, чому використання ** помилок з мітками ** замість простих винятків JavaScript робить базу коду простішою для підтримки протягом часу.

Наприклад, мова йде про те, що мова є невід’ємною частиною мови

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

Наприклад, при обговоренні «чистих функцій» проти «побічних ефектів», важливо вийти за рамки буквального перекладу. Просто кажучи “функція не має побічних ефектів” не повністю передає * переваги * такого дизайну. Замість цього, націлюйтеся на такі фрази, як «Ця функція розроблена для того, щоб бути передбачуваною і самодостатньою — мінімізуючи потенційні перешкоди з іншими частинами системи». Аналогічно, при перегляді коду, який використовує gen, пам’ятайте, що це не просто про генерування значень; це про контроль потоку обчислень в рамках ефекту. Фрази на кшталт «цей генератор забезпечує контрольований потік даних» або «Це дозволяє нам чисто управляти змінами стану» є більш ефективними, ніж просто сказати «він використовує gen.»

Крім того, обробка помилок в Effect-TS часто є місцем, де нюанси справді важливі. Концепція «підняття помилок» — поширення їх через систему ефектів — може бути неправильно інтерпретована як просто ігнорування проблем. Точніше, ми говоримо про * явно * визнання і управління потенційними невдачами в рамках контролю. Сказати « Цей метод обробляє помилку шляхом її розповсюдження » краще, ніж просто сказати « він обробляє помилку ». Замість цього, « Ми явно обробляємо цю помилку, щоб забезпечити цілісність даних » або « Розповсюджуючи цю помилку, ми зберігаємо чіткий запис того, що сталося не так », демонструє глибше розуміння. Ефективне спілкування вимагає вибору точного словника, який відображає * інтенціональність * за вибором дизайну.

Нарешті, при обговоренні таких концепцій, як Layer і Service, важливо розуміти, що вони представляють окремі рівні абстракції. « Цей шар ізолює проблеми » краще, ніж « цей шар запобігає перешкодам ». Аналогічно, опис служби як « надання абстракції для зовнішніх взаємодій » є більш точним, ніж просто сказати « вона надає інтерфейс »

Ось приклад, що демонструє gen в дії:

import * as Gen from 'effect-ts';

const addOne: Gen.Effect<Gen.State, number> = Gen.gen(err => {
  console.error(err); // Handle the error explicitly
  return 1;
});

// Example usage (simplified)
Gen.run({}, addOne).catch(err => console.log("Caught error:", err));

Цей приклад демонструє, як gen використовується для управління ефектом, включаючи потенційні помилки - ключовий аспект філософії дизайну Effect-TS і вимагає ретельного обміну інформацією про його роль в загальній архітектурі системи.