DevBitsLab.Feeds 0.0.2

DevBitsLab.Feeds

A reactive data management library for .NET that provides state-aware feeds with automatic loading, error handling, and incremental change tracking for collections.

📖 Overview

DevBitsLab.Feeds is a reactive data management library that simplifies working with asynchronous data in .NET applications. It provides a unified approach to handling loading states, errors, and data updates through a composable feed abstraction.

Key Benefits

• Simplified State Management: Automatic tracking of loading, error, and value states
• Reactive Updates: Event-driven architecture for real-time UI synchronization
• Incremental Collection Updates: Efficient list change tracking for optimal UI performance
• Type-Safe Composition: Combine multiple data sources with compile-time type checking
• MVVM-Ready: Built-in support for ICommand integration and data binding

📚 Documentation

📖 Full API Documentation — Detailed guides for all classes and interfaces

📋 Requirements

• .NET 10.0 or later
• C# 14 (Preview)
• Nullable Reference Types enabled

📦 Installation

.NET CLI

dotnet add package DevBitsLab.Feeds

Package Manager Console

Install-Package DevBitsLab.Feeds

🚀 Getting Started

Basic Feed Usage

using DevBitsLab.Feeds;

// Create a feed that loads data from an API
var customerFeed = Feed<Customer>.Create(async ct =>
{
    return await httpClient.GetFromJsonAsync<Customer>($"/api/customers/{id}", ct);
});

// Subscribe to state changes
customerFeed.StateChanged += (sender, e) =>
{
    if (customerFeed.IsLoading)
        ShowLoadingSpinner();
    else if (customerFeed.HasValue)
        DisplayCustomer(customerFeed.Value!);
    else if (customerFeed.HasError)
        ShowError(customerFeed.Error!.Message);
};

// Or await the feed directly
var customer = await customerFeed;

List Feed with Change Tracking

var productsFeed = ListFeed<Product>.Create(async ct =>
{
    return await productApi.GetProductsAsync(ct);
});

// Subscribe to incremental changes
productsFeed.ItemsChanged += (sender, e) =>
{
    switch (e.Change)
    {
        case ListChange<Product>.ItemAdded added:
            InsertRowAt(added.Index, added.Item);
            break;
        case ListChange<Product>.ItemRemoved removed:
            RemoveRowAt(removed.Index);
            break;
    }
};

// Modify the list - changes are tracked automatically
productsFeed.Add(new Product { Name = "New Product" });

Editable State with Validation

var settingsState = State<Settings>.Create(
    loadFunc: async ct => await settingsService.LoadAsync(ct),
    saveFunc: async (settings, ct) => await settingsService.SaveAsync(settings, ct),
    validateFunc: settings =>
    {
        var result = new ValidationResult();
        if (string.IsNullOrWhiteSpace(settings?.Username))
            result.AddError(nameof(Settings.Username), "Username is required");
        return result;
    });

// Edit and save
settingsState.Update(settingsState.Value! with { Theme = "Dark" });

if (settingsState.IsDirty && !settingsState.HasErrors)
    await settingsState.SaveAsync();

🔧 Core Types

📌 Feed States

📚 API Quick Reference

Feed Methods

• Create(loadFunc) - Create auto-loading feed
• CreateDeferred(loadFunc) - Create manually-triggered feed
• FromValue(value) - Create feed with existing value
• FromError(exception) - Create feed in error state
• RefreshAsync() - Reload data from source
• Select(selector) - Transform feed value

ListFeed Methods

• Empty() - Create empty list feed
• FromItems(items) - Create from existing items
• Add(item) / Insert(index, item) - Add items
• Remove(item) / RemoveAt(index) - Remove items
• Update(index, newItem) - Replace item
• BatchUpdate(action) - Atomic multi-operation

State Methods

• Update(value) - Set new value (marks dirty)
• SaveAsync() - Persist changes
• RevertAsync() - Discard changes
• Reset(value) - Set value without dirty flag

LINQ Extensions

• Select(selector) - Project items
• Where(predicate) - Filter items
• OrderBy(keySelector) - Sort items
• Take(count) / Skip(count) - Pagination
• Aggregate(aggregator) - Compute aggregate value

✅ Best Practices

1. Always Dispose Feeds

public class MyViewModel : IDisposable
{
    private readonly Feed<Data> _feed;
    public void Dispose() => _feed?.Dispose();
}

2. Batch Multiple List Changes

// Good: Single notification
listFeed.BatchUpdate(editor =>
{
    editor.Add(item1);
    editor.Add(item2);
});

3. Combine Feeds for Derived Data

var dashboardFeed = userFeed.CombineWith(
    ordersFeed,
    (user, orders) => new Dashboard(user, orders));

📊 Benchmark Results

Benchmarks run nightly. Run configuration: .NET 10, Release mode, Ubuntu Latest.

See the main repository README for full benchmark details.

Feed Throughput

ListFeed Throughput

State Throughput

Key Performance Characteristics

• Zero-allocation reads: Accessing Value, State, IsDirty, HasValue allocates nothing
• Sub-nanosecond property access: Core read operations complete in under 1 ns
• Efficient updates: Single-item operations complete in nanoseconds
• Scalable collections: ListFeed<T> operations scale well with collection size
• Batch optimization: BatchUpdate amortizes notification overhead across multiple operations

🤝 Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

1. Clone the repository
2. Open in Visual Studio 2022 or later
3. Build the solution
4. Run tests

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.