Forem: Pierre Bouillon

Managing database schema changes in .NET From theory to FluentMigrator

Pierre Bouillon — Mon, 16 Mar 2026 05:45:13 +0000

If you’ve ever managed a database alongside an evolving application, you’ve likely faced a common issue: your code and your database don't always evolve at the same pace. Over time, the schema version running in production can drift from what you’re using for local development. This only gets worse as more developers join the project, often working on features that require conflicting database changes.

Keeping environments in sync while tracking every schema modification is not that easy, and it explains why there are several tools to help you to do so.

In this article, we’ll work through a minimalist Web API using a Clean Architecture (or Onion/Hexagonal-like) structure. While our project includes an EF Core DbContext for data access, we will be using FluentMigrator to create and manage migrations in order to keep our database in sync with our code without the typical EF Core migration overhead or raw SQL scripts stored somewhere.

Why Bother With Migrations?

In the early stages of a project, you can usually get away with recreating your database from scratch whenever your entities change. However, as soon as your application starts handling real-world data and new features roll in, "nuking" the database is no longer an option. You need a way to evolve the schema without losing the data.

Migrations are designed for this exact scenario. At its core, a migration is like a patch note for your database: an incremental script that describes how to move the schema from its current state to a new one.

In practice, effective migrations generally follow two key principles:

Migrations should be atomic: Instead of some kind of "god script", each migration should be focused on the smallest possible increment for the feature and avoid doing too much. Most migration tools use a history table to ensure a script only runs once avoiding the schema to be in an inconsistent state.

For example: If a migration adds a Status column to your TodoItems table, you should avoid adding unrelated changes such as an index on another table to speed up performance on an unrelated issue.

Migrations should be reversible: If you describe how to apply a change, you should also specify how to undo it. These transitions are usually named "up" and "down". This ensures you have a safety net to roll back the schema if a deployment goes wrong.

For instance: If you realize a new Priority column is causing unexpected issues in production, a "down" migration allows you to quickly drop that column and restore the database to its previous stable state.

Adhering to these principles allows you to tightly couple your code to your database schema, ensuring they evolve at the same time. By treating migrations as small, incremental updates that are merged and tracked just like any other piece of code, you maintain data integrity across the board and ensure that no one on the team accidentally introduces a conflicting change.

An Overview of The Existing Tools

Since migrations are so handy at creating a healthy way to deal with database changes, a great variety of tools exist to manage them in numerous frameworks such as Alembic for Python, migrate for Go, etc.

Migration tools exist on a spectrum of abstraction ranging from those that hide SQL entirely behind .NET code to those that require you to write raw scripts manually.

Both have their advantages and drawbacks:

Sticking to .NET allows developers to stay within the C# ecosystem and delegate the "boilerplate" to the tooling. However, this also means the SQL will be some kind of black box since you didn't actually write it. Should you have an issue, you will probably have to investigate generated code too.
Handling the SQL separately gives you much more control over the SQL you will execute and does not leave room for unexpected code, but requires you both to maintain the scripts separately and to ensure the team's written scripts are valid.

Let's briefly see two popular approaches and where the tool we'll use, FluentMigrator, is placed on that axis.

Entity Framework Core

Entity Framework Core provides a built in way to manage migrations alongside its DbContext, usable through the Entity Framework Core CLI.

The most common approach, also known as Code First, is to create your .NET entities, and then use the CLI to generate and apply migrations:

dotnet ef migrations add InitialCreate
dotnet ef database update

In our example, for our TodoItem entity, EF Core will generate a migration class like this:

/// <inheritdoc />
public partial class InitialCreate : Migration
{
    /// <inheritdoc />
    protected override void Up(MigrationBuilder migrationBuilder)
    {
        migrationBuilder.CreateTable(
            name: "TodoItems",
            columns: table => new
            {
                Id = table.Column<Guid>(type: "TEXT", nullable: false),
                Title = table.Column<string>(type: "TEXT", nullable: false),
                IsCompleted = table.Column<bool>(type: "INTEGER", nullable: false)
            },
            constraints: table =>
            {
                table.PrimaryKey("PK_TodoItems", x => x.Id);
            });
    }

    /// <inheritdoc />
    protected override void Down(MigrationBuilder migrationBuilder)
    {
        migrationBuilder.DropTable(
            name: "TodoItems");
    }
}

From this usage, we can see that EF Core is on the far end of the "High Level" side. In a typical usage, the developer writes C# classes but rarely actually write the migrations. Instead, migrations are a kind of artifact generated by the tooling of Entity Framework.

RoundhousE, Evolve and Other SQL-First Tools

At the opposite end of the spectrum, we find tools like Roundhouse or Evolve. Unlike EF Core, Roundhouse moves away from C# abstractions entirely and embraces a Script-First philosophy.

In the case of Evolve, you typically start by creating a raw SQL script. The filename must follow a specific versioning structure for Evolve to pick it up:

-- 📂 V1_0_0__Initial_Create.sql
CREATE TABLE TodoItems (
    Id GUID PRIMARY KEY,
    Title TEXT NOT NULL,
    IsCompleted INTEGER NOT NULL
);

To ensure these scripts are available at runtime, you need to include them in your build output by updating your .csproj:

<ItemGroup>
  <Content Include="db\migrations\**\*.sql">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
  </Content>
</ItemGroup>

Finally, you can execute the migration:

var cnx = new SqliteConnection(yourConnectionString);

var evolve = new Evolve.Evolve(cnx, msg => _logger.LogInformation(msg))
{
    Locations = new[] { "db/migrations" },
    IsEraseDisabled = true,
};

evolve.Migrate();

The code we wrote is much more transparent but requires quite a lot of heavy lifting to put everything into place, making Evolve and similar tools to the far end of the "Low Level" side:

FluentMigrator

FluentMigratior occupies a more balanced position. It requires the developer to write the migrations explicitly, but it provides a C# Fluent API that mimics SQL syntax.

This allows more control over the changes applied to the database, while remaining agnostic of the database engine used under the hood, placing it around the middle of our spectrum:

Theory is great, but code is better. Now that we know why we’re choosing FluentMigrator, let’s look at how to actually set it up in our project.

Using FluentMigrator

For our example, we will be starting from a project with our basic building blocks are defined using the TodoItem as our entity and the TodoDbContext as our DbContext:

.
└── src/
    ├── Todo.Api/
    ├── Todo.Application/
    ├── Todo.Domain/
    │   └── TodoItem.cs
    └── Todo.Infrastructure/
        └── Persistence/
            └── TodoDbContext.cs

Creating Our First Migration

As with every library, let's first start by adding FluentMigrator to our Todo.Infrastructure project, as this layer is responsible for our data access concerns:

cd src/Todo.Infrastructure
dotnet add package FluentMigrator

With the packages installed, we can create our first migration. In FluentMigrator, a migration is a public class that inherits from Migration and is decorated with a [Migration] attribute containing a unique long integer acting as its ID.

FluentMigrator uses this ID to determine the execution order. You can adopt any convention you like, but I find using the current date followed by a counter (e.g., 2026_03_16_000) to be a robust way to avoid ID collisions in a team environment.

Initializing our database is done using a fluent, SQL-like API:

// 📂 Persistence/Migrations/CreateTodoItemsTable.cs
[Migration(2026_03_16_000, description: "Create todo items table")]
public class CreateTodoItemsTable : Migration
{
    public override void Up()
    {
        Create.Table("TodoItems")
            .WithColumn("Id").AsGuid().NotNullable().PrimaryKey()
            .WithColumn("IsCompleted").AsBoolean().NotNullable()
            .WithColumn("Title").AsString(128).NotNullable();
    }

    public override void Down()
    {
        Delete.Table("TodoItems");
    }
}

Since this code is using plain C#, it means you can also test it! While I won't be covering that part in this article, FluentMigrator actually has a guide for testing strategies you might want to look into.

Notice that the API also prompts us to specify the logic to undo our changes in the Down() method. This ensures we have a built-in safety net should we ever need to rollback this migration.

This abstraction allows you to keep your infrastructure database-agnostic. You can defer the choice of your database engine (or even switch from SQL Server to PostgreSQL) without rewriting the migration logic. You focus on the intent (.AsGuid()), and FluentMigrator handles the dialect (UNIQUEIDENTIFIER vs UUID).

And just like that, we’ve created our very first migration!

Configuring FluentMigrator

Writing a migration is only half the battle and we still need an engine to execute it. In the FluentMigrator, this is handled by the Runner.

Since it will be running the migration process, we will need a different NuGet package responsible for that. This is also the place you specify what database engine you are using.

Unlike the core library, the runner needs to be aware of the platform because it needs to know how to talk to the kind database we are using. Since we are using PostgreSQL for this project, we need to add the runner and its Postgres-specific implementation:

cd src/Todo.Infrastructure
dotnet add package FluentMigrator.Runner
dotnet add package FluentMigrator.Runner.Postgres

Runners are available for many database engines, including SQL Server, MySQL, SQLite, and Oracle.

With the packages installed, we can configure FluentMigrator within our service collection. There are three key pieces of information the Runner needs:

Which database engine are we targeting?
Where is the database located?
Where are the migration classes stored?

private static IServiceCollection AddMigrations(this IServiceCollection services, string connectionString)
{
    // We point to the assembly containing our migrations
    var migrationsAssembly = typeof(CreateTodoItemsTable).Assembly;

    services
        .AddFluentMigratorCore()
        .ConfigureRunner(runner => runner
            // 1. The database we are targeting
            .AddPostgres()
            // 2. How to connect to the database
            .WithGlobalConnectionString(connectionString)
            // 3. Where to look for the [Migration] attributes
            .ScanIn(migrationsAssembly).For.Migrations()) 
        .AddLogging(lb => lb.AddFluentMigratorConsole());

    return services;
}

By using ScanIn, FluentMigrator will automatically find any class decorated with the [Migration] attribute, ensuring that as your project grows, your configuration doesn't have to.

Now that the runner knows what to do, where to look and how to reach our database, we need to decide when these changes should actually happen.

Automatically Applying Migrations on Startup

In a Web API context, a common and handy approach is to run these migrations during the application startup.

This ensures that the database schema is always in sync with the code currently being deployed before the application starts handling traffic. To keep our Program.cs clean, we can wrap this logic in a small extension method:

public static class DatabaseMigrationHelper
{
    public static void ApplyDatabaseMigrations(this IServiceProvider serviceProvider)
    {
        // We use a scope to ensure the MigrationRunner is properly disposed
        using var scope = serviceProvider.CreateScope();
        var services = scope.ServiceProvider;
        var runner = services.GetRequiredService<IMigrationRunner>();

        // This triggers the execution of all pending "Up" migrations
        runner.MigrateUp();
    }
}

By using MigrateUp, FluentMigrator looks at its internal history table, compares it against the IDs in your code, and only executes the scripts that haven't been run yet.

Finally, we just need to call this method after the DI has been initialized, but before app.Run() is called:

var builder = WebApplication.CreateBuilder(args);

builder
    .Services
    .AddApplication()
    .AddInfrastructure();

var app = builder.Build();

...

+ app.Services.ApplyDatabaseMigrations();

app.Run();

If we run the app and have a look at the console, we will see a lot is going on. On the first run, FluentMigrator creates its history table, VersionInfo, to track which migrations have been applied. It then executes the CreateTodoItemsTable migration:

What’s great about this behavior is that it is idempotent. If we restart the app and check the console again, FluentMigrator detects that the database is already up to date. It opens a transaction, realizes the version matches, and immediately finishes without making any changes.

⚠️ A word of caution: While running migrations on startup is convenient for local development, it can be risky in scaled environments (like Kubernetes). If multiple instances spin up simultaneously, they might race to apply the same migrations.

Moving migrations to a dedicated step in your CI/CD pipeline or another process not only prevents race conditions but also improves security hygiene as it allows your Web app to run with a low-privilege connection string (data manipulation only), while only the deployment runner holds the high-privilege credentials required to actually alter the database schema.

Adding Features and Breaking the Schema

Congratulations! Our Todo app is a massive success. Users are now asking for a new feature: the ability to group tasks into Lists.

