👁 Image
ReactiveList 5.0.2

ReactiveList

👁 NuGet
👁 NuGet Downloads
👁 Build Status

ReactiveList is a high-performance, thread-safe observable collection library for .NET. It provides list, dictionary, sharded, indexed, and view-based collection types that publish change streams for UI binding, reactive workflows, live data processing, and low-allocation batch operations.

<p align="center"> <img src="Images/HeroImage.png" alt="ReactiveList V5 dual package configuration" width="500" /> </p>

V5.0.x Breaking Change

ReactiveList V5.0.x introduces a dual package configuration and changes the base namespaces.

This is a breaking change from ReactiveList V4.x.x.

Do not mix the two package variants in the same pipeline casually. Their namespaces and scheduler conventions are deliberately different. If an application needs both, keep a clear boundary between the lean CP.Primitives.* code and the System.Reactive CP.Reactive.* code.

Contents

• Installation
• Package Selection
• Migration From V4.x.x To V5.x.x
• Quick Start
• Using R3
• Core Concepts
• Collections
• Views
• Extension Methods
• API Reference
• Thread Safety
• Performance
• Target Frameworks
• Validation
• License

Installation

Lean primitives package:

dotnet add package ReactiveList --version 5.0.*

System.Reactive package:

dotnet add package ReactiveList.Reactive --version 5.0.*

The package dependencies are brought in automatically:

• ReactiveList references ReactiveUI.Primitives.
• ReactiveList.Reactive references ReactiveUI.Primitives.Reactive, which references System.Reactive.

Package Selection

Use only one variant unless you have a specific interop boundary.

Lean Package

using CP.Primitives;
using CP.Primitives.Collections;
using CP.Primitives.Core;
using CP.Primitives.Views;
using ReactiveUI.Primitives;
using ReactiveUI.Primitives.Concurrency;

Use this package when:

• You want BCL IObservable<T> without a direct System.Reactive dependency.
• You use ReactiveUI.Primitives.Concurrency.ISequencer.
• You use Sequencer.Default, Sequencer.Immediate, or SynchronizationContextSequencer.Current.
• You want the R3 bridge source generator packed by ReactiveUI.Primitives.

System.Reactive Package

using CP.Reactive;
using CP.Reactive.Collections;
using CP.Reactive.Core;
using CP.Reactive.Views;
using ReactiveUI.Primitives.Reactive;
using System.Reactive.Concurrency;

Use this package when:

• Your application already uses System.Reactive operators and schedulers.
• You want ReactiveList view creation APIs to accept IScheduler.
• You want to use schedulers such as ImmediateScheduler.Instance, CurrentThreadScheduler.Instance, or Scheduler.Default.

Migration From V4.x.x To V5.x.x

V4 code usually used CP.Reactive.* from the main package. In V5 you must choose the package variant first.

Option A: Move To The Lean V5 Package

Use this path if you do not need System.Reactive scheduler types in your public API.

1. Update the package reference to ReactiveList V5.0.x.
2. Replace namespaces:

CP.Reactive -> CP.Primitives
CP.Reactive.Collections -> CP.Primitives.Collections
CP.Reactive.Core -> CP.Primitives.Core
CP.Reactive.Views -> CP.Primitives.Views
CP.Reactive.Internal -> CP.Primitives.Internal

3. Keep ReactiveUI.Primitives imports:

using ReactiveUI.Primitives;
using ReactiveUI.Primitives.Concurrency;
using ReactiveUI.Primitives.Signals;

4. Keep lean scheduler usage:

using CP.Primitives.Collections;
using ReactiveUI.Primitives.Concurrency;

var list = new ReactiveList<int>();
using var view = list.CreateView(Sequencer.Immediate, throttleMs: 0);

Option B: Keep CP.Reactive.* Namespaces

Use this path if you want the old CP.Reactive.* namespace shape and System.Reactive scheduler conventions.

1. Replace the package reference with ReactiveList.Reactive V5.0.x.
2. Keep CP.Reactive.* namespaces.
3. Replace ReactiveUI.Primitives.Concurrency.ISequencer schedulers with System.Reactive.Concurrency.IScheduler.
4. Replace lean scheduler values with System.Reactive schedulers:

using CP.Reactive.Collections;
using System.Reactive.Concurrency;

var list = new ReactiveList<int>();
using var view = list.CreateView(ImmediateScheduler.Instance, throttleMs: 0);

Common Migration Checks

• Update global usings and aliases first.
• Rebuild before changing behavior. Most migration errors are namespace or scheduler-type errors.
• Avoid referencing both package variants in a single test assembly unless you fully qualify imports. Extension methods from ReactiveUI.Primitives and System.Reactive can otherwise create ambiguous Subscribe calls.
• Update UI code to use the scheduler type from the selected package.
• Update documentation and samples to say CP.Primitives.* for the lean package and CP.Reactive.* for the System.Reactive package.

