DevBitsLab.Feeds 0.0.10

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
• Built-in Analyzers: Roslyn analyzers to enforce best practices

📚 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 =>
    {
        if (string.IsNullOrWhiteSpace(settings?.Username))
            return ValidationResult.Error(nameof(Settings.Username), "Username is required");
        return ValidationResult.Success;
    });

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

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

🔧 Core Types

🔗 Standard Interface Support

*Available in DevBitsLab.Feeds.WinUI package

📌 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
• ToObservable() - Convert to IObservable<T> for Rx

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
• ToObservable() - Convert to IObservable<IReadOnlyList<T>>

State Methods

• Update(value) - Set new value (marks dirty)
• SaveAsync() - Persist changes
• RevertAsync() - Discard changes
• Reset(value) - Set value without dirty flag
• ToObservable() - Convert to IObservable<T> for Rx

Feed Extension Methods

• Select(selector) - Project values
• Filter(predicate) - Filter updates by predicate
• Debounce(delay) - Debounce value changes
• DistinctUntilChanged() - Suppress duplicate values
• Timeout(timeout) - Apply timeout to loading
• Catch(fallback) - Handle errors with fallback
• DefaultIfNull(value) - Provide default for null values

🔍 Analyzers

DevBitsLab.Feeds includes Roslyn analyzers to help enforce best practices:

See the full analyzer documentation for details.

✅ Best Practices

1. Use [BindableFeed] for Automatic Disposal

The [BindableFeed] attribute automatically implements IDisposable and disposes all marked feeds:

public partial class MyViewModel : ObservableObject
{
    [BindableFeed]
    public partial Feed<Customer> Customer { get; init; }
    
    [BindableFeed]
    public partial State<Settings> Settings { get; init; }
    
    [BindableFeed]
    public partial ListFeed<Order> Orders { get; init; }
    
    // IDisposable is auto-generated! Just call Dispose() when done.
}

// Usage:
var viewModel = new MyViewModel { ... };
// ... use the view model ...
viewModel.Dispose(); // All feeds are automatically disposed!

If you already implement IDisposable, call DisposeBindableFeeds() from your Dispose method:

public partial class MyViewModel : ObservableObject, IDisposable
{
    [BindableFeed]
    public Feed<Customer> Customer { get; } = Feed<Customer>.Create(LoadAsync);
    
    private readonly HttpClient _httpClient = new();
    
    public MyViewModel()
    {
        InitializeBindableFeeds(); // Required for non-partial properties
    }
    
    public void Dispose()
    {
        DisposeBindableFeeds(); // Disposes Customer automatically
        _httpClient.Dispose();  // Your custom cleanup
    }
}

2. Batch Multiple List Changes

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

// Avoid: Multiple notifications
listFeed.Add(item1);
listFeed.Add(item2);

3. Combine Feeds for Derived Data

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

4. Use Partial Properties for Automatic Binding (C# 13+)

Partial properties enable lazy initialization without needing InitializeBindableFeeds():

public partial class MyViewModel : ObservableObject
{
    [BindableFeed]
    public partial Feed<Person> Person { get; set; }
    
    // No InitializeBindableFeeds() needed - binding is set up lazily on first access
}

📊 Benchmark Results

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

Feed 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

🤝 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.