Technically, this means we need to create a new TodoLists table and link our existing TodoItems to it via a foreign key, hence breaking the compatibility with our current schema. This is where FluentMigrator shines as it allows us to handle schema changes and data migrations in a single, readable transaction.

This migration is a bit more involved because we have to handle existing data. If we simply added a "not null" foreign key, the migration would fail because the database wouldn't know which list to assign to the old tasks. Here is how we handle it gracefully:

[Migration(2026_03_16_001, description: "Create todo lists and link existing items")]
public class AddTodoLists : Migration
{
    public override void Up()
    {
        var defaultListId = Guid.CreateVersion7();

        Create.Table("TodoLists")
            .WithColumn("Id").AsGuid().NotNullable().PrimaryKey()
            .WithColumn("Title").AsString(128).NotNullable();

        // Add the column as nullable first to handle existing data
        Alter.Table("TodoItems")
            .AddColumn("ListId").AsGuid().Nullable();

        // Seed the default list
        Insert.IntoTable("TodoLists").Row(new
        {
            Id = defaultListId,
            Title = "General"
        });

        // Assign all existing items to the default list
        Update.Table("TodoItems")
            .Set(new { ListId = defaultListId })
            .AllRows();

        // Now enforce the constraint and the relationship
        Alter.Table("TodoItems")
            .AlterColumn("ListId").AsGuid().NotNullable()
            .ForeignKey("FK_TodoItems_TodoLists", "TodoLists", "Id");
    }

    public override void Down()
    {
        Delete.ForeignKey("FK_TodoItems_TodoLists").OnTable("TodoItems");
        Delete.Column("ListId").FromTable("TodoItems");
        Delete.Table("TodoLists");
    }
}

Notice the sequence: we altered the schema, inserted data, updated existing rows, and then enforced the relationship.

This example showcases why FluentMigrator sits in the middle of our spectrum. While we are writing .NET code, we aren't shielded from SQL-related concerns. We still have to respect the relational constraints of the database such as the fact that you can't add a NOT NULL foreign key to a table that already contains data without providing a default value first.

Because this class is now part of our project, any developer who pulls the code and run it will automatically have their local database upgraded to support Lists without having to recreate their database from scratch. Even more valuable: we won't have to do this in production either ensuring all the existing todo items of production won't need to be deleted either, which users surely will appreciate!

Wrapping Up

In this article, we explored the purpose of database migrations and the different philosophies that drive how we evolve schemas from high-level abstractions to raw SQL.

We looked at where FluentMigrator fits into this spectrum, offering a middle ground that provides control without sacrificing the benefits of the .NET ecosystem. We covered its features from the initial setup and dependency injection to handling complex, breaking schema changes while preserving existing data.

While EF Core migrations are a convenient starting point, FluentMigrator is a great choice for developers who want granular control over their schema evolution without the burden of writing and maintaining raw SQL. It achieves a sweet balance by retaining the familiarity of C#, while the library handles the heavy lifting of translating your intent into the correct database-specific dialect.

If you would like to play around with the example, feel free to clone the sources on GitHub!

Photo by Danist Soh on Unsplash

Deserializing Polymorphic JSON in .NET Without Losing Type Safety

Pierre Bouillon — Mon, 02 Feb 2026 06:30:00 +0000

JSON handling is often the bread and butter of an application, as data transit in and out of our project. Unfortunately, we don't always get to choose how they are structured and this can often come with a few challenges when we have to deal with polymorphism.

It may happen that we receive data that comes in different shapes, with some properties overlapping. To tackle this problem, there are a few ways to approach it with more or less type safety.

In this article, we will consider a practical approach, from the most simple, to the most robust.

Our Custom Map of French Hidden Gems

Congrats on your new project! You've just been tasked with building the back-end for a new interactive map of iconic french locations. We will have to ingest data from an external source and pass it on our application.

Unfortunately, the external API is not well structured, and these locations come as a mixed collection of points, with both landmarks and shops in the same array:

[
  {
    "Name": "Bouillon Chartier",
    "Category": "Restaurant",
    "Latitude": 48.8759,
    "Longitude": 2.3587,
    "Description": "Simple french dishes in an authentic 1950s atmosphere.",
    "OpeningHours": "11:30 - 00:00",
    "HasParking": false
  },
  {
    "Name": "Mont Saint-Michel",
    "Period": "Gothic",
    "Latitude": 48.6361,
    "Longitude": -1.5115,
    "Description": "Medieval abbey and UNESCO World Heritage Site."
  },
  {
    "Name": "Grand Café Foy",
    "Category": "Café",
    "Latitude": 48.6930,
    "Longitude": 6.1827,
    "Description": "A french café at the heart of the Place Stanislas.",
    "OpeningHours": "07:30 - 02:00",
    "HasParking": false
  },
  {
    "Name": "Cathedral of Our Lady of Strasbourg",
    "Period": "Gothic",
    "Latitude": 48.5819,
    "Longitude": 7.7513,
    "Description": "Catholic cathedral among the finest examples of Rayonnant Gothic architecture."
  }
]

What was looking like a simple task might prove to be a little harder than anticipated as every entry has some basic geographic coordinates, but different properties based on their type. To make it even worse, there is no clear discriminator such as Type: "Landmark" for instance.

Fortunately, that's no big deal for the .NET devs we are!

The God Object

Deserializing data might seem straightforward at first glance. If a property might not be present, we can simply tell C# that it might be null. This approach, often called a "God Object", crams all possible properties into a single class, regardless of whether they apply to every instance.

From this statement, we can infer the following Location record:

public record Location(
    string Name,
    double Latitude,
    double Longitude,
    string Description,
    // Shop properties
    ShopCategory? Category,
    string? OpeningHours,
    bool? HasParking,
    // Landmark properties
    HistoricalPeriod? Period,
    decimal? EntryFee
);

Digesting the data is now child's play:

var json = "...";
var locations = JsonSerializer.Deserialize<List<Location>>(json);

While this will indeed work, it has one major drawback which is that we never know what kind of location we are currently working with. This will result in plenty of null checks, or if through the code.

Moreover, we are clearly seeing that there are two groups here:

We could later parse our location and map each entry to a typed object, but that does not sounds to be very efficient.

Surely .NET has a better way to handle this kind of situation.

Polymorphic Deserialization

What if instead of creating our model (our Location record) around what the deserializer can handle, we proceed the other way around and define it as our data is structured?

Shaping Our Domain

We just saw that we have two kind of data, with a single common ground, let's represent things that way.

First, we represent our shared properties:

public abstract record MapLocation(
    string Name,
    double Latitude,
    double Longitude,
    string Description
);

Then, the first type, let's say the shop:

public record Shop(
    string Name,
    double Latitude,
    double Longitude,
    string Description,
    ShopCategory Category,
    string OpeningHours,
    bool HasParking
) : MapLocation(Name, Latitude, Longitude, Description);

And finally, the second type we are dealing with, the landmarks:

public record Landmark(
    string Name,
    double Latitude,
    double Longitude,
    string Description,
    HistoricalPeriod HistoricalPeriod,
    decimal? EntryFee
) : MapLocation(Name, Latitude, Longitude, Description)
{
    public bool IsFreeEntry => EntryFee is null;
}

Notice that we can already have some intelligence in the typing? A landmark might not have any entry fee and the model can clearly define that. That was not possible in a meaningful way with our god object where every landmark's property could be nullable.

This looks much closer to the domain we are working with, let's test this out!

var locations = JsonSerializer.Deserialize<List<MapLocation>>(json);

Unfortunately, running the previous code results in the following error:

An unhandled exception of type 'System.NotSupportedException' occurred in System.Text.Json.dll: 'Deserialization of interface or abstract types is not supported.

The serializer is not able to infer what kind of data it should deserialize it into, and removing the abstract won't solve the issue as we won't be able to access either Landmark or Shop property.

What we really need is a way to help the serializer identify what kind of data it is dealing with.

Introducing A Converter

System.Text.Json has exactly the kind of type we are looking for: JsonConverter<T>.

A JsonConverter is type that will help our serializer translates a given type to and from JSON, using the Read and Write method. In our example, we only want to help it reading the data, so we will be focusing on the Read part.

Here is the outline of our new converter:

public sealed class MapLocationJsonConverter : JsonConverter<MapLocation>
{
    public override MapLocation? Read(
        ref Utf8JsonReader reader,
        Type typeToConvert,
        JsonSerializerOptions options)
        => throw new NotImplementedException();

    public override void Write(
        Utf8JsonWriter writer,
        MapLocation value,
        JsonSerializerOptions options)
        => throw new NotImplementedException();
}

If our data had an explicit discriminator, such as $type, we could have used [JsonDerivedType(typeof(...), typeDiscriminator: "...")] and skip this whole part. What makes it tricky here is that the discriminator is implicit by being the presence or the absence of a property.

Focusing on the Read method, we need to find a value in the JSON that will tell us if the current entry is a Shop or a Landmark. There is not a single good answer here, and for the example we will consider that any entry with an HistoricalPeriod property is a Landmark, and a Shop otherwise:

public override MapLocation? Read(
    ref Utf8JsonReader reader,
    Type typeToConvert,
    JsonSerializerOptions options)
{
    using var jsonDoc = JsonDocument.ParseValue(ref reader);
    var root = jsonDoc.RootElement;

    var hasHistoricalPeriod = root.TryGetProperty("Period", out _);

    return hasHistoricalPeriod
        ? root.Deserialize<Landmark>(options)
        : root.Deserialize<Shop>(options);
}

Note that JsonDocument is used here for simplicity, but for large datasets, consider streaming approaches to avoid memory overhead.

We now have to let the serializer know it's there, and try again:

var options = new JsonSerializerOptions
{
    Converters = { new MapLocationJsonConverter() },
};

var locations = JsonSerializer.Deserialize<List<MapLocation>>(json, options);

If we run it again, we can observe that the MapLocation list contains only concrete classes of the appropriate type, hooray!

We can now consume our items with .NET taking care of strongly typing everything.

Wrapping Up

In this article, we tackled the challenge of deserializing polymorphic JSON when no explicit discriminator is available.

We began with a straightforward but somewhat messy approach with a God Object that sacrifices type safety for simplicity. While functional, this method leads to harder debugging and cluttering your code with null checks and reducing maintainability.

We then shifted to a more robust solution using inheritance and a custom JsonConverter. While this requires a bit more upfront effort, it helps ensuring we benefit from the type safety .NET has to offer.

Photo by David Clode on Unsplash

A Comprehensive Guide to State Management with Vanilla Angular

Pierre Bouillon — Mon, 06 Oct 2025 06:00:00 +0000

Photo by Shutter Speed on Unsplash

State management in Angular has come a long way. From raw Observables in global services, to modern and modular stores such as the signal store, passing by heavier Redux implementations: the Angular ecosystem has seen many ways of managing state.

However, since the last few major releases, Angular now also has a different kind of reactive variable with signals. With them, we now have a synchronous and reactive way to interact with and react to our data, things that were previously possible with a decent DX mainly through state management solutions.

In this article, we will explore how to manage state without a third party library with a practical use case, and implement the Redux pattern step by step. If you would like to follow along, you can head to the dev.local-state-management repository on GitHub.

Why Managing State At All?

If you already are familiar with state management, you can jump to the next section "Implementing State Management for a Shopping Cart".

In enterprise applications, we often hear about state management, but why do we have to do so? Isn't it simpler and straightforward to have properties in components and interacting with them from here?

Well, yes, and in fact it's an absolutely viable solution for small components, or even small projects. State management is a tool, and like every tool, it helps solving a specific issues such as sharing data across multiple components, keeping the complexity away from multiple components, allowing components to focus on the UI and not the logic, and so on.

If you're not familiar with it, a lot of things in software engineering often falls into the Law of the instrument, which can be summarized as "If your only tool is a hammer then every problem looks like a nail". In this case, state management is not always necessary as its a tradeoff between increased complexity and data consistency.

Moreover, it also allows for simpler tests: if all your logic is abstracted in a store then, when testing your components, you only have to mock the store to test the component's behavior.

A brief introduction to Redux

State management often follows the Redux pattern.

Made popular as a React library back in 2015, Redux is a library and a pattern to manage state in predictable manner.

It consist of a couple of logical groups, each with their own responsibility, allowing for the data to flow only in one way:

