AudiobookRepository bookRepo   = new JdbcAudiobookRepository(cm);
AuthorRepository    authorRepo = new JdbcAuthorRepository(cm);
GenreRepository     genreRepo  = new JdbcGenreRepository(cm);
RatingRepository    ratingRepo = new JdbcRatingRepository(cm);

// Завантаження однієї книги з усіма пов'язаними даними
Audiobook book = bookRepo.findById(bookId).orElseThrow();

// Три послідовних блокуючих виклики
Author author = authorRepo.findById(book.getAuthorId()).orElseThrow();  // 50ms
Genre  genre  = genreRepo.findById(book.getGenreId()).orElseThrow();    // 30ms
Double rating = ratingRepo.getAverageRating(bookId);                     // 80ms

// Загальний час: 50 + 30 + 80 = 160ms

authorRepo.findById():
  1. Отримати Connection з пулу           (1-5ms)
  2. Підготувати PreparedStatement        (1ms)
  3. Відправити SQL до БД                 (network roundtrip)
  4. Чекати на виконання SELECT           (БД виконує запит)
  5. Отримати ResultSet                   (network roundtrip)
  6. Змаппити рядок у об'єкт Author       (1ms)
  7. Закрити ресурси, повернути Connection (1ms)
  → Загалом: ~50ms

Ідеальний сценарій (паралельне виконання):
  Thread-1: authorRepo.findById()  → 50ms
  Thread-2: genreRepo.findById()   → 30ms  (виконується одночасно!)
  Thread-3: ratingRepo.getAverage() → 80ms  (виконується одночасно!)
  
  Загальний час: max(50, 30, 80) = 80ms
  Прискорення: 160ms / 80ms = 2× швидше

// Потік зупиняється тут і чекає на результат
Author author = authorRepo.findById(id).orElseThrow();
// Продовження виконання лише після отримання результату
System.out.println(author.getFirstName());

// Потік НЕ зупиняється — метод повертає "обіцянку" результату
CompletableFuture<Author> futureAuthor = authorRepo.findByIdAsync(id);

// Потік може продовжувати іншу роботу
System.out.println("Запит відправлено, продовжуємо роботу...");

// Коли результат потрібен — чекаємо на завершення
Author author = futureAuthor.join(); // блокується лише тут
System.out.println(author.getFirstName());

CompletableFuture<String> future = CompletableFuture.supplyAsync(() -> {
    // Цей код виконується в окремому потоці
    Thread.sleep(1000);
    return "Результат";
});

// Основний потік продовжує роботу
System.out.println("Обчислення запущено...");

// Коли потрібен результат:
String result = future.join(); // чекає завершення
System.out.println(result); // "Результат"

// Всі ці методи блокують потік до завершення
Connection conn = dataSource.getConnection();        // блокується
PreparedStatement stmt = conn.prepareStatement(sql); // блокується
ResultSet rs = stmt.executeQuery();                  // блокується ← найдовше
while (rs.next()) { ... }                            // блокується на кожній ітерації

package com.example.audiobook.repository.async;

import java.util.List;
import java.util.concurrent.CompletableFuture;

/**
 * Асинхронний контракт репозиторію.
 * <p>
 * Всі методи повертають {@link CompletableFuture} — обіцянку результату,
 * що буде обчислений у майбутньому в окремому потоці.
 * <p>
 * Клієнтський код може:
 * <ul>
 *   <li>Запустити кілька операцій паралельно без блокування</li>
 *   <li>Комбінувати результати через {@code thenCombine}, {@code allOf}</li>
 *   <li>Обробляти помилки через {@code exceptionally}, {@code handle}</li>
 * </ul>
 *
 * @param <T>  тип доменної сутності
 * @param <ID> тип первинного ключа
 */
public interface AsyncRepository<T, ID> {

    /**
     * Асинхронно знаходить сутність за первинним ключем.
     * <p>
     * Запит виконується у пулі потоків. Метод повертається негайно,
     * не чекаючи на завершення SQL-запиту.
     *
     * @param id первинний ключ
     * @return CompletableFuture з Optional[T] — завершиться після виконання SELECT
     */
    CompletableFuture<java.util.Optional<T>> findByIdAsync(ID id);

    /**
     * Асинхронно повертає всі сутності.
     * <p>
     * Для великих таблиць рекомендується використовувати пагінацію
     * або streaming (реалізується у підкласах).
     *
     * @return CompletableFuture зі списком сутностей
     */
    CompletableFuture<List<T>> findAllAsync();

    /**
     * Асинхронно зберігає нову сутність.
     * <p>
     * INSERT виконується у пулі потоків. CompletableFuture завершується
     * після успішного commit або з виключенням при помилці.
     *
     * @param entity сутність для збереження
     * @return CompletableFuture<Void> — завершиться після INSERT
     */
    CompletableFuture<Void> saveAsync(T entity);

