Как работает интерфейс IAsyncEnumerable<T>?

// Вариант 1: асинхронно, но всё в памяти — ждём ВСЕ строки
Task<List<Order>> GetAllAsync();

// Вариант 2: потоково, но синхронно — поток блокируется на каждой строке
IEnumerable<Order> GetAll();

// Вариант 3: и потоково, и асинхронно
IAsyncEnumerable<Order> GetAllAsync();

public interface IAsyncEnumerable<out T>
{
    IAsyncEnumerator<T> GetAsyncEnumerator(CancellationToken cancellationToken = default);
}

public interface IAsyncEnumerator<out T> : IAsyncDisposable
{
    T Current { get; }
    ValueTask<bool> MoveNextAsync();     // ValueTask — часто элемент уже готов (буфер), без аллокаций
}

public async IAsyncEnumerable<Product> GetAllProductsAsync(
    [EnumeratorCancellation] CancellationToken ct = default)
{
    string? cursor = null;
    do
    {
        // постраничный обход внешнего API
        var page = await _http.GetFromJsonAsync<Page<Product>>($"/products?cursor={cursor}", ct);
        foreach (var product in page!.Items)
            yield return product;                     // отдать элемент потребителю
        cursor = page.NextCursor;
    }
    while (cursor is not null);
}

await foreach (var product in _catalog.GetAllProductsAsync(ct))
{
    await _index.UpsertAsync(product, ct);
    if (product.IsDiscontinued) break;   // break → DisposeAsync → итератор прекращает загрузку страниц
}

var enumerator = source.GetAsyncEnumerator(ct);
try
{
    while (await enumerator.MoveNextAsync())
    {
        var product = enumerator.Current;
        // тело цикла
    }
}
finally
{
    await enumerator.DisposeAsync();
}

// 1. Прямой вызов метода с токеном
await foreach (var x in GetAllProductsAsync(ct)) { }

// 2. Токен у потребителя, когда последовательность пришла «готовой»
IAsyncEnumerable<Product> products = GetAllProductsAsync();
await foreach (var x in products.WithCancellation(ct)) { }

// EF Core: строки читаются из DbDataReader по одной, без ToList()
app.MapGet("/export", (AppDbContext db) =>
    db.Orders.AsNoTracking().Where(o => o.Year == 2025).AsAsyncEnumerable());
// System.Text.Json сериализует IAsyncEnumerable потоково: клиент получает JSON-массив по мере чтения

// Обработка большой выборки без загрузки в память
await foreach (var order in db.Orders.AsNoTracking().AsAsyncEnumerable().WithCancellation(ct))
{
    await writer.WriteLineAsync(ToCsv(order));
}

var names = await GetAllProductsAsync(ct)
    .Where(p => p.Price > 100)
    .Select(p => p.Name)
    .Take(50)
    .ToListAsync(ct);