The component consumes the state that wraps the data through selectors that exposes parts of it.
It can trigger actions to communicate that something has happened.
Actions will then be captured by pieces of logic that will translate them to an update of the state. There sinks are called reducers.
By updating the state, reducers will cause the selectors to update, and thus update the view.
Additionally, side effects can be triggered upon being notified of an action.

Here is a more graphical view of how this all falls into place:

Managing State in an Angular Application

In Angular, managing state is commonly done with a library, usually with NgRx, NGXS or rxAngular to only cite some of them. However, picking a library is more about preferences since they are all doing a pretty good job at providing building blocks for you to manage your application's state.

But since Angular signals, since started to change, and we now can leverage this reactive primitive to gracefully manage our state in a Redux-like way, without depending on third party library.

Let's see how!

Implementing State Management for a Shopping Cart

Case Study: Le Shop

For this section, we will work on introducing a state management system to the following french food shopping website:

Here are the actions that can currently be performed:

A user can see its cart, with the cumulated total
A user can add items to its cart by clicking the Add to Cart button
A user can clear its cart

For now, all of this is done in the parent component:

@Component({
  selector: 'app-root',
  imports: [ProductCardComponent, CartComponent],
  template: `
    <h2>Le Shop 🇫🇷</h2>

    <div>
      <app-cart [cart]="cart()" (clear)="clearCart()" />

      @if (productsResource.value(); as products) {
        <section>
          @for (product of products; track product.name) {
            <app-product-card [product]="product" (addedToCard)="addItem(product)" />
          }
        </section>
      }
    </div>
  `,
  styles: `...`,
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class App {
  readonly productsService = inject(ProductsService);

  readonly cart = signal<CartItem[]>([]);

  readonly productsResource = resource({
    loader: this.productsService.getProductsStock,
  });

  addItem(product: Product): void {
    this.cart.update((cartItems) => {
      const currentQuantity = cartItems.find(({ name }) => name === product.name)?.quantity ?? 0;

      return cartItems
        .filter(({ name }) => name !== product.name)
        .concat([{ ...product, quantity: currentQuantity + 1 }]);
    });
  }

  clearCart(): void {
    this.cart.set([]);
  }
}

Analyzing the Current Structure

As we said earlier, if the scope doesn't grow and the complexity is manageable, having this kind of code is fine.

However, if new use cases arise, things can be a bit harder to keep organize. For instance, look back at the code, and think of how you would successively add:

A toast to notify the user of the product he just added
A way to apply discounts
A button to be notified of when a product that is currently out of stock becomes available

Apart from the business cases, this also presents some technical downsides since this component has a lot of responsibilities (managing the cart logic, presenting the data, ...).

Since most of the logic lives here, it would not be possible to share it with other components either. If one day we had to add a small cart icon in the navbar with the current total, we would have a hard time doing so.

In summary, this component:

Will be more and more bloated as it supports more and more use cases
Mixes business logic with UI orchestration
Is harder to test than it could be
Can't easily share its state

Fortunately, we know what Redux is, and are about to introduce a brand new store!

Creating the Store

To create our store, we will focus on each part one after the other, starting by the state.

Defining the State

Before writing any code, we have to identify what our state is currently made of. On the top of our head, we can identify a few properties:

The current loading status
The listed products
The added items

We could also have add an error message if the loading failed, but for the sake of the example, we will keep it short here, feel free to implement it!

We can now translate the contract defining our state, and wrap it in a signal to be able to synchronously access it, but also to react to a change if needed:

export interface AppState {
  addedProducts: CartItem[];
  isLoading: boolean;
  products: ListedProduct[];
}

@Injectable()
export class AppStore {
  readonly #state = signal<AppState>({
    addedProducts: [],
    isLoading: false,
    products: [],
  });
}

That's a great start, but we don't have any way to actually interact with our store, let's work on it.

Adding Events

Events are things that happened. They often have to properties:

They are asynchronous, and can usually be triggered in any order, at any time
They carry a payload, that can be identical if the same thing is emitted (for instance, if we add the same product twice, it would result in the same event being fired twice, with the same product)

Since events are asynchronous and can be identical, Observables are a good fit to represent them. We can represent those events as emitted by those sources.

This could also have been done with signals by overriding the equality check to always be false, and thus allowing for the same payload to be sent twice. However, I am personally not found of this way of representing sources since it kind of defies one of the primary properties of signals.

In our case, we have a few things that can be represented as events:

The cart is cleared
A product is added to the cart
Products are loaded

Each of them can be emitted, with their payload, by the following sources:

readonly #cartCleared = new Subject<void>();
readonly #productAddedToCart = new Subject<{ product: Product }>();
readonly #productsLoaded = new Subject<{ products: ListedProduct[] }>();
readonly #productsLoading = new Subject<void>();

Did you notice? All events are using the past tense. This is a way of representing that something has happened.

However, we don't want to expose these properties since they are part of how the store is orchestrating with its state. For instance, we don't want a Component to instruct the store of which products were loaded, since it's not its responsibility.

We can instead expose a public API to allows only some actions to be triggered by the consumers. This is what is called actions:

addProductToCart(product: Product): void {
  this.#productAddedToCart.next({ product });
}

clearCart(): void {
  this.#cartCleared.next();
}

We can now emit event, but we still are not interacting with the state, and that's where reducers come into play.

Creating Reducers

Reducers are pieces of code that listen for events, and update the state depending of their payload.

It's important to notice that they are the only part of the store that can temper with the state.

Since our events are represented as Observables, we can write our reducers as Subscriptions to each of our events:

constructor() {
  this.#cartCleared
    .pipe(takeUntilDestroyed())
    .subscribe(() => this.#state.update((state) => ({ ...state, addedProducts: [] })));

  this.#productAddedToCart.pipe(takeUntilDestroyed()).subscribe(({ product }) =>
    this.#state.update((state) => {
      const currentQuantity =
        state.addedProducts.find(({ name }) => name === product.name)?.quantity ?? 0;

      const updatedCart = state.addedProducts
        .filter(({ name }) => name !== product.name)
        .concat([{ ...product, quantity: currentQuantity + 1 }]);

      return { ...state, addedProducts: updatedCart };
    }),
  );

  this.#productsLoaded
    .pipe(takeUntilDestroyed())
    .subscribe(({ products }) =>
      this.#state.update((state) => ({ ...state, products, isLoading: false })),
    );
}

Almost there! Unfortunately, since the components cannot tell which products are loaded, we need a way to trigger this programmatically.

Introducing Effects

Simply put, effects are events that trigger others. Applied to our application, we can think of the resource's change of loading state or value as events, and trigger the appropriate events accordingly.

Let's first grab the resource:

readonly #productsService = inject(ProductsService);

readonly #productsResource = resource({
  loader: this.#productsService.getProductsStock,
});

We can now react to the changes, and propagate the desired event:

effect(() => {
  const products = this.#productsResource.value();

  if (products) {
    this.#productsLoaded.next({ products });
  }
});

effect(() => {
  const isLoading = this.#productsResource.isLoading();

  if (isLoading) {
    this.#productsLoading.next();
  }
});

Funny thing that the signals package is exposing an effect method that is great for us to .. propagate effects!

And just like that, our state is now holding the business logic of our application, with the data always flowing in one direction:

User actions or effects can trigger actions
actions emit events
events are captured by reducers
reducers update the state

Our state is now looking great, with just a small issue: there is no way to read the state from an external consumer.

Exposing Selectors

Selectors are ways to reactively expose parts of the state.

For instance, we want to access what the content of the cart is, and see its content updated dynamically.

Fortunately, our state is already reactive since it's a signal, and derived, read only, parts of a signal, is the textbook definition of a computed.

This makes the selectors fairly easy to write:

readonly addedProducts = computed(() => this.#state().addedProducts);
readonly products = computed(() => this.#state().products);

We are not using the isLoading property in this example, but feel free to expand the example with your own usages!

Our store is now successfully implementing the Redux pattern. If we take a look back at the previous diagram, here it is, applied to our case:

With a functioning store, and the proper ways to interact with it, we can now remove the business logic of our component with the store we just created.

Using The Store

Before using our store, remember to provide it just like any other service. In this example, it will be provided at the AppComponent level, as its component store. For global state, you can of course use @Injectable({ providedIn: 'root' }) or directly provide it in the appConfig.

@Component({
  selector: 'app-root',
  imports: [ProductCardComponent, CartComponent],
  template: `...`,
  styles: `...`,
  providers: [AppStore],  // 👈 Provided here
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class App {
  readonly store = inject(AppStore);
  // ...
}

Now that it's provided, we can replace all the business logic with our store's properties:

@Component({
  selector: 'app-root',
  imports: [ProductCardComponent, CartComponent],
  template: `
    <h2>Le Shop 🇫🇷</h2>

    <div>
      <app-cart [cart]="store.addedProducts()" (clear)="clearCart()" />

      @if (store.products(); as products) {
        <section>
          @for (product of products; track product.name) {
            <app-product-card [product]="product" (addedToCard)="addItem(product)" />
          }
        </section>
      }
    </div>
  `,
  styles: `...`,
  providers: [AppStore],
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class App {
  protected readonly store = inject(AppStore);

  addItem(product: Product): void {
    this.store.addProductToCart(product);
  }

  clearCart(): void {
    this.store.clearCart();
  }
}

Our component now only focuses on orchestrating the UI, and is stripped of any business logic's considerations.

With this refactor, we addressed the issues we faced:

If we were to test the component, we would only have to mock the AppStore
If we had to share the state, we could provide the store higher in the hierarchy and consume it elsewhere
If we had to add a new feature, the store would wrap that logic and integrate it with the existing state

Takeaways

In this article, we explored what Redux is, what problems it solves, and how to implement this pattern in an Angular application without introducing a third-party library.

Beyond simplifying our code, this approach brings clear separation of concerns: components focus solely on UI orchestration while the store handles all business logic. This separation makes testing significantly easier, as we can test the store's logic independently and mock it entirely when testing components.

The state holds our application data in a reactive signal, while actions provide a public API for triggering changes. Events represent things that have happened and are emitted through Subjects, which reducers listen to as the sole updaters of state. Effects handle side effects and trigger other events, and selectors expose reactive, read-only slices of state through computed signals.

State management often feels like something reserved for complex applications with heavy dependencies, but as we've seen, it's actually quite accessible. By leveraging Angular's native signals and RxJS Observables, we built a fully functional Redux-like store using nothing more than the tools that Angular already provides.

This doesn't mean that libraries like NgRx, NGXS, or RxAngular don't have their place. They offer additional features, conventions, and tooling that can be valuable for larger teams or more complex scenarios. However, understanding that you can achieve effective state management with "simple" Angular code empowers you to make informed decisions about when a library is truly necessary and when the framework's built-in capabilities are more than sufficient for your needs.

If you are interested in learning more about reactivity, I wrote two chapters in my book "Modern Web Development with Angular", which you can find on Amazon 👇

My Attempt at Neobrutalism with Svelte: Redesigning my Website

Pierre Bouillon — Wed, 20 Aug 2025 08:01:44 +0000

It's been a while since the last time I woke up and decided my portfolio wasn't what I wanted anymore.

My personal website has two purposes:

Serving as references when recruiters ask for my résumé or projects
Trying out new things that I might not be able to professionally at the time

The first one is the core purpose of the site, but the second one is far more entertaining.

Last time, I discovered Analog as a way to create static website with Static Site Generation (or SSG), and decided to try it out:

This time, I noticed a lot has been going on with Svelte and SvelteKit for the past releases: a new major version, a great i18n library with Paraglide JS, their own signal variants with runes and so on.

Moreover, Tailwind released its v4 at the beginning of this year. In the meantime, I also discovered neobrutalism, a specific aesthetic that I wanted to try out.

With the tech stack being set (Svelte + SvelteKit, Paraglide JS, TailwindCSS v4), and a goal (attempting to use neobrutalism), I was all set:

This article is less about the technical details of the rewrite, and more about what I've done and how.

Prefer to see the result first? You can visit it here:

👉 Jump to the website

What is Neobrutalism

Before jumping straight to my editor, I first had to clearly identify what neobrutalism was for me.

I'm not very good at designing sleek UIs (and have a lot of respect for people who can), but I do enjoy building interfaces that stand out, even if ‘polished’ isn’t the first word that comes to mind.

Luckily, I found a lot of great resources that cover and explain what neobrutalism is about. The best definition I've found, is the quote from this article:

As a UI design style, neobrutalism focuses on raw, unrefined elements like bold colors, simple shapes, and intentionally "unfinished" aesthetics.

Unlike Material Design, it’s not a rigid system. It’s more about breaking conventional design rules intentionally.

Neobrutalism isn’t one-size-fits-all. These sites, for example, share its hallmarks: bold contrasts, raw edges, and big elements:

Contrasting with the minimalistic, rounded designs we often see, such as LinkedIn's:

My Attempt at it

My main goal was still clarity: recruiters need to grasp my profile quickly. But that didn’t mean sacrificing personality, and that's an important point for me.

Main Section

I started with the main section, as a way to condense a short presentation and the main external links, using rough borders and light animations to make everything more pleasant to interact with:

Experiences

Experiences are usually sections with a lot of details, and packing in duration, title, location, content, and type (pro/personal) without overwhelming visitors wasn't easy.

I explored different options (cards, lists, ...) and decided that a timeline would let me organize this visually, balancing details with simplicity, allowing me to express some of these information as visual elements as well:

The duration is presented as a label on the top of the card
The title and location (if present) as headers
The content as ... content
The experience type with the type of line that is being drawn on the timeline.

Here's the result:

As a bonus, the current experience's landmark has a nice "ping" animation!

Articles

In the past few years, I've written a few articles on DEV (and even published a book!).

It was important for me to feature this section on the website, as it shows that I'm still interested and publishing about things in tech.

DEV.to has a great API and made it easy to pull article data. There is a lot you can do with it but I kept it simple: title, date, description, and a link to the article.

With a nice animation, and by playing with the colors, I was able to create this overview:

It's also absolutely possible to load more article if the user wants to, thanks to a button at the end.

Projects

Finally, aside from work and writing from time to time, I get occasionally involved in some other projects.

These are usually things I'm proud of, or just happy to share, but the main difficulty was to find a way to present projects that can be widely different: what layout could suit both a coding project and a teaching experience while tying them together cohesively?

In the end, I picked a simple card but with a label to categorize them, as well as an optional link to the original resource:

Conclusion

All in all, I'm pretty happy with the result: it does a better job of showcasing my work and adding context.

Of course, things could be better, but so far everything is generated during the build step, published on GitHub with a CI/CD pipeline, with a French and an English version available, and I find it much clearer than the former version ... until next year probably!

Check out the website and see for yourself!

Setup PocketBase For Your Integration Tests with TestContainers and xUnit

Pierre Bouillon — Mon, 04 Aug 2025 06:30:00 +0000

I've recently started writing about how I'm building PocketBase.Net in the Building PocketBase.Net Step by Step series.

However, I haven't had the opportunity to go over what was already in place. In particular, having a robust testing suite with both unit and integration tests was a very important point for me, as the library could potentially be used by others to manage their data, which is often the most critical part of applications.

In this article, I will explain how I set up a working testing environment for my integration tests, using a dockerized PocketBase instance with TestContainers.

A short Introduction to Integration Testing

As software engineers, we are (I hope) used to testing our code. However, there are a lot of ways to test it, with the most common from my experience being:

"Local" testing: you just developed a feature and you run it locally, in your environment, to ensure it is working
Unit testing: you are asserting that your method, given a precise input and no (or simulated) dependencies, returns the expected result. It is usually written in three acts: Arrange (prepare the system), Act (perform the operation) and Assert (ensure that the result is the expected one).

In C#, a unit test can be as simple as:

public void Calculator_Multiply_ReturnsPositiveValueForNegativeNumbers()
{
    // Arrange: the system is created in isolation
    var calculator = new Calculator();

    // Act: a single operation is performed
    var result = calculator.Multiply(-4, -2);

    // Assert: we test operation's result
    result.ShouldBeGreaterThan(0);
}

However, unit tests can lack of context in more complex scenarios. For instance, you might be sure that a method is working in isolation, but when chained with many other method calls it might not. In the same way, your dependencies (email service, database, authentication system, etc.) might not be interacting with it correctly.

To ensure those cases are covered as well, you can write integration tests, which will give you a bit more confidence about how your code is behaving when considered in its globality, with its dependencies and external systems.

📝 NOTE:
We often speak about test pyramid to represent the types of tests and their number.

If you were not already familiar with testing and want to dive deeper, I highly recommend you to read the resources on the Software Testing Guide by Martin Fowler.

Integration Testing in PocketBase.Net

In the case of PocketBase.Net, I wanted to be sure that the logic tested in my unit tests, was correctly integrating with PocketBase once plugged to it.

Creating a Testing PocketBase Instance

To ensure that the code works with PocketBase, I had to interact with a real instance. I considered two options:

Running an instance somewhere, either locally or hosted.
Creating a dockerized instance that would be destroyed once the tests are completed.

I picked the second option as I thought it was the best approach to still have an isolated and reproducible environment, even from the CI.

Introducing TestContainers

Fortunately, there is an awesome project for that named TestContainers.

TestContainers is a library that allows you to run a docker container programmatically in a few lines, using the builder pattern:

// Create a new instance of a container.
var container = new ContainerBuilder()
  .WithImage("xxx/yyy:1.2.0")
  .Build();

// Start the container.
await container.StartAsync();

All we need to get started with this library is to have Docker on our system, and an image to use.

Creating Our PocketBase Container

To get started with our dockerized version of PocketBase, we have to pick a Docker image from the many available on DockerHub:

In this article, as for PocketBase.Net, we will be using adrianmusante/pocketbase.

📝 NOTE:
Choose your image carefully as you might have some security requirements to consider.

Writing our builder only needs a few lines:

new ContainerBuilder()
    .WithImage("adrianmusante/pocketbase:0.28.4")
    .Build();

But we can actually go further with all the available options.

For instance, we can bind the ports, run migrations, define an administrators, and much more:

new ContainerBuilder()
    .WithImage("adrianmusante/pocketbase:0.28.4")
    // 👇 Bind port 8080
    .WithPortBinding(PocketBasePort, true)
    // 👇 Wait for the health check to respond
    .WithWaitStrategy(
        Wait.ForUnixContainer()
            .UntilHttpRequestIsSucceeded(r => r
                .ForPort(PocketBasePort)
                .ForPath("/api/health")
                .WithMethod(HttpMethod.Get)))
    // 👇 Delete the container once shut down
    .WithCleanUp(true)
    // 👇 Setup an administrator
    .WithEnvironment("POCKETBASE_ADMIN_EMAIL", AdminCredentials.Identity)
    .WithEnvironment("POCKETBASE_ADMIN_PASSWORD", AdminCredentials.Password)
    // 👇 Install and run migrations
    .WithResourceMapping(
        source: migrationsDirectory,
        target: "/pocketbase/migrations")
    .Build();

Now that our builder is defined, let's see how to integrate it in our xUnit test suite!

Using the Container with xUnit

When sharing context between test classes, xUnit suggests using fixtures such as IClassFixture<>.

This is especially useful since it supports having an asynchronous workflow during the setup of your test context, simply by implementing IAsyncLifetime. In our case, running the container is an asynchronous operation since we have to wait for it to be up.

Let's create our fixture for our container to be used in our tests:

public class PocketBaseFixture : IAsyncLifetime
{
    ...

    public PocketBaseFixture()
    {
        // 1️⃣ Create the container builder
        _pocketBaseContainer = new ContainerBuilder()
            ...
            .Build();
    }

    public async Task InitializeAsync()
    {
        // 2️⃣ Start the container
        await _pocketBaseContainer
            .StartAsync()
            .ConfigureAwait(false);

        // 3️⃣ Retrieve the container's details
        var pocketBaseBaseUrl =
            $"http://{_pocketBaseContainer.Hostname}:" +
            $"{_pocketBaseContainer.GetMappedPublicPort(PocketBasePort)}";

        // 4️⃣ Interact with the container
        ServiceProvider = new ServiceCollection()
            .AddPocketBase(
                serverUrl: new Uri(pocketBaseBaseUrl),
                credentials: AdminCredentials)
            .AddPocketBaseRepositories(scanningAssembly: typeof(TodoItemRecord).Assembly)
            .BuildServiceProvider();
    }

    public async Task DisposeAsync()
    {
        // 5️⃣ Stop everything properly
        await _pocketBaseContainer
            .StopAsync()
            .ConfigureAwait(false);
    }
}

With the fixture being defined, we now need to indicate xUnit to use it for our test class:

// 👇 Tells xUnit the fixture to use
public class AuthenticationTests(PocketBaseFixture fixture)
    : IClassFixture<PocketBaseFixture>
{
    [Trait("scenario", "happy path")]
    [Fact(DisplayName = "Authentication should succeed with valid admin credentials")]
    public async Task AuthenticateUsing_WithValidCredentials_ShouldReturnAuthenticatedUser()
    {
        // Arrange
        var client = fixture.ServiceProvider.GetRequiredService<PocketBaseHttpClientWrapper>();

        // Act
        // 👇 Makes an HTTP call to our dockerized pocketbase instance 
        var user = await client.AuthenticateUsing(
            fixture.AdminCredentials,
            CancellationToken.None);

        // Assert
        user.ShouldNotBeNull();
        user.Email.ShouldBe(fixture.AdminCredentials.Identity);
        client.IsAuthenticated.ShouldBeTrue();
    }
}

When running our test, we can now be sure that AuthenticateUsing is working correctly with a real PocketBase instance:

Closing thoughts

In this article, we saw what integration tests are, how to take advantage of docker in C# with TestContainers and how to harness our container for our xUnit test suite.

I hope this article gave you some insights about how you could be using either PocketBase or TestContainers for your next projects!

If you would like to have a look at the PocketBase.Net integration tests to see the full code.

Our First Issue: Enhancing Queries With Sorting

Pierre Bouillon — Thu, 24 Jul 2025 12:24:48 +0000

Welcome back for the next step on our journey building PocketBase.Net!

Today we will be working on enhancing queries, by working on the issue #5 Add sorting support on queries.

The Issue
Development Process
- Defining Our Goals
- Implementation
  - Setup
  - Implementing WithSorting
  - Writing the Acceptance Test
  - Implementing the Sorting
  - Running Our Tests
  - Creating the Sorting String Builder
- Finishing Touches
Closing Thoughts

The issue

So far, PocketBase.Net allows for developers to filter results and paginate a search, but not for sorting.

For instance, if you would like the ten first users whose name starts with P, but starting from the youngest ones, it is not something you can do natively (unless fetching all users whose name start with P and then do the sorting yourself).

However, this is not a PocketBase limitation, since the feature does exist and is documented in the web API reference:

Development Process

Defining Our Goals

Before diving head first into the task, we must first have a look at how queries are structured as of now. For that, we can have a look at the repository integration tests:

var singlePagedCompletedTodoItem = await repository
    .Query()
    .WithFilter(completedTodoItemsSearchFilter)
    .WithPagination(new PaginationOptions
    {
        ItemsPerPage = 1,
        PageNumber = 1,
    })
    .ExecuteAsync();

We can notice that sorting and filtering share some common ground. Both of them consist of a string and both of them should respect a specific syntax (despite the sorting string being much more simple since it does not need grouping or logic operators).

Based on the existing code and this remark, we can think about building the feature in the same way we built the filtering: by accepting a raw string as a sorting parameter, but also providing a C# class that would help us building one with a fluent pattern.

Something like this:

var singlePagedCompletedTodoItem = await repository
    .Query()
    .WithFilter(completedTodoItemsSearchFilter)
    // 👇 Using a raw sorting string
    .WithSorting("-viewCount,title")
    .WithPagination(...)
    .ExecuteAsync();

With the possibility to build the filter separately:

var sortByMostViewedThenAlphabetically = Sort
    .ByDescending("viewCount")
    .ThenBy("title")
    .Build();

var singlePagedCompletedTodoItem = await repository
    .Query()
    .WithFilter(completedTodoItemsSearchFilter)
    .WithSorting(sortByMostViewedThenAlphabetically)
    .WithPagination(...)
    .ExecuteAsync();

📝 NOTE
I tend to prefer Descending rather than Desc or Administrator rather than Admin since abbreviations can be unclear sometimes (for example, you probably don't want to abbreviate Analytics).

Looks like we're good to go! Now our goals are set:

Add a WithSorting method to queries
Implement a way to build a sorting string separately

Implementation

Setup

Before working on the issue, I will first start by creating my branch to work on this task, as stated in the CONTRIBUTING.md file:

git checkout -b 5-add-sorting-support-on-queries

Make sure Docker is up and running, open the solution, and let's get started!

Implementing WithSorting

Writing the Acceptance Test

We will start by covering the new use case in the integration test, and work from here to get the implementation right.

Just so we can write the test, we have to define the method first:

// 📂 QueryBuilder.cs

/// <summary>
/// Defines how the results should be sorted for the query.
/// </summary>
/// <param name="sorting">The sorting to apply.</param>
/// <returns>The builder instance for method chaining.</returns>
public QueryBuilder<TRecord> WithSorting(string sorting)
    => this;

📝 NOTE
The logic is not yet added, we will do so to make our test pass once written.

Since in our tests we are working with TodoItem, we can design the following test:

Given one completed task and one pending task
Retrieve all of them, sorted first on their status in descending order and then on their name
Ensure the order is correct
Retrieve all of them again, sorted first on their status in ascending order and then on their name in descending order
Ensure the order is still correct

Here is what it looks like:

// 📂 RepositoryTests.cs

public async Task RepositoryOperations_ShouldBehaveAsExpected()
{
    // ...

    // Sorting results
    var todoItemsByDescendingStatusThenByAlphabeticalOrder = await repository
        .Query()
        .WithSorting("-isCompleted,description")
        .ExecuteAsync();

    todoItemsByDescendingStatusThenByAlphabeticalOrder.ShouldSatisfyAllConditions(
        (todoItems) => todoItems.Items[0].ShouldBeEquivalentTo(completedTodoItemEntity),
        (todoItems) => todoItems.Items[1].ShouldBeEquivalentTo(pendingTodoItemEntity));

    var todoItemsByStatusThenByDescendingAlphabeticalOrder = await repository
        .Query()
        .WithSorting("isCompleted,-description")
        .ExecuteAsync();

    todoItemsByStatusThenByDescendingAlphabeticalOrder.ShouldSatisfyAllConditions(
        (todoItems) => todoItems.Items[0].ShouldBeEquivalentTo(pendingTodoItemEntity),
        (todoItems) => todoItems.Items[1].ShouldBeEquivalentTo(completedTodoItemEntity));

We now have a failing test that we can run to test our implementation.

Implementing the Sorting

In order to store the sorting, we will have to add a new property to the Query object to represent it, which is pretty straightforward:

// 📂 Query.cs

/// <summary>
/// Sorting to apply on the search results. Defaults to an empty string.
/// </summary>
public string Sorting { get; init; } = string.Empty;

📝 NOTE
null values can make our life harder sometimes. When possible, I prefer to use empty values instead, such as string.Empty.

Now that the property is added, we can update the logic of WithSorting:

// 📂 QueryBuilder.cs

public QueryBuilder<TRecord> WithSorting(string sorting)
{
    _query = _query with { Sorting = sorting };
    return this;
}

With our query now successfully holding and passing the value of the filter, we now have to use the sorting upon executing the query. This will require us to update both the repository and the client:

// 📂 IRepository.cs

public class Repository<TRecord>(
    IPocketBaseClient pocketBaseClient,
    PocketBaseClientConfiguration configuration,
    RecordValidator<TRecord> validator
) : IRepository<TRecord>
    where TRecord : RecordBase
{
    // ... 

    public Task<Paged<TRecord>> GetRecords(
        Query<TRecord>? query,
        CancellationToken cancellationToken = default)
        => pocketBaseClient.GetRecords<TRecord>(
            CollectionName,
            query?.Filter,
            query?.PaginationOptions,
            // 👇 Propagate the parameter
            query?.Sorting,
            cancellationToken);
}

📝 NOTE
I said I prefer not to use null where possible, but I started with default parameters as null. This is why I am using this value again, to keep the API consistent with the other parameters. In a future task, it could be better to smoother the DX by using empty values here too.

And now onto the client:

📂 IPocketBaseClient.cs

public interface IPocketBaseClient
{
    // ...

    Task<Paged<TRecord>> GetRecords<TRecord>(
        string collectionIdOrName,
        string? filter = null,
        PaginationOptions? paginationOptions = null,
+       string? sorting = null,
        CancellationToken cancellation = default
    ) where TRecord : RecordBase;
}

public class PocketBaseClient(
    PocketBaseClientConfiguration configuration,
    PocketBaseHttpClientWrapper httpClientWrapper
) : IPocketBaseClient
{
    // ...

    /// <inheritdoc/>
    public Task<Paged<TRecord>> GetRecords<TRecord>(
        string collectionIdOrName,
        string? filter = null,
        PaginationOptions? paginationOptions = null,
+       string? sorting = null,
        CancellationToken cancellationToken = default
    ) where TRecord : RecordBase
        => httpClientWrapper.SendGet<TRecord>(
            collectionIdOrName,
            filter,
            paginationOptions,
+           sorting,
            cancellationToken);

📝 NOTE
At this point, parameters count are starting to grow everywhere, it might be worth considering propagating the query in itself at some point.

Finally, we will have to append the sorting to the query parameters:

📂 PocketBaseHttpClientWrapper.cs

public Task<Paged<TRecord>> SendGet<TRecord>(
    string collectionIdOrName,
    string? filter = null,
    PaginationOptions? paginationOptions = null,
+   string? sorting = null,
    CancellationToken cancellationToken = default
) where TRecord : RecordBase
{
    var query = AppendQueryParameters(
        $"/api/collections/{collectionIdOrName}/records",
        string.IsNullOrEmpty(filter) ? null : $"filter=({filter})",
+       string.IsNullOrEmpty(sorting) ? null : $"sort={sorting}",
        paginationOptions?.ToQueryParameters());

    return SendRequest<Paged<TRecord>>(
            (httpClient) => httpClient.GetAsync(query, cancellationToken),
            onErrorThrow: (_) => new RecordSearchFailedException(),
            cancellationToken);
}

📝 NOTE
If we would be passing the Query here instead, we could delegate the construction of the query parameters to the class, resulting in a better encapsulation and cleaner code.

Running Our Tests

With the sorting parameter handled and propagated, we can now run our test again, and ensure it is passing:

Great! We can now commit and push our changes on GitHub.

Onto the next part!

Creating the Sorting String Builder

Writing the sorting ourselves is indeed possible, but people might want to use variables, or have a sorting a bit more complex.

To support that kind of use cases, we can create a builder in the same way a builder already allows for complex filters to be written, such as:

var filter = Filter.Field("id").Equal(37)
    .And().Grouped(
        Filter.Field("age").GreaterThanOrEqual(18)
        .Or().Field("role").Like("admin"))
    .And().Field("isVerified").Equal(true)
    .Build();

// Produces: id=37 && (age>=18 || role~"admin") && isVerified=true

In the same spirit, here is how we could implement a builder for our sorting string:

// 📂 SortBuilder.cs

namespace PocketBase.Net.Client.Entities;

public sealed class Sort
{
    private readonly Queue<string> _sortSections = new();

    private Sort(string seed)
        => _sortSections.Enqueue(seed);

    public static Sort By(string fieldName)
        => new(fieldName);

    public static Sort ByDescending(string fieldName)
        => new(AsDescendingField(fieldName));

    public Sort ThenBy(string fieldName)
    {
        _sortSections.Enqueue(fieldName);
        return this;
    }

    public Sort ThenByDescending(string fieldName)
    {
        _sortSections.Enqueue(AsDescendingField(fieldName));
        return this;
    }

    private static string AsDescendingField(string fieldName)
        => '-' + fieldName;

    public string Build()
        => string.Join(',', _sortSections);
}

Once the documentation added, we can add some unit tests to ensure that everything is working properly. For that, we can ask Le Chat to generate the following:

// 📂 SortBuilderTests.cs

public class SortBuilderTests
{
    [Fact(DisplayName = "Build should return correct sort string for multiple fields")]
    public void Build_ShouldReturnCorrectSortStringForMultipleFields()
    {
        // Arrange
        var sort = Sort.ByDescending("name")
            .ThenBy("age")
            .ThenByDescending("date");

        // Act & Assert
        sort.Build().ShouldBe("-name,age,-date");
    }
}

Since the test is passing, we can now use that instead in our integration tests:

+ var sortByStatusDescendingThenName = Sort
+     .ByDescending("isCompleted")
+     .ThenBy("description")
+     .Build();

var todoItemsByStatusDescendingThenName = await repository
    .Query()
-     .WithSorting("-isCompleted,description)
+     .WithSorting(sortByStatusDescendingThenName)
    .ExecuteAsync();

...

+ var sortByStatusThenNameDescending = Sort
+     .By("isCompleted")
+     .ThenByDescending("description")
+     .Build();

var todoItemsByStatusThenNameDescending = await repository
    .Query()
-     .WithSorting("isCompleted,-description)
+     .WithSorting(sortByStatusThenNameDescending)
    .ExecuteAsync();

We can run all our tests once more, to ensure everything is still working properly:

Great! We can now commit and push those changes as well.
You can have a look on GitHub at the commit.

Finishing Touches

We are almost done, but we still have to document our changes by updating the README:

We also have to remember to delete the part stating that sorting was not yet supported.

Now that everything is neatly finished, it's time to publish the PR: https://github.com/pBouillon/PocketBase.Net/pull/11

All checks are passing, the feature is implemented, tested and documented: we can now merge the changes, close the issue and delete our branch. 🚀

Closing Thoughts

And voilà:

We successfully implemented the task, from its definition, to its final implementation passing by its design and test cases.

We still have plenty of other features to add but that's one less now!

Thanks for keeping up so far, and feel free to make your own suggestions in comments or directly by creating a new discussion on GitHub!

Launching and Building PocketBase.Net in the Open

Pierre Bouillon — Wed, 23 Jul 2025 10:29:59 +0000

After over six months without writing, I'm back and starting a new series about my latest open-source side project.

In this series, I'll be showing how I'm building this project. The goal is to tackle each issue one by one in dedicated articles, documenting the development process and the challenges I face.

The project is already open source, so why not share the thoughts behind it as well?

But first things first: in this article, let me introduce PocketBase.Net, the project's goals, its current status, and what the next steps are.

Presenting PocketBase.Net
- What is PocketBase
- Working with PocketBase
- Introducing PocketBase.Net
Current State
What's Next
Building with You

Presenting PocketBase.Net

In one sentence, PocketBase.Net is a library that aims to make PocketBase easy to work with in dotnet projects.

What is PocketBase

PocketBase is a lightweight backend as a service (BaaS) that uses SQLite under the hood.

Unlike other popular BaaS such as Firebase, Supabase, and others, you can spin up a new instance of PocketBase simply by running a single executable.

This makes it incredibly easy to get started locally, dockerize, or even host it.

Out of the box, PocketBase allows you to manage your data in collections, handle authentication, rights, and protect some operations with rules. You can also get notified of real-time updates and much more.

If you have not already, I highly encourage you to check out the project on https://pocketbase.io, or watch this nice 3:30 Fireship video about it:

Working with PocketBase

Once spun up, you can interact with your PocketBase instance using the JS SDK, the Go SDK, or through its web API.

For instance, here is how you could retrieve products from your instance:

GET https://[Your Instance]/api/collections/products/records

You can also access the web view to see your data, update the collection rules, integrate new login method such as OAuth third parties such as GitHub, see logs and much more.

Introducing PocketBase.Net

Given that the web API has a pretty exhaustive documentation and that no official .NET SDK is available, PocketBase.Net is my attempt to provide one for .NET developers who would like to use PocketBase as their database.

The goal is to make working with PocketBase simple from a .NET project, using idiomatic C#.

Using this library, any developer should be able to perform basic CRUD operations and leverage PocketBase capabilities.

Current State

As of the time of writing, I have just open-sourced the project with its bare minimum features.

So far you can already:

Authenticate your client to perform actions as a specific account
Create, Read, Update and Delete records
Query data with more complex requirements such as filters or pagination
Use dynamically created repositories for each of your entities

Here is quick glance at some of the operations you can do with PocketBase.Net:

var article = new
{
    IsPublic = true,
    Name = "Getting Started With PocketBase.Net",
};

var articleRecord = await articleRepository.CreateRecordFrom(article);

var draftArticleRecord = await articleRepository.UpdateRecord(
    articleRecord.Id,
    article with { IsPublic = false });

var draftsArticleRecords = await articleRepository
    .Query()
    .WithFilter("isDraft=true")
    .ExecuteAsync();

The project also features:

A unit tests suite (that could use some more tests if you feel like helping!)
An integration tests suite, using a dockerized PocketBase instance with TestContainers to ensure real world scenario are covered
A CI step running on GitHub Actions
A comprehensive XMLdoc and a detailed README about the library's usage

What's next

The library is far from finished an lacks some of the core features you would expect.

First of all, there is no NuGet package published yet. Some operations are also not supported at this time, such as sorting or relationships.

For each of those tasks, and the others to come, I will create an issue on GitHub.

Once started, I will document in a new article the development process for that task, from its scope, to the final implementation and documentation.

Building with You

If you would like to join this small open source journey, you are more than welcome to do so, and there are several ways for you to get involved!

You can, of course, write some code, document or test the project (be sure to have a look at the contribution guidelines before checking the opened issues), but you can also write suggestions on the GitHub discussions or in comments.

Depending on what happens during the lifetime of the library, I might also write about how review pull requests and incoming contributions.

That's all for today's post!

I hope you are as excited about this modest adventure as I am, and I can't wait to see where it will go.

Stay tuned for the next upcoming feature and article!

This post was proofread by Le Chat, that also generated the image

My First Book: Modern Web Development with Angular

Pierre Bouillon — Fri, 06 Dec 2024 23:35:59 +0000

Hi everyone!

This is a bit of an off-topic post, breaking from my Angular-related content series, to announce that I have published my first book with Duncan Faulkner.

"Modern Web Development with Angular Build Cutting-Edge, Scalable Web Apps from Scratch with Angular, TypeScript, and Reactive Programming" is a book aimed at newcomers to Angular, helping them getting started from the ground up with the framework.

In it, you will find a step-by-step guided journey through Angular, covering best practices and hands-on exercises to help you become familiar with the framework.

I had the opportunity to write it thanks to This is Angular and especially @layzee which let me know about this opportunity.

This has been a challenging adventure but one that I am very proud of having accomplished and it really is an accomplishment.

You can grab your own copy here 👇
https://www.amazon.com/Modern-Web-Development-Angular-Cutting-Edge/dp/B0DP8LQ597

Have a great day!

Using GitHub as an Authentication Provider in Your Angular App with PocketBase

Pierre Bouillon — Mon, 19 Aug 2024 05:30:00 +0000

Authentication is always a delicate subject since it is one of the core layers guarding your application's features against unwanted access.

There are many ways to handle authentication and one of them is to rely on authentication providers, trusted entities that can authenticate someone for you. You are probably already familiar with this way of managing authentication as many applications suggest to "Sign in with Microsoft" or "Log in with Google".

In this article, we will discuss how to configure PocketBase to use GitHub as an authentication provider for your Angular app, here's an overview of what we will be building:

📝 If you would like to follow along, you can clone the code of this article using this repository and follow along using the branches, starting with 01-initial-setup.

What is PocketBase

PocketBase is a Backend as a Service (BaaS) like FireBase, SupaBase, Appwrite and many others.

What differentiates it from others however, is that it consists of a single executable file making it really easy to run locally or to self-host, where other solutions often require either connecting to a cloud instance, or setting up several Docker containers.

PocketBase aims to be used as a backend solution, providing authentication, en embedded database, realtime subscriptions and built-in authentication management.

It can also do much more than that, and you can have a look at their documentation or online demo to try for yourself.

There is also a pretty good video of Fireship on the subject:

Integrating GitHub OAuth with PocketBase

Before actually consuming it, we should first setup our backend in our Angular project.

🌲 Start here with the branch: 01-initial-setup, the final result will be in 02-pocketbase-installation.

Setting Up PocketBase

Since PocketBase is a single executable, we can download it either from the direct link in the docs or on the GitHub releases page.

📝 As of the time I'm writting this article, the current version of PocketBase is 0.22.19

Once downloaded, open the archive and copy pocketbase.exe into the Angular project. I placed mine at pocketbase/pocketbase.exe:

Once in your project, simply run it with the command pocketbase serve, you should observe the following output:

Some files are also automatically created by PocketBase on startup, consisting of its initial configuration.

You can now navigate to http://127.0.0.1:8090/_/ where you will be asked for the credentials of the administrator account of your PocketBase instance. This user will be allowed to update the internals of your backend, create new tables, routes, and much more:

Upon creation you should be redirected to the administration dashboard:

We're all set!

Registering GitHub as an OAuth Provider

To configure GitHub as an OAuth provider, we should first get credentials from the platform by registering our applications in GitHub.

In order to create a new OAuth application, navigate to https://github.com/settings/apps and click on OAuth Apps. You can then click on the top right button labeled New OAuth App.

You will be asked for some informations that you can fill as you see fit, except for the Authorization callback URL which is handled by PocketBase and should redirect to /api/oauth2-redirect of your instance. In our case, the desired URL is http://localhost:8090/api/oauth2-redirect:

When created, copy the Client ID and generate a new Client secrets to copy its value as well.

Back to the PocketBase administration panel, in the sidebar, click on the wrench icon to navigate to http://127.0.0.1:8090/_/#/settings. From there, click on the Auth providers item in the Authentication section. Amongst the listed providers, you should see GitHub:

If you click on the cog, a menu opens and you can specify the values with the OAuth application we just created:

Once filled, you can click on Save changes and noticed that GitHub now appears as enabled:

And just like that, we configured our PocketBase backend to use GitHub as an OAuth provider!

Consuming PocketBase from our Angular Application

Now that we have a running backend with OAuth2 configured, we can interract with it like we would with any other backend.

🌲 Start here with the branch 02-pocketbase-installation, the final result will be in 03-consuming-pocketbase.

Initializing the Client

The easiest way to get started with PocketBase in a JS project is to use their JS Client-side SDK available on GitHub.

Let's get started by installing the required dependency:

pnpm install pocketbase

Once done, we can instantiate a new client using the URL PocketBase is running at:

import PocketBase from 'pocketbase';
const pb = new PocketBase('http://127.0.0.1:8090');

However, we can also take advantage of Angular's powerful dependency injection system and instead wrap it into an injection token:

// 📂 src/app/pocketbase.provider.ts
export const PocketBaseClient = new InjectionToken<PocketBase>(
  'PocketBase client',
);

We can then expose a method that will manage the PocketBase client's creation for us:

// 📂 src/app/pocketbase.provider.ts
export const providePocketBase = (baseUrl: string): EnvironmentProviders =>
  makeEnvironmentProviders([
    {
      provide: PocketBaseClient,
      // 👇 You could also inject `environment` here instead
      useFactory: () => new PocketBase(baseUrl),
    },
  ]);

We now have to register our provider in main.ts:

// 📂 src/main.ts
bootstrapApplication(AppComponent, {
  providers: [
    provideExperimentalZonelessChangeDetection(),
+   providePocketBase('http://localhost:8090'),
  ],
}).catch((err) => console.error(err));

And we can now inject the client into the AuthenticationService:

// 📂 src/app/authentication.service.ts

@Injectable({ providedIn: 'root' })
export class AuthenticationService {
+ readonly #pocketBase = inject(PocketBaseClient);
  // ...
}

Implementing Authentication with PocketBase

Since PocketBase is managing authentication, we don't have to be orchestrating the sign in process, instead we only need to declare what logic we would like to run if the authentication status changes.

In PocketBase, the authStore is in charge of managing authentication and its events.

In our case, we would like to update the user's name whenever he signs in by registering a callback:

// 📂 src/app/authentication.service.ts
@Injectable({ providedIn: 'root' })
export class AuthenticationService {
  // ...

+ constructor() {
+   this.#pocketBase.authStore.onChange((_token, user) => {
+     this.#userName.set(user?.['username'] ?? null);
+   });
+ }

  // ...
}

Signing Methods

We now have configured pretty much everything, except the actual sign in and sign out methods.

Signing out is the most straightforward method to write since it just consists of clearing PocketBase's authStore:

// 📂 src/app/authentication.service.ts
@Injectable({ providedIn: 'root' })
export class AuthenticationService {
  // ...

  signOut(): void {
-   this.#userName.set(null);
+   this.#pocketBase.authStore.clear();
  }
}

Signing in also doesn't require much to write, since PocketBase and its SDK will be handling all the complexity. All we need to do is to trigger the authentication challenge for the users collection, using github as a provider.

Since this is a Promise, we can also log an eventual error that might occurred:

// 📂 src/app/authentication.service.ts
@Injectable({ providedIn: 'root' })
export class AuthenticationService {
  // ...

  signInWithGithub(): void {
-   this.#userName.set('pBouillon');
+   this.#pocketBase
+     .collection('users')
+     .authWithOAuth2({ provider: 'github' })
+     .catch((error) => console.log(error.originalError));
  }
}

If you now run the demo again, you should be able to sign in using GitHub:

Congrats! You've just achieved authentication in your Angular app using GitHub as an OAuth provider 🎉

📝 You can still go further by implementing a mechanism to detect if the user is already signed in when the page opens using by storing a cookie with its details and read it on initialization. You can look into the authServer#exportToCookie method as a starting point.

Wrapping up

With the last piece of codes added and the demo fully functional, we successfully have setup a backend using PocketBase, and configured GitHub to act as our authentication provider.

Should you add any other provider (Microsoft, Google, Facebook or even Discord) the process is globally the same, except for some specificities some might require.

However PocketBase is much more than that and I highly encourage you to check out all the features it has. Amongst many other things, you can manage your data, create table view, see logs history, create custom API routes, create data migrations, etc.

In my experience, PocketBase make it really easy to work on side project where you quickly want to get started without having to deal with the complexity of writing your own backend from scratch.

Moreover, with the options to self-host it, or the free alternatives such as PocketHost, going to production is really simple.

You can still check-out the docs to learn more about it, or browse this article's repository:

pBouillon / DEV.GitHubAuthWithPocketBase

Demo code for the "Using GitHub as an Authentication Provider in Your Angular App with PocketBase" article on DEV

Using GitHub as an Authentication Provider in Your Angular App with PocketBase

Demo code for the "Using GitHub as an Authentication Provider in Your Angular App with PocketBase" article on DEV

View on GitHub

I hope your learned something useful!

Pierre BouillonFollow

Software Engineer | Full Stack Developer | Coffee Lover

Photo by Nicole Geri on Unsplash

Synchronized Web Storage with Signals

Pierre Bouillon — Tue, 18 Jun 2024 06:15:06 +0000

Working with local storage in JavaScript is both very easy and sometimes frustrating. While being really straightforward, the Web Storage API lack of one critical feature that is more deeply rooted than ever in modern Angular applications: reactivity.

Fortunately, with the latest release, many tools are at our disposal to create a handy utility function, creating a reactive signal from a value stored locally!

In this article, we will see how to abstract the web storage in a dedicated Angular service, and how to take advantage of it to synchronize its value using signals to achieve the following outcome:

All the code of this article is hosted on GitHub if you would like to check it out!

Abstracting the Web Storage

Before actually building the signal's logic, we will first have to abstract the native Web Storage API.

This will allow us to chose what we are manipulating, how, as well as giving us more flexibility on what kind of storage we would use (not to mention an easier way of mocking it for testing purposes).

Dynamic Storage Type

The first thing we would like to do is to define an injection token for the kind of storage to use:

// 📂 storage.service.ts
export const STORAGE = new InjectionToken<Storage>(
  'Web Storage Injection Token'
);

From now we can provide the desired Storage (localStorage, sessionStorage, etc.) to our Angular application:

// 📂 main.ts
bootstrapApplication(AppComponent, {
  providers: [{ provide: STORAGE, useValue: localStorage }],
}).catch((err) => console.error(err));

Creating the `StorageService`

Since the Storage is now known in the injection container, we can consume it in an Angular service to manage the read and write operation, while also enforcing type safety (within a certain limit):

// 📂 storage.service.ts
@Injectable({ providedIn: 'root' })
export class StorageService {
  readonly #storage = inject(STORAGE);

  getItem<T>(key: string): T | null {
    const raw = this.#storage.getItem(key);
    return raw === null
      ? null
      : JSON.parse(raw) as T;
  }

  setItem<T>(key: string, value: T | null): void {
    const stringified = JSON.stringify(value);
    this.#storage.setItem(key, stringified);
  }
}

Now that the basic building blocks are ready, we can work on the actual signals!

Leveraging Signals

Signals are really easy to use but also really easy to wrap and extend.

Before diving into read and write synchronization, let's first create the utility function:

// 📂 from-storage.function.ts
export const fromStorage = <TValue>(storageKey: string): WritableSignal<TValue | null> => {
  const storage = inject(StorageService);

  const initialValue = storage.getItem<TValue>(storageKey);
  return signal<TValue | null>(initialValue);
}

For now, this only create a signal from a value (or its absence) in the injected Storage.

Upon calling fromStorage, we can now track a specific key and its (typed) value:

// 📂 app.component.ts
type ColorScheme = 'light' | 'dark';

@Component({ /*...*/ })
export class AppComponent {
  readonly preferredTheme = fromStorage<ColorScheme>('preferred-theme');
}

This looks promising, but we still lack of that desired reactivity in two major cases:

When updating the value, we should also update the stored value
When any update is made to the storage for this key, we should also update the value

Let's address those!

Syncing Writes

Updating the value in the Storage whenever we are updating the signal's value is the easiest part.

With effect we can simply call StorageService.setItem to write the updated value since it will be invoked when the value actually changes (or matches the defined equality):

// 📂 from-storage.function.ts
export const fromStorage = <TValue>(storageKey: string): WritableSignal<TValue | null> => {
  // ...
  const fromStorageSignal = signal<TValue | null>(initialValue);

  const writeToStorageOnUpdateEffect = effect(() => {
    const updated = fromStorageSignal();
    untracked(() => storage.setItem(storageKey, updated));
  });

  return fromStorageSignal;
}

That's one problem solved!

Syncinc Reads: Taking Advantage of the Web Storage API

The main issue here is that the update can occur in two cases that we can't always control:

Another piece of code updates the stored value
Another tab updates the same value

We will need a way of detecting that something changed, possibly outside of our app.

Using `setTimeout`

A first solution we might think of would be using setTimeout.

While possible, it would either introduce a latency in the update with a long period, or a heavy polling mechanism if we chose a smaller one (not to mention that watching several values would then introduce a lot of those polling systems).

Such a system could be implemented as:

// 📂 from-storage.function.ts
export const fromStorage = <TValue>(storageKey: string): WritableSignal<TValue | null> => {
  // ...

  const updateSignalOnSignalWriteEffect = effect((onCleanup) => {
    const intervalId = setInterval(() => {
      const newValue = storage.getItem<TValue>(key);
      const currentValue = fromStorageSignal();

      const hasValueChanged = newValue !== currentValue;
      if (hasValueChanged) fromStorageSignal.set(newValue);
    }, 150)

    onCleanup(() => clearInterval(intervalId));
  });

  return fromStorageSignal;
}

🚨 In applications that are still using zonejs for change detection, you should run this outside zone to avoid triggering unecessary change detection:
inject(NgZone).runOutsideAngular(() =>  /*...*/ );

Using the storage event

What if instead of a polling mechanism we could react to a change? Fortunately, the Web Storage API defines a Storage Event that can be listened to using storage.onstorage or the storage event, which tells us that something in the Storage has been modified, what key was targeted and some more information.

Sounds great, let's use that instead:

// 📂 from-storage.function.ts
export const fromStorage = <TValue>(storageKey: string): WritableSignal<TValue | null> => {
  // ...

  const storageEventListener = (event: StorageEvent) => {
    const isWatchedValueTargeted = event.key === storageKey;
    if (!isWatchedValueTargeted) {
      return;
    }

    const currentValue = fromStorageSignal();
    const newValue = storage.getItem<TValue>(storageKey);

    const hasValueChanged = newValue !== currentValue;
    if (hasValueChanged) {
      fromStorageSignal.set(newValue);
    };
  }

  window.addEventListener('storage', storageEventListener);

  // 👇 Don't forget to clean up after yourself
  inject(DestroyRef).onDestroy(() => {
    window.removeEventListener('storage', storageEventListener);
  });

  return fromStorageSignal;
}

Great! Let's try it:

// 📂 app.component.ts
@Component({ /*...*/ })
export class AppComponent {
  readonly preferredTheme1 = fromStorage<ColorScheme>('preferred-theme');
  togglePreferredTheme(): void {
    this.preferredTheme1.update(current => current === 'light' ? 'dark' : 'light');
  }

  readonly preferredTheme2 = fromStorage<ColorScheme>('preferred-theme');
  setLightTheme(): void {
    this.preferredTheme2.set('light');
  }
}

Calling setLightTheme does not update preferredTheme1 and togglePreferredTheme has no effect of preferredTheme2! I thought we just solved this problem?

The explanation is actually on the MDN doc page:

Note: This won't work on the same browsing context that is making the changes (...)

It means that updating the value ourselves won't trigger the event in our own tab. We were so close to a reactive value!

Fortunately, the StorageEvent can be crafted and we have our own service to interact with the storage, meaning that we can raise that event ourselves upon write:

// 📂 storage.service.ts
@Injectable({ providedIn: 'root' })
export class StorageService {
  readonly #storage = inject(STORAGE);

  getItem<T>(key: string): T | null { /*...*/ }

  setItem<T>(key: string, value: T | null): void {
    const stringified = JSON.stringify(value);
    this.#storage.setItem(key, stringified);

    // 👇 Notify of the update
    const storageEvent = new StorageEvent('storage', {
      key: key,
      newValue: stringified,
      storageArea: this.#storage,
    });

    window.dispatchEvent(storageEvent);
  }
}

🚨 Be aware that this can duplicate events for the other tabs, hence the need of checking if the value has changed in the event handler to avoid any issue.

If we try again to call togglePreferredTheme or setLightTheme, we can see that both signals are now indeed updated along with the value in the Storage. We did it!

Wrapping up

In this article we abstracted both the Storage and the interaction with the Web Storage API in order to have control of its usage. We then introduced a method to create a signal from a key to watch a value in the Storage, achieving synchronization between signals and the Web Storage:

If you would like to play with the code yourself, check out the code on GitHub!

I hope your learned something useful!

Pierre BouillonFollow

Software Engineer | Full Stack Developer | Coffee Lover

Photo by CHUTTERSNAP on Unsplash

Efficient Patterns for Effects

Pierre Bouillon — Wed, 17 Apr 2024 04:54:06 +0000

Angular's signals have been quite a revolution since they came out, from new state management approach to a brand new way of rethinking reactivity within applications, signals have deeply influenced the framework's ecosystem.

While most of its primitives are stable, effect is still in developer preview as of the time I'm writing this article, and can often lead to errors or warnings.

In this post, we will cover the basics of the usage of effect, some tips and tricks I use, and showcase a way to enhance their behavior.

Effect in a Nutshell

Effect is a function that defines a callback to be called whenever any of the signal it wrapped changes:

const age = signal(26);

effect(() => {
  console.log(`Happy ${age()}th birthday! 🎂`);
});

age.update(age => ++age);
// -> Happy 27th birthday! 🎂

Tips and Tricks

The core of what compose an effect is there, but in the real world, they can prove harder to use and to maintain, leading to unexpected behaviors or bugs.

After heavily using them, the Angular's community found patterns and ways to ease their usage, here are some I found particularly useful.

📝 This is just tips I enjoy using, they don't necessarily come from any sort of official guideline or convention.

Explicit your dependencies

In the previous example, seeing that the effect relies on age is fairly easy to spot since there is only a single line and a single signal.

In a larger codebase, it might be a bit harder, or simply add some unecessary cognitive load.

To both simplify the reading of an effect, and clarify its dependencies, it is common to see the first lines of a signal explicitely unwrapping the values:

effect(() => {
  // 👇 Indicate which signals this effect will work on
  const productId = productId();
  const isLoggedIn = isLoggedIn();

  // Logic based on the unwrapped values
});

Small and Focused Effects

When using them, try to write Small and Focuses Effects (stay SaFE!).

If they grow, effects will be unclear as what their initial goal was, and if you need to consume one more signal in the future, it might have some unwanted side effects.

Keeping the effects concise clarify their scope and make them easier to read:

// ❌
effect(() => {
  const age = age();
  const isLoggedIn = isLoggedIn();
  const selectedProductId = selectedProductId();

  // ...
});

// ✅
effect(() => {
  const isLoggedIn = isLoggedIn();

  // ...
});

effect(() => {
  const age = age();
  const selectedProductId = selectedProductId();

  // ...
});

Name your things

Since effects are "just" callbacks, it can sometimes prove difficult to understand their meaning.

However, we can take advantage of its API to name the EffectRef it returns, and hence explicit its goal.

For example, here is the previous example:

const redirectAnonymousEffect = effect(() => {
  const isLoggedIn = isLoggedIn();

  // ...
});

const ensureLegalAgeEffect = effect(() => {
  const age = age();
  const selectedProductId = selectedProductId();

  // ...
});

📝 Notice that by naming things, you might also notice that an effect tries to englobe too many things and needs to be split in parts.

Untrack what doesn't need to be tracked

Since effects tracks signals called from a reactive context, it can help to go a step further than just declaring the dependencies by plainly untrack the rest of the logic:

const ensureLegalAgeEffect = effect(() => {
  const age = age();
  const selectedProductId = selectedProductId();

  // 👇 Nothing in here can impact the trigger of the effect
  untracked(() => {
    // ...
  });
});

While it's a bit more verbose, it's a convenient way to ensure that the logic will not impact the effect's trigger.

Supercharging effects

Keeping those tips in mind is great, applying them even more, but staying consistant relying only on self discipline can be hard, even more in a team.

However, with a bit of TS magic, GitHub comments and time, we can write a wrapped function for those principles:

Its usage allows you to specify the signals to listen to, and a function to be executed whenever the dependencies changed. Any signal called within it won't mark it as a dependency of the effect:

const loginChangedEffect = effectFromDeps(
  [this.loginStatus],
  ([loginStatus]) => {
    console.log(`[${loginStatus}] There is currently ${this.userCount()} users`)
  });

By providing an additional option object, we can actually go a step further and have finer control on the effect's lifecycle:

This allows us to specify callbacks on effect's creation and cleanup:

const loginChangedEffect = effectFromDepsWithLifecycle(
  [this.loginStatus],
  ([loginStatus]) => {
    console.log(`[${loginStatus}] There is currently ${this.userCount()} users`)
  }, {
    onCreation: () => console.log('Created'),
    onCleanup: () => console.log('Cleaned up'),
  });

That’s all I had to share today, happy coding!

Handling Pagination with StateAdapt

Pierre Bouillon — Thu, 28 Dec 2023 12:00:00 +0000

In a previous article, I covered how to paginate data using NgRx Component Stores

Handling pagination with NgRx component stores

Pierre Bouillon for Playful Programming Angular ・ Feb 28 '23

#tooling #productivity

In today's article, we are going to tackle the same problem but with StateAdapt, a small but growing state management library, focused on composability, evolutivity and declarative programming.

📑 As usual, this article is build as a hands on lab. You can code alongside me by following the notes marked by a '🧪'.

Initial State

The application we will be working on will be a simple todo list, with a bunch of items displayed:

For now the pagination is handled by the component itself, along with the data, but we will be shifting this from the component into a dedicated store.

Configuring StateAdapt

🧪 Checkout the initial-setup tag to get started from here

Before managing our state, we will first need to configure the state management library.

For that, we will install the required packages:

npm i -D @state-adapt/core @state-adapt/rxjs @state-adapt/angular

Once installed, we can use the default store provider:

// 📁 src/main.ts
bootstrapApplication(AppComponent, {
  providers: [defaultStoreProvider],  // 👈 Provided here
}).catch((err) => console.error(err));

We're all set and ready for to create our adapters!

Creating the adapters

🧪 Checkout the with-state-adapt tag to get started from here

StateAdapt has the unique particularity of allowing us to define how to manage a specific piece of data through dedicated adapters.

In our case, we will be managing todo items based on the current pagination.

Instead of managing everything at once, we will break it down by managing each piece of part of our state.

Adapting the Pagination

To get started, we will start by creating the adapter of the pagination details.

In a new file, we can extract the interface:

// 📁 src/app/pagination.ts
export interface Pagination {
  offset: number;
  pageSize: number;
}

From there, we will be able to define the two actions we currently have: going to the next and the previous page:

// 📁 src/app/pagination.ts

// ...

export const paginationAdapter = createAdapter<Pagination>()({
  nextPage: ({ offset, pageSize }) => ({ pageSize, offset: offset + 1 }),
  previousPage: ({ offset, pageSize }) => ({ pageSize, offset: offset - 1 }),
  selectors: {
    pagination: (state) => state,
  },
});

📑 You might also want to change the page size and more in a real application, I'm just sticking to the example here!

Adapting the Todo Item

As we just did for the pagination, we will now be creating an adapter for our TodoItem.

This time the interface already exists, and we will just append the adapter.

For the example simplicity's sake, our state won't contain any logic, just a selector for the item itself:

// 📁 src/app/todo-item.ts

// ...

export const todoItemAdapter = createAdapter<TodoItem>()({
  selectors: {
    todoItem: (state) => state,
  },
});

We're all set for adapting our TodoItem but unfortunately we won't be manipulating a single todo item but several onces.

We could create an adapter for TodoItem[] but instead StateAdapt offers an efficient and concise way of reusing existing logic for multiple entities with createEntityAdapter.

With our previously defined adapter, we can now adapt a list of todo items fairly simply:

// 📁 src/app/todo-item.ts

// ...

export const todoItemsAdapter = createEntityAdapter<TodoItem>()(todoItemAdapter);

Thanks to that, our adapters for the TodoItem are done, in just a few lines of code. It's time to work on the paginated items now!

Adapting the Paginated Items

Back in our TodoItemService, we can define our state as a pagination details and a collection of todo items.

However, since the listed TodoItem[] are considered as entities, we will tag them as such. StateAdapt provides a type named EntityState that has two generic parameters: the entity itself and the name of the key used for its identity. In our case, managing several TodoItems drills down to managing an EntityState<TodoItem, 'id'>:

// 📁 src/app/todo-item.service.ts

// ...

export interface TodoItemsState {
  pagination: Pagination;
  todoItems: EntityState<TodoItem, 'id'>;
}

@Injectable({ providedIn: 'root' })
export class TodoItemService {
  // ...
}

While this might look strange at first, it allows us to reuse or previous adapters to adapt the TodoItemsState using joinAdapters, with little to no code to write:

// 📁 src/app/todo-item.service.ts

// ...

export const todoItemsStateAdapter = joinAdapters<TodoItemsState>()({
  pagination: paginationAdapter,
  todoItems: todoItemsAdapter,
})();

@Injectable({ providedIn: 'root' })
export class TodoItemService {
  // ...
}

Creating Our Store

🧪 Checkout the with-adapters tag to get started from here

Now that all managed entities and state can be adapted, we still have to use the adapters to create the store.

First, we need a starting point, an initial state:

// 📁 src/app/todo-item.service.ts

// ...

const initialState: Readonly<TodoItemsState> = {
  pagination: { offset: 0, pageSize: 5 },
  todoItems: createEntityState<TodoItem, 'id'>(),
};

@Injectable({ providedIn: 'root' })
export class TodoItemService {
  // ...
}

📑 Since todoItems is an EntityState<TodoItem, 'id'>, we use the provided createEntityState method for the initial value instead of an empty array.

With this initial state, creating our store doesn't require much more code:

// 📁 src/app/todo-item.service.ts

// ...

@Injectable({ providedIn: 'root' })
export class TodoItemService {
  readonly #store = adapt(initialState, {
    adapter: todoItemsStateAdapter,
  });

  // ...
}

Defining the Actions

With our state initialized and our store set up, we can now wire the actions allowing us to navigate between pages.

In StateAdapt, an action is triggered by nexting a Source that acts as a medium of action emission.

In our case, we will need two source: one to navigate to the next page, and one to navigate to the previous one:

// 📁 src/app/todo-item.service.ts

// ...

@Injectable({ providedIn: 'root' })
export class TodoItemService {
  readonly nextPage$ = new Source('[Todo Items State] Next Page');
  readonly previousPage$ = new Source('[Todo Items State] Previous Page');

  readonly #store = adapt(initialState, {
    adapter: todoItemsStateAdapter,
    sources: {
      previousPaginationPage: this.previousPage$,
      nextPaginationPage: this.nextPage$,
    },
  });

  // ...
}

💡 Notice that StateAdapt auto-generated the sources based on the joined paginationAdapter!

While this will update the pagination, the TodoItems won't be updated, and we will need to perform a side effect for that.

In essence, we would like to retrieve and set the TodoItems every time the pagination changes.

To do so, we will first define a way to set all TodoItems, the same way we did for the pagination:

// 📁 src/app/todo-item.service.ts

// ...

@Injectable({ providedIn: 'root' })
export class TodoItemService {
  readonly nextPage$ = new Source('[Todo Items State] Next Page');
  readonly previousPage$ = new Source('[Todo Items State] Previous Page');
  readonly #setTodoItems$ = new Source<TodoItem[]>(
    '[Todo Items State] Set Todo Items'
  );

  readonly #store = adapt(initialState, {
    adapter: todoItemsStateAdapter,
    sources: {
      previousPaginationPage: this.previousPage$,
      nextPaginationPage: this.nextPage$,
      setTodoItemsAll: this.#setTodoItems$,  👈 New source
    },
  });

  // ...
}

Performing a side effect is just as much as any side effect defined using RxJs: by subscribing to the appropriate observable:

// 📁 src/app/todo-item.service.ts

// ...

@Injectable({ providedIn: 'root' })
export class TodoItemService {
  readonly nextPage$ = new Source<void>('[Todo Items State] Next Page');
  readonly previousPage$ = new Source<void>('[Todo Items State] Previous Page');

  // 👇 Since this side effect is internal, the visibility is private
  readonly #setTodoItems$ = new Source<TodoItem[]>('[Todo Items State] Set Todo Items');

  readonly #store = adapt(initialState, {
    // ...
  });

  constructor() {
    this.#store.pagination$
      .pipe(
        takeUntilDestroyed(),
        switchMap((pagination) => this.getTodoItems(pagination))
      )
      .subscribe((todoItems) => this.#setTodoItems$.next(todoItems));
  }

  // ...
}

We are almost done! Our state is now a functional management solution, but we can't read it for now, let's add the selectors.

Reading Our State

A popular way of reading state is by defining view models, or "vm".

For our store, we can define the view model as a signal of the two things we are interested in: the pagination and the todo items:

// 📁 src/app/todo-item.service.ts

// ...

@Injectable({ providedIn: 'root' })
export class TodoItemService {
  // ...

  readonly vm = toSignal(
    this.#store.state$.pipe(
      map((state) => ({
        pagination: state.pagination,
        todoItems: Object.values(state.todoItems.entities),
      }))
    ),
    { requireSync: true }
  );

  constructor() {
    // ...
  }

  // ...
}