    /**
     * Асинхронно оновлює існуючу сутність.
     *
     * @param entity сутність з оновленими даними
     * @return CompletableFuture<Void> — завершиться після UPDATE
     */
    CompletableFuture<Void> updateAsync(T entity);

    /**
     * Асинхронно видаляє сутність за первинним ключем.
     *
     * @param id первинний ключ
     * @return CompletableFuture<Boolean> — true якщо сутність була видалена
     */
    CompletableFuture<Boolean> deleteByIdAsync(ID id);

    /**
     * Асинхронно повертає кількість сутностей.
     *
     * @return CompletableFuture<Long> з кількістю записів
     */
    CompletableFuture<Long> countAsync();

    /**
     * Асинхронно перевіряє існування сутності.
     *
     * @param id первинний ключ
     * @return CompletableFuture<Boolean> — true якщо сутність існує
     */
    CompletableFuture<Boolean> existsByIdAsync(ID id);
}

package com.example.audiobook.repository.async;

import com.example.audiobook.repository.Repository;

import java.util.List;
import java.util.Optional;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;

/**
 * Абстрактна реалізація {@link AsyncRepository}, що обгортає
 * синхронний {@link Repository} і виконує всі операції асинхронно
 * через {@link ExecutorService}.
 * <p>
 * <b>Архітектурне рішення:</b> Замість дублювання JDBC-логіки,
 * цей клас делегує виклики до існуючого синхронного репозиторію
 * і обгортає результати у {@link CompletableFuture}.
 * <p>
 * <b>Управління пулом потоків:</b>
 * <ul>
 *   <li>За замовчуванням використовується {@code ForkJoinPool.commonPool()}
 *       (спільний пул для всіх {@code CompletableFuture.supplyAsync()})</li>
 *   <li>Можна передати власний {@link ExecutorService} через конструктор
 *       для контролю розміру пулу та політики черги</li>
 *   <li>Рекомендований розмір пулу: кількість ядер CPU × 2
 *       (оскільки операції I/O-bound, а не CPU-bound)</li>
 * </ul>
 *
 * @param <T>  тип доменної сутності
 * @param <ID> тип первинного ключа
 */
public abstract class AbstractAsyncRepository<T, ID> implements AsyncRepository<T, ID> {

    /**
     * Синхронний репозиторій, до якого делегуються всі операції.
     * Підкласи передають конкретну реалізацію (JdbcAuthorRepository тощо).
     */
    protected final Repository<T, ID> syncRepository;

    /**
     * Пул потоків для виконання асинхронних операцій.
     * Якщо null — використовується ForkJoinPool.commonPool().
     */
    protected final ExecutorService executor;

    /**
     * Створює асинхронний репозиторій з власним пулом потоків.
     *
     * @param syncRepository синхронний репозиторій для делегування
     * @param executor       пул потоків (або null для commonPool)
     */
    protected AbstractAsyncRepository(Repository<T, ID> syncRepository,
                                      ExecutorService executor) {
        this.syncRepository = syncRepository;
        this.executor = executor;
    }

    /**
     * Створює асинхронний репозиторій з ForkJoinPool.commonPool().
     * Зручний конструктор для простих випадків.
     *
     * @param syncRepository синхронний репозиторій для делегування
     */
    protected AbstractAsyncRepository(Repository<T, ID> syncRepository) {
        this(syncRepository, null);
    }

    // =========================================================
    // Реалізація AsyncRepository через делегування
    // =========================================================

    /**
     * Асинхронно знаходить сутність за ID.
     * <p>
     * Виконує {@code syncRepository.findById(id)} у пулі потоків.
     * Основний потік не блокується — метод повертається негайно.
     */
    @Override
    public CompletableFuture<Optional<T>> findByIdAsync(ID id) {
        return runAsync(() -> syncRepository.findById(id));
    }

    /**
     * Асинхронно повертає всі сутності.
     * <p>
     * <b>Увага:</b> Для великих таблиць (>10000 рядків) цей метод
     * може спричинити OutOfMemoryError. Використовуйте пагінацію
     * або streaming для великих датасетів.
     */
    @Override
    public CompletableFuture<List<T>> findAllAsync() {
        return runAsync(() -> syncRepository.findAll());
    }

    /**
     * Асинхронно зберігає нову сутність.
     * <p>
     * INSERT виконується у пулі потоків. CompletableFuture завершується
     * з {@code null} (Void) після успішного збереження або з виключенням.
     */
    @Override
    public CompletableFuture<Void> saveAsync(T entity) {
        return runAsync(() -> {
            syncRepository.save(entity);
            return null; // Void
        });
    }

