Normalized State

Key Characteristics

1. Normalization: Entities are stored in an ImmutableDictionary, indexed by a unique key (e.g., Guid, int). This eliminates redundancy and simplifies the management of related entities.

2. Immutability: All operations on the state return a new instance, ensuring that state changes are predictable, traceable, and free from side effects.

3. Comprehensive API: NormalizedState provides a rich set of methods for common operations, making it easier to manipulate collections of entities in a consistent and predictable way.

Example: Defining a Todo State

Consider a todo application where each todo item has a unique identifier. Here's how you would define a normalized state for managing todos:

In this example:

• TodoState inherits from NormalizedState<Guid, TodoItem, TodoState>, managing a collection of TodoItem entities.

• Selectors are defined to encapsulate logic for querying the state, such as retrieving completed or active todos.

Entity Management Methods

Here’s an overview of the key methods available in NormalizedState:

• Create: Initializes a new state with a collection of entities.

  public static TState Create(ImmutableList<TEntity> entities)

  Example:

  var initialState = TodoState.Create(initialTodos);

• AddOne: Adds a single entity to the state.

  public TState AddOne(TEntity entity)

  Example:

  var newState = state.AddOne(new TodoItem(Guid.NewGuid(), "New Task"));

• AddMany: Adds multiple entities to the state.

  public TState AddMany(IEnumerable<TEntity> entities)

  Example:

  var newState = state.AddMany(newListOfTodos);

• SetOne: Replaces or adds a single entity.

  public TState SetOne(TEntity entity)

  Example:

  var updatedState = state.SetOne(updatedTodo);

• SetMany: Replaces or adds multiple entities.

  public TState SetMany(IEnumerable<TEntity> entities)

  Example:

  var updatedState = state.SetMany(updatedTodos);

• RemoveOne: Removes an entity by its key.

  public TState RemoveOne(TKey key)

  Example:

  var newState = state.RemoveOne(todoId);

• RemoveMany: Removes multiple entities by their keys.

  public TState RemoveMany(IEnumerable<TKey> keys)

  Example:

  var newState = state.RemoveMany(todoIds);

• UpdateOne: Updates a single entity using an action or function.

  public TState UpdateOne(TKey key, Action<TEntity> update) public TState UpdateOne(TKey key, Func<TEntity, TEntity> update)

  Example:

  var updatedState = state.UpdateOne(todoId, todo => todo.MarkAsCompleted());

• UpdateMany: Updates multiple entities using an action or function.

  public TState UpdateMany(IEnumerable<TKey> keys, Action<TEntity> update) public TState UpdateMany(IEnumerable<TKey> keys, Func<TEntity, TEntity> update)

  Example:

  var updatedState = state.UpdateMany(todoIds, todo => todo.MarkAsCompleted());

• UpsertOne: Updates or inserts a single entity.

  public TState UpsertOne(TEntity entity)

  Example:

  var newState = state.UpsertOne(newTodoItem);

• UpsertMany: Updates or inserts multiple entities.

  public TState UpsertMany(IEnumerable<TEntity> entities)

  Example:

  var newState = state.UpsertMany(todoItems);

• MapOne: Transforms a single entity by applying a function.

  public TState MapOne(TKey key, Func<TEntity, TEntity> map)

  Example:

  var mappedState = state.MapOne(todoId, todo => todo.WithPriority("High"));

• Map: Transforms all entities in the state.

  public TState Map(Func<TEntity, TEntity> map)

  Example:

  var mappedState = state.Map(todo => todo.WithCategory("Work"));

Example: Adding, Updating, and Removing Entities

Merging Entities

When you need to merge a set of entities into the state, you can use the Merge method. This method allows for different merge strategies, such as overwriting existing entities or failing if duplicates are found.

• MergeStrategy.FailIfDuplicate: Ensures that no duplicates are merged into the state.

• MergeStrategy.Overwrite: Overwrites any existing entities with the new ones.

Querying Entities

Entities stored in a NormalizedState are indexed by their keys, making it easy to query them efficiently. You can retrieve an entity directly by its key using the indexer.

Filtering with Selectors

Selectors allow you to define reusable queries that filter or transform the state. This keeps your components clean and focused on rendering UI rather than managing data.

Breakdown of the Serialized Structure

1. type: This field indicates the fully qualified name of the state type, including the assembly information. It tells the system how to deserialize this state back into its original type.

2. by-id: This dictionary holds the entities indexed by their unique keys. Each key corresponds to an entity's ID, and the value is the entity itself, represented as a JSON object.

3. all-ids: This array lists all the keys (IDs) of the entities stored in the state. It preserves the order of the entities as they were added, which can be useful for displaying items in a particular order.

Advantages of the Serialized Format

• Efficiency: By storing entities in a dictionary, operations like lookups, updates, and deletions are very efficient.

• Clarity: The separation between the by-id dictionary and the all-ids list provides a clear distinction between the entities themselves and their ordering, making it easier to understand and manipulate the state.

• Consistency: When rehydrating (deserializing) the state, the structure ensures that all entities are restored accurately, maintaining the relationships and order as intended.

This structured approach not only makes the state more manageable within your application but also ensures that any serialized data is robust, easy to inspect, and straightforward to restore.