📑 You can also use combineLatest to create your view model:

readonly vm = toSignal(
  combineLatest({
    pagination: this.#store.pagination$,
    todoItems: this.#store.todoItemsAll$,
  }),
  { requireSync: true }
);

Our state is now initialized and readable, it's time to ditch the logic in the component and rely on it instead!

Consuming the State

🧪 Checkout the with-store tag to get started from here

Back in our AppComponent, we can now remove the custom logic from the code behind and rely on the service instead:

// 📁 src/app/app.component.ts

@Component({
  // ...
})
export class AppComponent {
  readonly #todoItemService = inject(TodoItemService);

  readonly vm = this.#todoItemService.vm;

  onPreviousPage(): void {
    this.#todoItemService.previousPage$.next();
  }

  onNextPage(): void {
    this.#todoItemService.nextPage$.next();
  }
}

Similarly, we can now consume the vm from the template:

// 📁 src/app/app.component.ts

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [TodoItemComponent],
  template: `
    @for (todoItem of vm().todoItems; track todoItem.id) {
    <app-todo-item [todoItem]="todoItem" />
    }

    <div class="grid">
      <button
        type="button"
        (click)="onPreviousPage()"
        [disabled]="vm().pagination.offset === 0"
      >
        ←
      </button>
      <button
        type="button"
        (click)="onNextPage()"
        [disabled]="vm().pagination.offset === 2"
      >
        →
      </button>
    </div>
  `,
})
export class AppComponent {
  // ...
}