    /**
     * Асинхронно оновлює існуючу сутність.
     */
    @Override
    public CompletableFuture<Void> updateAsync(T entity) {
        return runAsync(() -> {
            syncRepository.update(entity);
            return null;
        });
    }

    /**
     * Асинхронно видаляє сутність за ID.
     */
    @Override
    public CompletableFuture<Boolean> deleteByIdAsync(ID id) {
        return runAsync(() -> syncRepository.deleteById(id));
    }

    /**
     * Асинхронно повертає кількість сутностей.
     */
    @Override
    public CompletableFuture<Long> countAsync() {
        return runAsync(() -> syncRepository.count());
    }

    /**
     * Асинхронно перевіряє існування сутності.
     */
    @Override
    public CompletableFuture<Boolean> existsByIdAsync(ID id) {
        return runAsync(() -> syncRepository.existsById(id));
    }

    // =========================================================
    // Утилітний метод для запуску асинхронних операцій
    // =========================================================

    /**
     * Виконує {@link java.util.function.Supplier} у пулі потоків
     * і повертає {@link CompletableFuture} з результатом.
     * <p>
     * Якщо {@code executor} заданий — використовує його,
     * інакше — {@code ForkJoinPool.commonPool()}.
     *
     * @param supplier лямбда, що виконує синхронну операцію
     * @param <R>      тип результату
     * @return CompletableFuture з результатом виконання
     */
    protected <R> CompletableFuture<R> runAsync(java.util.function.Supplier<R> supplier) {
        if (executor != null) {
            return CompletableFuture.supplyAsync(supplier, executor);
        } else {
            return CompletableFuture.supplyAsync(supplier);
        }
    }

    /**
     * Закриває пул потоків (якщо він був переданий через конструктор).
     * <p>
     * <b>Важливо:</b> Викликайте цей метод при завершенні роботи додатку,
     * інакше потоки залишаться активними і JVM не завершиться.
     * <p>
     * Якщо використовується {@code ForkJoinPool.commonPool()} (executor == null),
     * цей метод нічого не робить — commonPool керується JVM.
     */
    public void shutdown() {
        if (executor != null) {
            executor.shutdown();
        }
    }
}

package com.example.audiobook.repository.async;

import com.example.audiobook.domain.Author;
import com.example.audiobook.repository.AuthorRepository;

import java.util.List;
import java.util.UUID;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutorService;

/**
 * Асинхронна реалізація {@link AuthorRepository}.
 * <p>
 * Обгортає синхронний {@link com.example.audiobook.repository.jdbc.JdbcAuthorRepository}
 * і виконує всі операції асинхронно через {@link ExecutorService}.
 * <p>
 * Додає асинхронні версії специфічних методів:
 * {@link #findByLastNameAsync(String)}, {@link #findByFullNameAsync(String, String)}.
 */
public class AsyncAuthorRepository extends AbstractAsyncRepository<Author, UUID> {

    /**
     * Синхронний репозиторій, приведений до специфічного типу
     * для доступу до методів {@link AuthorRepository}.
     */
    private final AuthorRepository authorRepository;

    /**
     * Створює асинхронний репозиторій авторів з власним пулом потоків.
     *
     * @param authorRepository синхронний JdbcAuthorRepository
     * @param executor         пул потоків для асинхронних операцій
     */
    public AsyncAuthorRepository(AuthorRepository authorRepository,
                                 ExecutorService executor) {
        super(authorRepository, executor);
        this.authorRepository = authorRepository;
    }

    /**
     * Створює асинхронний репозиторій з ForkJoinPool.commonPool().
     */
    public AsyncAuthorRepository(AuthorRepository authorRepository) {
        this(authorRepository, null);
    }

    // =========================================================
    // Асинхронні версії специфічних методів AuthorRepository
    // =========================================================

    /**
     * Асинхронно знаходить авторів за частиною прізвища.
     * <p>
     * Виконує {@code authorRepository.findByLastName()} у пулі потоків.
     * Корисно для автодоповнення у пошуковому полі — не блокує UI-потік.
     *
     * @param lastNamePart підрядок прізвища (регістр-незалежний)
     * @return CompletableFuture зі списком знайдених авторів
     */
    public CompletableFuture<List<Author>> findByLastNameAsync(String lastNamePart) {
        return runAsync(() -> authorRepository.findByLastName(lastNamePart));
    }

    /**
     * Асинхронно знаходить автора за точним прізвищем та ім'ям.
     *
     * @param lastName  прізвище (точний збіг)
     * @param firstName ім'я (точний збіг)
     * @return CompletableFuture з Optional[Author]
     */
    public CompletableFuture<java.util.Optional<Author>> findByFullNameAsync(
            String lastName, String firstName) {
        return runAsync(() -> authorRepository.findByFullName(lastName, firstName));
    }
}