Quick Start

Lean Package Example

using CP.Primitives.Collections;
using CP.Primitives.Core;
using ReactiveUI.Primitives;

var orders = new ReactiveList<Order>();

using var subscription = orders.Stream.Subscribe(notification =>
{
 if (notification.Action == CacheAction.Added && notification.Item is not null)
 {
 Console.WriteLine($"Added order {notification.Item.Id}");
 }
});

orders.Add(new Order(1, 125.00m));
orders.AddRange([new Order(2, 40.00m), new Order(3, 75.00m)]);

public sealed record Order(int Id, decimal Amount);

System.Reactive Package Example

using CP.Reactive.Collections;
using CP.Reactive.Core;
using System;
using System.Reactive.Concurrency;

var orders = new ReactiveList<Order>();

using var subscription = orders.Stream.Subscribe(notification =>
{
 if (notification.Action == CacheAction.Added && notification.Item is not null)
 {
 Console.WriteLine($"Added order {notification.Item.Id}");
 }
});

orders.Add(new Order(1, 125.00m));
using var view = orders.CreateView(ImmediateScheduler.Instance, throttleMs: 0);

public sealed record Order(int Id, decimal Amount);

Batch Edit

using CP.Primitives.Collections;

var list = new ReactiveList<string>();

list.Edit(editor =>
{
 editor.Add("alpha");
 editor.Add("beta");
 editor.Insert(1, "middle");
 editor.Remove("alpha");
});

Edit batches collection mutations and emits one batch notification after the transaction completes.

Using R3

ReactiveList does not require R3, but the lean ReactiveList package depends on ReactiveUI.Primitives, which packs the ReactiveUI.Primitives R3 bridge source generator as an analyzer. Do not add ReactiveUI.Primitives.R3Bridge.Generator directly.

To use R3:

dotnet add package ReactiveList --version 5.0.*
dotnet add package R3

Then import the generated bridge namespace:

using CP.Primitives.Collections;
using ReactiveUI.Primitives.R3Bridge;

var list = new ReactiveList<int>();

// System.IObservable<CacheNotify<int>> -> R3.Observable<CacheNotify<int>>
var r3Stream = list.Stream.AsR3Observable();

The source generator emits bridge methods only when the consumer assembly references the required R3 symbols:

Use bridges at the edge of your application. Keep the internal pipeline in one model after conversion.

Example with an R3 filter stream:

using CP.Primitives.Collections;
using ReactiveUI.Primitives.Concurrency;
using ReactiveUI.Primitives.R3Bridge;

var list = new ReactiveList<Product>();

R3.Observable<Func<Product, bool>> r3Filter = GetFilterObservable();
var primitivesFilter = r3Filter.AsPrimitivesSignal();

using var view = list.CreateView(primitivesFilter, Sequencer.Immediate, throttleMs: 0);

static R3.Observable<Func<Product, bool>> GetFilterObservable() =>
 R3.Observable.Return<Func<Product, bool>>(product => product.IsActive);

public sealed record Product(string Name, bool IsActive);

For System.Reactive-first projects, prefer ReactiveList.Reactive. Use R3 conversion at boundaries only if that assembly also references R3 and the required ReactiveUI.Primitives bridge symbols.

Core Concepts

Change Stream

Every collection exposes a stream of cache notifications:

IObservable<CacheNotify<T>> Stream { get; }

The stream emits CacheNotify<T> values for single-item, batch, clear, move, update, and refresh operations.

CacheNotify

CacheNotify<T> describes a collection change.

CacheAction values:

• Added
• Removed
• Updated
• Moved
• Refreshed
• Cleared
• BatchOperation
• BatchAdded
• BatchRemoved

ChangeSet

ChangeSet<T> is a compact IReadOnlyList<Change<T>> used for DynamicData-style processing.

Useful members:

• Count
• Adds
• Removes
• Updates
• Moves
• AsSpan()
• Dispose()

Change<T> provides factory methods for CreateAdd, CreateRemove, CreateUpdate, CreateMove, and CreateRefresh.

ChangeReason values:

• Add
• Remove
• Update
• Move
• Refresh
• Clear

Collections

ReactiveList<T>

ReactiveList<T> is a thread-safe observable list implementing IList<T>, non-generic IList, IReadOnlyList<T>, INotifyCollectionChanged, INotifyPropertyChanged, and IDisposable.

Constructors:

new ReactiveList<T>();
new ReactiveList<T>(IEnumerable<T> items);
new ReactiveList<T>(T item);