🧪 You could still go further, what about moving the condition for the [disabled] attributes to a selector?

And we are done! However, our pagination is now handled by StateAdapt that will also give us access to additional features like Redux DevTools out of the box:

Takeaways

In this article, we saw how we could handle pagination using StateAdapt as our state management solution, by taking advantage of its API focused on composition.

We incrementally adapted our entities to create the component state, and initialized our store from that point.

Finally, we consumed it from our component in order to remove the logic that it defined.

If you would like to see the resulting code, you can browse the article's repository:

pBouillon / DEV.HandlingPaginationWithStateAdapt

Demo code for the "Handling pagination with StateAdapt" article on DEV

Handling pagination with StateAdapt

Demo code for the "Handling pagination with StateAdapt" article on DEV

View on GitHub

I hope that you learn something useful there!

Pierre BouillonFollow

Software Engineer | Full Stack Developer | Coffee Lover

Photo by Sincerely Media on Unsplash

Forem: Pierre Bouillon

Managing database schema changes in .NET From theory to FluentMigrator

Why Bother With Migrations?

An Overview of The Existing Tools

Entity Framework Core

RoundhousE, Evolve and Other SQL-First Tools

FluentMigrator

Using FluentMigrator

Creating Our First Migration

Configuring FluentMigrator

Automatically Applying Migrations on Startup