package com.example.audiobook.repository.async;

import com.example.audiobook.domain.Genre;
import com.example.audiobook.repository.GenreRepository;

import java.util.UUID;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutorService;

/**
 * Асинхронна реалізація {@link GenreRepository}.
 */
public class AsyncGenreRepository extends AbstractAsyncRepository<Genre, UUID> {

    private final GenreRepository genreRepository;

    public AsyncGenreRepository(GenreRepository genreRepository, ExecutorService executor) {
        super(genreRepository, executor);
        this.genreRepository = genreRepository;
    }

    public AsyncGenreRepository(GenreRepository genreRepository) {
        this(genreRepository, null);
    }

    /**
     * Асинхронно знаходить жанр за точною назвою.
     */
    public CompletableFuture<java.util.Optional<Genre>> findByNameAsync(String name) {
        return runAsync(() -> genreRepository.findByName(name));
    }
}

package com.example.audiobook.repository.async;

import com.example.audiobook.domain.Audiobook;
import com.example.audiobook.repository.AudiobookRepository;

import java.math.BigDecimal;
import java.util.List;
import java.util.UUID;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutorService;

/**
 * Асинхронна реалізація {@link AudiobookRepository}.
 */
public class AsyncAudiobookRepository extends AbstractAsyncRepository<Audiobook, UUID> {

    private final AudiobookRepository audiobookRepository;

    public AsyncAudiobookRepository(AudiobookRepository audiobookRepository,
                                    ExecutorService executor) {
        super(audiobookRepository, executor);
        this.audiobookRepository = audiobookRepository;
    }

    public AsyncAudiobookRepository(AudiobookRepository audiobookRepository) {
        this(audiobookRepository, null);
    }

    /**
     * Асинхронно знаходить аудіокниги заданого автора.
     */
    public CompletableFuture<List<Audiobook>> findByAuthorIdAsync(UUID authorId) {
        return runAsync(() -> audiobookRepository.findByAuthorId(authorId));
    }

    /**
     * Асинхронно знаходить аудіокниги заданого жанру.
     */
    public CompletableFuture<List<Audiobook>> findByGenreNameAsync(String genreName) {
        return runAsync(() -> audiobookRepository.findByGenreName(genreName));
    }

    /**
     * Асинхронно знаходить аудіокниги з ціною не більше заданої.
     */
    public CompletableFuture<List<Audiobook>> findByMaxPriceAsync(BigDecimal maxPrice) {
        return runAsync(() -> audiobookRepository.findByMaxPrice(maxPrice));
    }
}

package com.example.audiobook;

import com.example.audiobook.db.ConnectionManager;
import com.example.audiobook.domain.Author;
import com.example.audiobook.domain.Audiobook;
import com.example.audiobook.domain.Genre;
import com.example.audiobook.repository.async.*;
import com.example.audiobook.repository.jdbc.*;
import com.example.audiobook.repository.strategy.SqlStrategyFactory;

import java.util.UUID;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;

public class AsyncDemo {

    public static void main(String[] args) {
        ConnectionManager cm = ConnectionManager.forH2("./data/audiobook_db");
        var factory = SqlStrategyFactory.forH2();

        // Створюємо пул потоків: CPU_CORES × 2 для I/O-операцій
        int poolSize = Runtime.getRuntime().availableProcessors() * 2;
        ExecutorService executor = Executors.newFixedThreadPool(poolSize);

        // Синхронні репозиторії
        var syncAuthorRepo    = new JdbcAuthorRepository(cm, factory.authorStrategy());
        var syncGenreRepo     = new JdbcGenreRepository(cm, factory.genreStrategy());
        var syncAudiobookRepo = new JdbcAudiobookRepository(cm, factory.audiobookStrategy());

        // Асинхронні обгортки
        var asyncAuthorRepo    = new AsyncAuthorRepository(syncAuthorRepo, executor);
        var asyncGenreRepo     = new AsyncGenreRepository(syncGenreRepo, executor);
        var asyncAudiobookRepo = new AsyncAudiobookRepository(syncAudiobookRepo, executor);

        try {
            demonstrateSequentialVsParallel(
                asyncAuthorRepo, asyncGenreRepo, asyncAudiobookRepo
            );
        } finally {
            executor.shutdown();
            cm.close();
        }
    }

