Concepts & Principles

Concepts

Cortex.Net distinguishes the following concepts in your application. You saw them in the previous gist, but let's dive into them in a bit more detail.

1. State

State is the data that drives your application. Usually there is domain specific state like a list of todo items and there is view state such as the currently selected element. Remember, state is like spreadsheets cells that hold a value.

2. Derivations

Anything that can be derived from the state without any further interaction is a derivation. Derivations exist in many forms:

• The user interface.
• Derived data, such as the number of todos left.
• Backend integrations like sending changes to the server.

Cortex.Net distinguishes two kind of derivations:

• Computed values. These are values that can always be derived from the current observable state using a pure function. A pure function is a function where its result is dependent on its arguments and does not produce side effects.
• Reactions. Reactions are side effects that need to happen automatically if the state changes. These are needed as a bridge between imperative and reactive programming. Or to make it more clear, they are ultimately needed to achieve I/O. People starting with Cortex.Net tend to use reactions too often. The golden rule is: if you want to create a value based on the current state, use computed.

Back to the spreadsheet analogy, formulas are derivations that compute a value. But for you as a user to be able to see it on the screen a reaction is needed that repaints part of the GUI.

3. Actions

An action is any piece of code that changes the state. User events, backend data pushes, scheduled events, etc. An action is like a user that enters a new value in a spreadsheet cell.

Actions can be defined explicitly in Cortex.Net to help you to structure code more clearly. If Cortex.Net is used in strict mode, Cortex.Net will enforce that no state can be modified outside actions.

Principles

Cortex.Net supports a uni-directional data flow where actions change the state, which in turn updates all affected views.

All Derivations are updated automatically and atomically when the state changes. As a result it is never possible to observe intermediate values.

All Derivations are updated synchronously by default. This means that, for example, actions can safely inspect a computed value directly after altering the state.

Computed values are updated lazily. Any computed value that is not actively in use will not be updated until it is necessary for a side effect (I/O). If a view is no longer in use it will be garbage collected automatically.

All Computed values should be pure. They are not supposed to change state.

Illustration

The following listing illustrates the above concepts and principles:

using Cortex.Net.Api;

[Observable]
public class TodoStore
{
    public IList<Todo> Todos { get; private set; }

    [Computed]
    public int CompletedCount => this.Todos.Count(x => x.Completed);    

    public TodoStore()
    {
        /* a delegate that observes the state */
        sharedState.Autorun(() => {
            Console.WriteLine($"Completed {todos.ActiveCount} of {todos.Count} items.");
        });
    }

    /* ..and some actions that modify the state */
    [Action]
    public void First()
    {
        Todos.Add(new Todo()
        {
            Title = "Take a walk",
            Completed = false,
        });
        // -> synchronously prints 'Completed 0 of 1 items.'
    }
    
    [Action]
    public void Second()
    {
        Todo.Todos[0].Completed = true;
        // -> synchronously prints 'Completed 1 of 1 items.'
    }
}