Adding Features and Breaking the Schema

Wrapping Up

Deserializing Polymorphic JSON in .NET Without Losing Type Safety

Our Custom Map of French Hidden Gems

The God Object

Polymorphic Deserialization

Shaping Our Domain

Introducing A Converter

Wrapping Up

A Comprehensive Guide to State Management with Vanilla Angular

Why Managing State At All?

A brief introduction to Redux

Managing State in an Angular Application

Implementing State Management for a Shopping Cart

Case Study: Le Shop

Analyzing the Current Structure

Creating the Store

Defining the State

Adding Events

Creating Reducers

Introducing Effects

Exposing Selectors

Using The Store

Takeaways

My Attempt at Neobrutalism with Svelte: Redesigning my Website

What is Neobrutalism

My Attempt at it

Main Section

Experiences

Articles

Projects

Conclusion

Setup PocketBase For Your Integration Tests with TestContainers and xUnit

A short Introduction to Integration Testing

Integration Testing in PocketBase.Net

Creating a Testing PocketBase Instance

Introducing TestContainers

Creating Our PocketBase Container

Using the Container with xUnit

Closing thoughts

Our First Issue: Enhancing Queries With Sorting

Table of Contents

The issue

Development Process

Defining Our Goals

Implementation

Setup

Implementing WithSorting

Writing the Acceptance Test

Implementing the Sorting

Running Our Tests

Creating the Sorting String Builder

Finishing Touches

Closing Thoughts

Launching and Building PocketBase.Net in the Open

Presenting PocketBase.Net

What is PocketBase

Working with PocketBase

Introducing PocketBase.Net

Current State

What's next

Building with You

My First Book: Modern Web Development with Angular

Using GitHub as an Authentication Provider in Your Angular App with PocketBase

What is PocketBase

Integrating GitHub OAuth with PocketBase

Setting Up PocketBase

Registering GitHub as an OAuth Provider

Consuming PocketBase from our Angular Application

Creating the `StorageService`

Using `setTimeout`