    /**
     * Порівняння послідовного та паралельного виконання.
     */
    static void demonstrateSequentialVsParallel(
            AsyncAuthorRepository authorRepo,
            AsyncGenreRepository genreRepo,
            AsyncAudiobookRepository audiobookRepo) {

        UUID bookId   = UUID.fromString("..."); // ID існуючої книги
        UUID authorId = UUID.fromString("...");
        UUID genreId  = UUID.fromString("...");

        System.out.println("=== Послідовне виконання (синхронний стиль) ===");
        long startSeq = System.currentTimeMillis();

        // Послідовні виклики — кожен чекає на попередній
        Author author = authorRepo.findByIdAsync(authorId).join();  // 50ms
        Genre  genre  = genreRepo.findByIdAsync(genreId).join();    // 30ms
        Audiobook book = audiobookRepo.findByIdAsync(bookId).join(); // 40ms

        long endSeq = System.currentTimeMillis();
        System.out.println("Час виконання: " + (endSeq - startSeq) + "ms");
        System.out.println("Завантажено: " + author.getFirstName() + ", "
                         + genre.getName() + ", " + book.getTitle());

        System.out.println("\n=== Паралельне виконання ===");
        long startPar = System.currentTimeMillis();

        // Запускаємо всі три запити ОДНОЧАСНО — не чекаємо на завершення
        CompletableFuture<Author>    futureAuthor = authorRepo.findByIdAsync(authorId)
            .thenApply(opt -> opt.orElseThrow());
        CompletableFuture<Genre>     futureGenre  = genreRepo.findByIdAsync(genreId)
            .thenApply(opt -> opt.orElseThrow());
        CompletableFuture<Audiobook> futureBook   = audiobookRepo.findByIdAsync(bookId)
            .thenApply(opt -> opt.orElseThrow());

        // Чекаємо завершення ВСІХ трьох запитів
        CompletableFuture.allOf(futureAuthor, futureGenre, futureBook).join();

        // Отримуємо результати (вони вже готові — join() не блокується)
        Author authorPar = futureAuthor.join();
        Genre  genrePar  = futureGenre.join();
        Audiobook bookPar = futureBook.join();

        long endPar = System.currentTimeMillis();
        System.out.println("Час виконання: " + (endPar - startPar) + "ms");
        System.out.println("Завантажено: " + authorPar.getFirstName() + ", "
                         + genrePar.getName() + ", " + bookPar.getTitle());

        System.out.println("\n=== Прискорення ===");
        double speedup = (double)(endSeq - startSeq) / (endPar - startPar);
        System.out.printf("Паралельне виконання у %.2f× швидше\n", speedup);
    }
}

/**
 * Завантажує книгу за ID, потім знаходить всі інші книги того ж автора.
 * <p>
 * Операції виконуються послідовно (друга залежить від результату першої),
 * але асинхронно — основний потік не блокується.
 */
public CompletableFuture<List<Audiobook>> findRelatedBooks(UUID bookId) {
    return asyncAudiobookRepo.findByIdAsync(bookId)
        .thenCompose(optBook -> {
            // Цей блок виконується після завершення findByIdAsync
            Audiobook book = optBook.orElseThrow();
            UUID authorId = book.getAuthorId();
            
            // Запускаємо другий асинхронний запит
            return asyncAudiobookRepo.findByAuthorIdAsync(authorId);
        });
    // Повертає CompletableFuture<List<Audiobook>> — результат другого запиту
}

// Використання:
CompletableFuture<List<Audiobook>> futureRelated = findRelatedBooks(bookId);
List<Audiobook> relatedBooks = futureRelated.join(); // чекаємо завершення обох запитів

// ❌ НЕПРАВИЛЬНО — повертає CompletableFuture<CompletableFuture<List<Audiobook>>>
CompletableFuture<CompletableFuture<List<Audiobook>>> nested = 
    asyncAudiobookRepo.findByIdAsync(bookId)
        .thenApply(optBook -> {
            Audiobook book = optBook.orElseThrow();
            return asyncAudiobookRepo.findByAuthorIdAsync(book.getAuthorId());
        });

// ✅ ПРАВИЛЬНО — повертає CompletableFuture<List<Audiobook>>
CompletableFuture<List<Audiobook>> flat = 
    asyncAudiobookRepo.findByIdAsync(bookId)
        .thenCompose(optBook -> {
            Audiobook book = optBook.orElseThrow();
            return asyncAudiobookRepo.findByAuthorIdAsync(book.getAuthorId());
        });

/**
 * DTO для відображення автора зі статистикою.
 */
public record AuthorWithStats(
    Author author,
    long bookCount,
    double averageRating
) {}

/**
 * Завантажує автора та його статистику паралельно.
 * <p>
 * Два запити виконуються одночасно, результати комбінуються
 * після завершення обох.
 */