Properties and streams:

Mutation methods:

Read and copy methods:

Reactive2DList<T>

Reactive2DList<T> derives from ReactiveList<ReactiveList<T>> and models rows, grids, matrices, and nested collections.

Constructors:

new Reactive2DList<T>();
new Reactive2DList<T>(IEnumerable<IEnumerable<T>> items);
new Reactive2DList<T>(IEnumerable<ReactiveList<T>> items);
new Reactive2DList<T>(IEnumerable<T> items);
new Reactive2DList<T>(ReactiveList<T> item);
new Reactive2DList<T>(T item);

Additional methods:

QuaternaryList<T>

QuaternaryList<T> is a four-shard thread-safe observable collection for large data sets, lower allocation pressure, parallel-friendly operations, and secondary-index lookups.

Core APIs:

Secondary index APIs:

QuaternaryDictionary<TKey, TValue>

QuaternaryDictionary<TKey, TValue> is a four-shard thread-safe observable dictionary for key-value caches, bulk writes, and value-indexed lookup.

Core APIs:

Secondary index APIs:

Low-Level Quad Types

QuadList<T> and QuadDictionary<TKey, TValue> are lower-level shard containers used by the quaternary collections. They expose direct add, remove, clear, copy, capacity, enumeration, and dispose operations. Most application code should use QuaternaryList<T> or QuaternaryDictionary<TKey, TValue> instead.

Views

Views are disposable live projections over collection streams. Dispose them when the UI or workflow no longer needs updates.

Common view members:

• Items
• Count
• indexer for list-like views
• CollectionChanged
• PropertyChanged
• Refresh()
• ToProperty(Action<ReadOnlyObservableCollection<T>>)
• ToProperty(out ReadOnlyObservableCollection<T>)
• Dispose()

View Examples

using CP.Primitives;
using CP.Primitives.Collections;
using ReactiveUI.Primitives.Concurrency;
using ReactiveUI.Primitives.Signals;

var products = new QuaternaryList<Product>();
products.AddIndex("ByCategory", product => product.Category);

using var active = products.CreateView(product => product.IsActive, Sequencer.Default);
using var grouped = products.GroupBy(product => product.Category, Sequencer.Default);
using var indexed = products.CreateViewBySecondaryIndex("ByCategory", "Hardware", Sequencer.Default);

var query = new BehaviorSignal<string>("hardware");
using var search = products.CreateView(
 query,
 static (text, product) => product.Name.Contains(text, StringComparison.OrdinalIgnoreCase),
 Sequencer.Default);

public sealed record Product(string Name, string Category, bool IsActive);

Extension Methods

CacheNotifyExtensions

These operate on IObservable<CacheNotify<T>>.

ReactiveListExtensions

These operate on collection streams and change sets.

QuaternaryExtensions

These operate on QuaternaryList<T> and QuaternaryDictionary<TKey, TValue>.

API Reference

Interfaces

Core Types

Namespaces

Thread Safety

All public collection operations are designed for thread-safe use.

• ReactiveList<T> uses lock-based synchronization for list and observable collection state.
• Reactive2DList<T> inherits the thread-safety model from ReactiveList<T>.
• QuaternaryList<T> and QuaternaryDictionary<TKey, TValue> use four internal shards and reader/writer locking to reduce contention for larger data sets.
• Enumerators and snapshots are safe point-in-time views.
• Observable streams are notification surfaces; core collection mutations do not depend on observers completing expensive work.

Use care with direct-memory APIs:

• AsSpan() exposes current storage and should be used only when you can guarantee no concurrent writes.
• Prefer ToArray(), Snapshot(), or AsMemory() for defensive snapshots.

Performance

ReactiveList is optimized for low-allocation notifications, pooled batches, sharded storage, and batch editing.

Use these patterns:

Measured benchmark highlights from the V5 work:

Target Frameworks

The library targets the shared CoreTargetFrameworks configured for the repository:

• net8.0
• net9.0
• net10.0
• net11.0
• On Windows builds, net462, net472, net48, net481, and matching Windows TFMs are included.

Native AOT compatibility is enabled for compatible modern .NET target frameworks.

Validation

The V5 dual package configuration has been verified locally with:

dotnet restore src\ReactiveList.sln
dotnet build src\ReactiveList.sln -c Release --no-restore -v quiet
dotnet test src\ReactiveList.sln -c Release --no-build --no-restore

The full TUnit run passed across the solution with 2,901 tests, 0 failed, and 0 skipped. The targeted MTP Cobertura coverage run reported 100.00% line coverage for the ReactiveList package.

License

This project is licensed under the MIT License. See for details.