Components & selectors

BlexComponentBase

Inherit from BlexComponentBase and call Subscribe(...) in OnInitialized. The component re-renders whenever a subscribed store changes and detaches every handler on dispose - there is no StateHasChanged to call and nothing to clean up.

@inherits BlexComponentBase
@inject CounterStore Counter

<p>Count: @Counter.Count</p>
<button @onclick="Counter.Increment">+1</button>

@code {
    protected override void OnInitialized() => Subscribe(Counter);
}

You can subscribe to several stores at once; the call is idempotent per store.

protected override void OnInitialized() => Subscribe(Counter, Todos, Settings);

Selector subscriptions

Subscribe(store) fires on any change to that store. On a store with many independent fields - or one big collection - that re-renders components that do not care. Subscribe to a projection instead, and the component only wakes up when the projected value actually changes.

// Re-renders only when Count changes; a change to Step is ignored.
protected override void OnInitialized()
    => Subscribe(Counter, () => Counter.Count);

Outside components

The same primitive is a plain extension method on IBlexStore, usable anywhere. It returns a token - dispose it to stop observing.

using var sub = store.Subscribe(
    () => store.Count,
    count => Console.WriteLine($"count is now {count}"));

// ... later
sub.Dispose();   // stop observing

Previous and current

The two-argument overload delivers (previous, current), which is what you want for transition logic - analytics, animations, "changed from X to Y" logging. This is MobX's reaction shape.

var sub = store.Subscribe(
    () => store.Status,
    (previous, current) => _analytics.Track("status-changed", previous, current),
    fireImmediately: true);

Custom equality

Both overloads take an optional IEqualityComparer<T>. Supply one when the projection returns something whose default equality is not what you mean - a collection, for instance, where you want to compare contents rather than references.

This is the case that quietly defeats selectors. A projection like () => Contacts.All.Where(c => c.Starred) builds a new object on every evaluation, so the default reference comparison always reports a change and the subscription fires on every action - precisely what selecting a projection was meant to avoid. BlexComparers supplies the two comparers that fix it, the same job zustand's shallow does.

// Fires on every action: Where(...) is a new object each time.
store.Subscribe(() => store.Contacts.All.Where(c => c.Starred), Refresh);

// Fires only when the starred contacts actually differ.
store.Subscribe(
    () => store.Contacts.All.Where(c => c.Starred),
    Refresh,
    BlexComparers.Sequence<Contact>());

// Order is incidental for a selection of ids -- compare as a set.
store.Subscribe(
    () => store.SelectedIds,
    Refresh,
    BlexComparers.Set<int>());

// Components take the same argument:
Subscribe(Store, () => Store.Visible, BlexComparers.Sequence<Contact>());

fireImmediately

Pass fireImmediately: true to invoke the callback once at subscription time with the current value, so an observer does not have to seed itself. With the two-argument overload, previous and current are both the value at subscription. If that first call throws, the subscription is detached before the exception surfaces - the caller never received a token, so a handler left attached would be unstoppable.

Across stores

BlexManager carries the same pair of overloads for a projection that spans stores. Without it, a value derived from two stores has to be recomputed on every action of every store - the cross-store equivalent of re-rendering the whole app on any change.

@inject BlexManager Manager
@inject CartStore Cart
@inject ProfileStore Profile

protected override void OnInitialized()
    => OwnsSubscription(Manager.Subscribe(
           () => Cart.Total > Profile.CreditLimit,     // spans two stores
           overLimit => _banner = overLimit ? "Over your limit" : null));

// The (previous, current) overload and a custom comparer work the same as on a store:
Manager.Subscribe(
    () => Cart.Total,
    (previous, current) => _analytics.CartValueChanged(previous, current));

Owning other subscriptions

OwnsSubscription(IDisposable) hands any token to the component so it is disposed along with it - a manager subscription, a selector token you made yourself, anything.

@code {
    [Inject] private BlexManager Manager { get; set; } = default!;

    protected override void OnInitialized()
    {
        Subscribe(Store);
        OwnsSubscription(Manager.SubscribeTo<OrdersStore>(ctx => Refresh()));
    }
}

The raw event

Under everything is IBlexStore.StateChanged, a plain Action raised once per action after the state has settled. Use it directly when you want no machinery at all - just remember to unsubscribe.

void OnChanged() => Console.WriteLine("something changed");

store.StateChanged += OnChanged;
// ...
store.StateChanged -= OnChanged;