public CompletableFuture<AuthorWithStats> getAuthorWithStats(UUID authorId) {
    // Запит 1: завантажити автора
    CompletableFuture<Author> futureAuthor = 
        asyncAuthorRepo.findByIdAsync(authorId)
            .thenApply(opt -> opt.orElseThrow());

    // Запит 2: порахувати книги автора (паралельно з запитом 1)
    CompletableFuture<Long> futureBookCount = 
        asyncAudiobookRepo.findByAuthorIdAsync(authorId)
            .thenApply(List::size)
            .thenApply(Long::valueOf);

    // Запит 3: середній рейтинг (паралельно з 1 і 2)
    CompletableFuture<Double> futureRating = 
        asyncRatingRepo.getAverageRatingForAuthor(authorId);

    // Комбінуємо результати після завершення ВСІХ трьох запитів
    return futureAuthor
        .thenCombine(futureBookCount, (author, count) -> 
            new Object[] { author, count }) // проміжний результат
        .thenCombine(futureRating, (arr, rating) -> 
            new AuthorWithStats((Author) arr[0], (Long) arr[1], rating));
}

// Використання:
AuthorWithStats stats = getAuthorWithStats(authorId).join();
System.out.println(stats.author().getFirstName() + ": " 
                 + stats.bookCount() + " книг, рейтинг " + stats.averageRating());

public CompletableFuture<AuthorWithStats> getAuthorWithStats(UUID authorId) {
    CompletableFuture<Author> futureAuthor = 
        asyncAuthorRepo.findByIdAsync(authorId)
            .thenApply(opt -> opt.orElseThrow());

    CompletableFuture<Long> futureBookCount = 
        asyncAudiobookRepo.findByAuthorIdAsync(authorId)
            .thenApply(books -> (long) books.size());

    CompletableFuture<Double> futureRating = 
        asyncRatingRepo.getAverageRatingForAuthor(authorId);

    // Чекаємо завершення всіх трьох
    return CompletableFuture.allOf(futureAuthor, futureBookCount, futureRating)
        .thenApply(v -> new AuthorWithStats(
            futureAuthor.join(),   // вже готовий — join() не блокується
            futureBookCount.join(),
            futureRating.join()
        ));
}

/**
 * Завантажує автора за ID з fallback на значення за замовчуванням.
 * <p>
 * Якщо автор не знайдений або виникла помилка БД — повертає
 * "невідомого автора" замість виключення.
 */
public CompletableFuture<Author> findAuthorOrDefault(UUID authorId) {
    return asyncAuthorRepo.findByIdAsync(authorId)
        .thenApply(opt -> opt.orElseThrow(() -> 
            new IllegalArgumentException("Автор не знайдений")))
        .exceptionally(ex -> {
            // Цей блок виконується лише якщо виникло виключення
            System.err.println("Помилка завантаження автора: " + ex.getMessage());
            
            // Повертаємо fallback-значення
            return new Author("Невідомий", "Автор");
        });
}

// Використання:
Author author = findAuthorOrDefault(invalidId).join();
// Якщо invalidId не існує → повертає Author("Невідомий", "Автор")

/**
 * Завантажує автора та логує результат (успіх або помилку).
 * <p>
 * {@code handle} викликається завжди — незалежно від того,
 * завершився CompletableFuture успішно чи з виключенням.
 */
public CompletableFuture<Author> findAuthorWithLogging(UUID authorId) {
    return asyncAuthorRepo.findByIdAsync(authorId)
        .thenApply(opt -> opt.orElseThrow())
        .handle((author, ex) -> {
            if (ex != null) {
                // Виникло виключення
                System.err.println("❌ Помилка: " + ex.getMessage());
                return new Author("Fallback", "Author");
            } else {
                // Успішне завершення
                System.out.println("✓ Завантажено: " + author.getFirstName());
                return author;
            }
        });
}

// Синхронний Unit of Work (стаття 16)
UnitOfWork uow = new JdbcUnitOfWork(cm);
try {
    Author author = new Author("Тарас", "Шевченко");
    Genre  genre  = new Genre("Поезія");
    Audiobook book = new Audiobook("Кобзар", author, genre);

    uow.registerNew(author);
    uow.registerNew(genre);
    uow.registerNew(book);

    uow.commit(); // BEGIN; INSERT authors; INSERT genres; INSERT audiobooks; COMMIT
} catch (Exception e) {
    uow.rollback();
    throw e;
}

/**
 * Асинхронна підготовка даних + синхронний commit.
 * <p>
 * Завантажуємо автора та жанр паралельно (асинхронно),
 * потім створюємо книгу та зберігаємо все в одній транзакції (синхронно).
 */
public CompletableFuture<Void> createAudiobookAsync(
        String title, UUID authorId, UUID genreId) {

    // Крок 1: Паралельно завантажити автора та жанр (асинхронно)
    CompletableFuture<Author> futureAuthor = 
        asyncAuthorRepo.findByIdAsync(authorId)
            .thenApply(opt -> opt.orElseThrow());

    CompletableFuture<Genre> futureGenre = 
        asyncGenreRepo.findByIdAsync(genreId)
            .thenApply(opt -> opt.orElseThrow());

    // Крок 2: Після завершення обох — створити книгу та зберегти (синхронно)
    return CompletableFuture.allOf(futureAuthor, futureGenre)
        .thenApply(v -> {
            Author author = futureAuthor.join();
            Genre  genre  = futureGenre.join();

            // Тут ми у пулі потоків, але виконуємо синхронний код
            UnitOfWork uow = new JdbcUnitOfWork(connectionManager);
            try {
                Audiobook book = new Audiobook(title, author, genre);
                uow.registerNew(book);
                uow.commit(); // ← синхронний виклик у потоці пулу
                return null; // Void
            } catch (Exception e) {
                uow.rollback();
                throw new RuntimeException(e);
            }
        });
}

// Використання:
createAudiobookAsync("Кобзар", authorId, genreId)
    .thenRun(() -> System.out.println("Книга створена"))
    .exceptionally(ex -> {
        System.err.println("Помилка: " + ex.getMessage());
        return null;
    });

package com.example.audiobook.persistence.async;

import com.example.audiobook.persistence.UnitOfWork;

import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutorService;

/**
 * Асинхронна обгортка над {@link UnitOfWork}.
 * <p>
 * Методи реєстрації ({@code registerNew}, {@code registerDirty}) виконуються
 * синхронно (вони лише додають об'єкти до списків — без SQL).
 * <p>
 * {@link #commitAsync()} виконує всі SQL-операції асинхронно в одному потоці,
 * гарантуючи транзакційну цілісність.
 */
public class AsyncUnitOfWork {

    private final UnitOfWork syncUnitOfWork;
    private final ExecutorService executor;

    public AsyncUnitOfWork(UnitOfWork syncUnitOfWork, ExecutorService executor) {
        this.syncUnitOfWork = syncUnitOfWork;
        this.executor = executor;
    }

    /**
     * Реєструє новий об'єкт (синхронно — без SQL).
     * Метод не блокується — просто додає об'єкт до списку.
     */
    public void registerNew(Object entity) {
        syncUnitOfWork.registerNew(entity);
    }

    /**
     * Реєструє змінений об'єкт (синхронно).
     */
    public void registerDirty(Object entity) {
        syncUnitOfWork.registerDirty(entity);
    }

    /**
     * Реєструє видалений об'єкт (синхронно).
     */
    public void registerDeleted(Object entity) {
        syncUnitOfWork.registerDeleted(entity);
    }

    /**
     * Асинхронно фіксує всі зміни в одній JDBC-транзакції.
     * <p>
     * Всі SQL-операції (INSERT, UPDATE, DELETE) виконуються
     * послідовно в одному потоці пулу, використовуючи одне Connection.
     * Це гарантує транзакційну цілісність.
     *
     * @return CompletableFuture<Void> — завершується після COMMIT або з виключенням
     */
    public CompletableFuture<Void> commitAsync() {
        return CompletableFuture.runAsync(() -> {
            // Цей блок виконується в одному потоці пулу
            syncUnitOfWork.commit(); // BEGIN; INSERT...; UPDATE...; DELETE...; COMMIT
        }, executor);
    }

    /**
     * Відміняє всі незафіксовані зміни (синхронно — без SQL).
     */
    public void rollback() {
        syncUnitOfWork.rollback();
    }
}

public CompletableFuture<Void> createComplexScenarioAsync() {
    AsyncUnitOfWork asyncUow = new AsyncUnitOfWork(
        new JdbcUnitOfWork(connectionManager), 
        executor
    );

    // Крок 1: Паралельно завантажити дані
    CompletableFuture<Author> futureAuthor = 
        asyncAuthorRepo.findByIdAsync(authorId)
            .thenApply(opt -> opt.orElseThrow());

    CompletableFuture<Genre> futureGenre = 
        asyncGenreRepo.findByIdAsync(genreId)
            .thenApply(opt -> opt.orElseThrow());

    // Крок 2: Після завершення — зареєструвати об'єкти
    return CompletableFuture.allOf(futureAuthor, futureGenre)
        .thenApply(v -> {
            Author author = futureAuthor.join();
            Genre  genre  = futureGenre.join();

            // Реєстрація — синхронна, без SQL
            Audiobook book1 = new Audiobook("Книга 1", author, genre);
            Audiobook book2 = new Audiobook("Книга 2", author, genre);
            asyncUow.registerNew(book1);
            asyncUow.registerNew(book2);

            return null;
        })
        // Крок 3: Асинхронно закомітити всі зміни в одній транзакції
        .thenCompose(v -> asyncUow.commitAsync())
        .exceptionally(ex -> {
            asyncUow.rollback();
            throw new RuntimeException("Транзакція провалилася", ex);
        });
}

// Запускаємо 100 асинхронних запитів
List<CompletableFuture<Author>> futures = new ArrayList<>();
for (int i = 0; i < 100; i++) {
    futures.add(asyncAuthorRepo.findByIdAsync(authorIds.get(i)));
}

// Що станеться?
// - Перші 10 запитів отримають Connection з пулу
// - Наступні 90 чекатимуть на звільнення Connection
// - Потоки ExecutorService блокуються у getConnection()

// Правило: розмір пулу потоків ≤ розмір пулу з'єднань
int connectionPoolSize = 10;
int threadPoolSize = connectionPoolSize; // або менше

ExecutorService executor = Executors.newFixedThreadPool(threadPoolSize);

public class ThrottledAsyncRepository<T, ID> extends AbstractAsyncRepository<T, ID> {

    private final Semaphore semaphore;

    public ThrottledAsyncRepository(Repository<T, ID> syncRepo, 
                                    ExecutorService executor,
                                    int maxConcurrent) {
        super(syncRepo, executor);
        this.semaphore = new Semaphore(maxConcurrent);
    }

    @Override
    public CompletableFuture<Optional<T>> findByIdAsync(ID id) {
        return CompletableFuture.supplyAsync(() -> {
            try {
                semaphore.acquire(); // чекаємо дозволу
                try {
                    return syncRepository.findById(id);
                } finally {
                    semaphore.release(); // звільняємо дозвіл
                }
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();
                throw new RuntimeException(e);
            }
        }, executor);
    }
}

// ❌ DEADLOCK: join() блокує потік, що виконує thenApply
CompletableFuture<Author> future1 = asyncAuthorRepo.findByIdAsync(id1);
CompletableFuture<Genre> future2 = future1.thenApply(author -> {
    // Цей блок виконується у потоці пулу
    // join() блокує потік, чекаючи на інший CompletableFuture
    Genre genre = asyncGenreRepo.findByIdAsync(genreId).join(); // ← DEADLOCK!
    return genre;
});

// ✅ ПРАВИЛЬНО: thenCompose не блокує потік
CompletableFuture<Genre> future2 = future1.thenCompose(author -> 
    asyncGenreRepo.findByIdAsync(genreId)
        .thenApply(opt -> opt.orElseThrow())
);

try {
    Author author = asyncAuthorRepo.findByIdAsync(invalidId).join();
} catch (Exception e) {
    // e — це CompletionException, що обгортає SQLException
    System.err.println(e.getClass()); // CompletionException
    System.err.println(e.getCause().getClass()); // DatabaseException
}

asyncAuthorRepo.findByIdAsync(invalidId)
    .exceptionally(ex -> {
        // ex — це оригінальне виключення (DatabaseException)
        if (ex instanceof DatabaseException) {
            System.err.println("Помилка БД: " + ex.getMessage());
        }
        return null;
    })
    .join();

public static Throwable unwrapCompletionException(Throwable ex) {
    if (ex instanceof java.util.concurrent.CompletionException && ex.getCause() != null) {
        return ex.getCause();
    }
    return ex;
}

// Використання:
try {
    author = asyncAuthorRepo.findByIdAsync(id).join();
} catch (Exception e) {
    Throwable cause = unwrapCompletionException(e);
    if (cause instanceof DatabaseException) {
        // Обробка помилки БД
    }
}

// ❌ НЕБЕЗПЕЧНО: операція може не завершитися до завершення програми
asyncAuthorRepo.saveAsync(newAuthor);
// Програма завершується → ExecutorService.shutdown() → потік перервано → INSERT не виконано

// ✅ ПРАВИЛЬНО: чекаємо на завершення
asyncAuthorRepo.saveAsync(newAuthor).join();

// Або зберігаємо future для пізнішого очікування
List<CompletableFuture<Void>> pendingWrites = new ArrayList<>();
pendingWrites.add(asyncAuthorRepo.saveAsync(author1));
pendingWrites.add(asyncAuthorRepo.saveAsync(author2));

// Перед завершенням програми:
CompletableFuture.allOf(pendingWrites.toArray(new CompletableFuture[0])).join();

// R2DBC: повністю асинхронний API
Mono<Author> authorMono = client
    .sql("SELECT * FROM authors WHERE id = :id")
    .bind("id", authorId)
    .map(row -> new Author(
        row.get("id", UUID.class),
        row.get("first_name", String.class),
        row.get("last_name", String.class)
    ))
    .one(); // повертає Mono<Author> (Project Reactor)

// Підписка на результат (non-blocking)
authorMono.subscribe(author -> 
    System.out.println("Завантажено: " + author.getFirstName())
);