Forem: Michael De Abreu

5-Operators and Composition in Our System - Building a Reactive System in TypeScript

Michael De Abreu — Thu, 03 Apr 2025 11:47:35 +0000

To recap, we have built and optimized a reactive system that can store variables and react to updates and event emissions, update other states, and perform side-effect calls. The journey has been incredible, and I hope this has helped you to understand more about how reactive systems work under the hood, but all things must come to an end. This will be the final post of the series, where we will explore how to create operators for our system. This will also be a long post since everything is related to operators, and I didn't want to break the flow.

Defining an operator

If you are familiar with other reactive libraries, you have probably seen these functions that allow you to transform values in a data stream. These functions are called operators. An operator should be a function that takes a transformation function and returns another function that gets the internal stream, applies the transformation, and returns a new stream.

export type OperatorFn<T, R = T> = (source: Subscribable<T>) => Event<R>;

We could also apply the transformation directly without involving the stream system, but then the operators would be synchronous, and that wouldn't be much fun, would it? By keeping the stream, we can use it to create async operators easily; more on that later.

Coding our first operator

If I mention transforming a data stream, I bet you are thinking about the map method of an array, and you'd be right. The first operator we will create is a map operator. Let's start by defining the test:

describe("map", () => {
  it("should apply map correctly", () => {
    const source = event<number>();

    const mapped1 = map((x: number) => x * 2)(source);
    const mapped2 = map((x: number) => `${x}`)(mapped1);

    const result = mock();

    mapped2.subscribe(result);

    source(2);

    expect(result).toHaveBeenCalledWith("4");
  });
});

We want the operator to be composable. This first callback will create the signature of the OperatorFn that we defined, something we can reuse to call the operator and create a new stream.

Let's start by creating the map function in its own file:

export function map<T, R>(fn: (value: T) => R): OperatorFn<T, R> {
}

Since we want to return an operator function, we need something like this:

return (source) => {
  const mappedEvent = event<R>();
  return mappedEvent;
};

We return a function that creates a new event and returns it, but it's not transforming the output yet. To do that, we need to use the fn callback we're passing to the operator.

source.subscribe((value) => mappedEvent(fn(value)));

With this, we subscribe to the input source of the operator and emit transformed values into the new event. Finally, this is what our first operator looks like:

export function map<T, R>(fn: (value: T) => R): OperatorFn<T, R> {
  return (source) => {
    const mappedEvent = event<R>();
    source.subscribe((value) => mappedEvent(fn(value)));
    return mappedEvent;
  };
}

This operator emits a new value each time the input is updated. However, another useful method the Array prototype has is filter, which allows us to get a new array with only the values we want, based on a predicate function.

The filter operator

To create our second operator, we'll start again by writing the tests first:

describe("filter", () => {
  it("should apply filter correctly", () => {
    const source = event<number>();
    const filtered = filter((x) => x > 5)(source);

    const result = mock();

    filtered.subscribe(result);

    source(3);
    expect(result).not.toHaveBeenCalled();
    source(7);
    expect(result).toHaveBeenCalledWith(7);
  });
});

This operator is very similar to map, so I'll skip the step-by-step explanation and show the complete implementation instead.

export function filter<T>(predicate: (value: T) => boolean): OperatorFn<T> {
  return (source) => {
    const filteredEvent = event<T>();
    source.subscribe((value) => {
      if (predicate(value)) {
        filteredEvent(value);
      }
    });
    return filteredEvent;
  };
}

The only difference between the operators lies in their behavior. Instead of transforming a value, this operator evaluates whether the value should be emitted.

With this, we now have two operators, map and filter, and the result of each can be used as the source for another. We can leverage that to create a way to chain operators more naturally.

Composing with `pipe`

Composition is a fundamental part of any reactive system, and operator chaining is the most natural way to express transformations and logic over time. Instead of creating one-off streams and wiring them manually, we can define a clear and readable sequence of operations, just like we do with array methods. I think it would be better if we could chain them naturally, like this:

const result = source.pipe(
  map((x) => x * 2),
  filter((x) => x > 5)
);

This might seem like magic, but all we really need to do is apply the operators one after another, like we've been doing manually. We'll just take advantage of the fact that the output of one stream is the input of the next. It's not magic, but it's going to look a lot cleaner.

function pipe<R>(...operators: OperatorFn<any, any>[]): Event<R> {
  const pipeEvent = event<unknown>();
  subscribe(pipeEvent);
  const resultEvent = operators.reduce(
    (acc, op) => op(acc),
    pipeEvent,
  ) as Event<R>;
  return resultEvent;
}

Thanks to the composable API we’ve built, we can chain all the operators into a resulting event simply by creating a new event that subscribes to the source and using it as the initial value in the reducer. That result is what we return from the pipe function.

To integrate this new method in each creator, we just need to add it. By default, it will always return an event, but you could tweak it per creator to make it return the same type. I'll leave that part up to you, and instead, I'll show how you can integrate it into event; similarly, you can add it to other creators.

export function event<T = void>(): Event<T> {
  // Same code we had; we only need to update the return.
  return Object.assign(emit, { subscribe, toState, pipe }) as Event<T>;
}

With that, any state, event, or computed we create will have a pipe method that we can use to chain our operators. We've got two basic operators, but let’s build a few more to show what this system is capable of.

Other operators

Debounce

This operator won’t emit a new value until a specified amount of time has passed.

export function debounce<T>(delay: number): OperatorFn<T> {
  return (source) => {
    const debouncedEvent = event<T>();
    let timeoutId: ReturnType<typeof setTimeout> | undefined;

    source.subscribe((value) => {
      if (timeoutId != null) {
        clearTimeout(timeoutId);
      }

      timeoutId = setTimeout(() => {
        debouncedEvent(value);
        timeoutId = void 0;
      }, delay);
    });

    return debouncedEvent;
  };
}

Merge

This operator merges two sources into a single stream:

export function merge<S, O>(other: Subscribable<O>): OperatorFn<S, S | O> {
  return (source) => {
    const mergedEvent = event<S | O>();
    source.subscribe(mergedEvent);
    other.subscribe(mergedEvent);
    return mergedEvent;
  };
}

MapAsync

This one is my personal favorite. It allows you to map your source into a promise and receive its result asynchronously.

export function mapAsync<T, R, E = unknown>(
  promiseFn: (value: T) => Promise<R>,
): OperatorFn<T, { data?: T; loading?: boolean; error?: E; }> {
  return (source) => {
    const out = event<{ data?: T; loading?: boolean; error?: E; }>();
    let currentFetchId = 0;
    source.subscribe(async (value) => {
      currentFetchId++;
      const fetchId = currentFetchId;
      out({ loading: true });
      try {
        const result = await promiseFn(value);
        if (fetchId === currentFetchId) {
          out({ data: result });
        }
      } catch (error: any) {
        if (fetchId === currentFetchId) {
          out({ error });
        }
      }
    });
    return out;
  };
}

So simple, yet so useful, and incredibly powerful.

One more thing...

If you’ve been following along, you’ve probably noticed TypeScript complaining about the pipe types. We did not define any types for it, so of course, it will complain. However, typing a pipe method is complex because it requires a level of recursion that can even push TS to its limits. This is the most complex part of this series, and it's not even about code but about the shape of the types themselves. What I did is similar to what other libraries like rxjs have done: overloads. A lot of overloads.

PipeFn types

export interface PipeFn<T, S extends Pipeable<any>> {
  (): Event<R>;
  <A>(op1: OperatorFn<NonNullable<T>, A>): Event<R>;
  <A, B>(op1: OperatorFn<NonNullable<T>, A>, op2: OperatorFn<A, B>): Event<R>;
  <A, B, C>(
    op1: OperatorFn<NonNullable<T>, A>,
    op2: OperatorFn<A, B>,
    op3: OperatorFn<B, C>,
  ): Event<R>;
  <A, B, C, D>(
    op1: OperatorFn<NonNullable<T>, A>,
    op2: OperatorFn<A, B>,
    op3: OperatorFn<B, C>,
    op4: OperatorFn<C, D>,
  ): Event<R>;
  <A, B, C, D, E>(
    op1: OperatorFn<NonNullable<T>, A>,
    op2: OperatorFn<A, B>,
    op3: OperatorFn<B, C>,
    op4: OperatorFn<C, D>,
    op5: OperatorFn<D, E>,
  ): Event<R>;
  <A, B, C, D, E, F>(
    op1: OperatorFn<NonNullable<T>, A>,
    op2: OperatorFn<A, B>,
    op3: OperatorFn<B, C>,
    op4: OperatorFn<C, D>,
    op5: OperatorFn<D, E>,
    op6: OperatorFn<E, F>,
  ): Event<R>;
  <A, B, C, D, E, F, G>(
    op1: OperatorFn<NonNullable<T>, A>,
    op2: OperatorFn<A, B>,
    op3: OperatorFn<B, C>,
    op4: OperatorFn<C, D>,
    op5: OperatorFn<D, E>,
    op6: OperatorFn<E, F>,
    op7: OperatorFn<F, G>,
  ): Event<R>;
  <A, B, C, D, E, F, G, H>(
    op1: OperatorFn<NonNullable<T>, A>,
    op2: OperatorFn<A, B>,
    op3: OperatorFn<B, C>,
    op4: OperatorFn<C, D>,
    op5: OperatorFn<D, E>,
    op6: OperatorFn<E, F>,
    op7: OperatorFn<F, G>,
    op8: OperatorFn<G, H>,
  ): Event<R>;
  <A, B, C, D, E, F, G, H, I>(
    op1: OperatorFn<NonNullable<T>, A>,
    op2: OperatorFn<A, B>,
    op3: OperatorFn<B, C>,
    op4: OperatorFn<C, D>,
    op5: OperatorFn<D, E>,
    op6: OperatorFn<E, F>,
    op7: OperatorFn<F, G>,
    op8: OperatorFn<G, H>,
    op9: OperatorFn<H, I>,
  ): Event<R>;
  <A, B, C, D, E, F, G, H, I, J>(
    op1: OperatorFn<NonNullable<T>, A>,
    op2: OperatorFn<A, B>,
    op3: OperatorFn<B, C>,
    op4: OperatorFn<C, D>,
    op5: OperatorFn<D, E>,
    op6: OperatorFn<E, F>,
    op7: OperatorFn<F, G>,
    op8: OperatorFn<G, H>,
    op9: OperatorFn<H, I>,
    op10: OperatorFn<I, J>,
  ): Event<R>;
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  <R>(...ops: OperatorFn<any, any>[]): Event<R>;
}

export interface Pipeable<T> {
  pipe: PipeFn<T, this>;
}

That's all, folks!

And with that, we've reached the end of the series. We started with something as simple as a counter, and we ended up building a complete reactive system, with state, events, operators, async transformations and functional composition.

There's still plenty we could explore to continue the journey, including more advanced topics like batch updates, dev tools, dependency graph, performance optimizations, and integrations with other libraries. But that would go far beyond the scope and simplicity of what we've built so far.

Thank you so much for joining me. I hope you’ve enjoyed the process as much as I did. Now that you know how this works, you might even come up with better ideas than mine, and that would be awesome. I can only hope you'll share them. Until next time.

4-Optimizing and Refactoring the Code - Building a Reactive System in TypeScript

Michael De Abreu — Tue, 11 Mar 2025 11:00:00 +0000

So far, we've built a solid foundation for our reactive system. We started by defining a way to manage the state and respond to events. Then, we added computed values, enhancing them with automatic dependency tracking and removing the need to manually list dependencies. This has allowed us to write more declarative and efficient code.

However, as our implementation has grown, we've begun to notice some repeating patterns across different parts of the system. Functions like state, computed, and event all share similar logic for handling subscriptions and emitting events. This duplication makes the code harder to maintain and increases the risk of inconsistencies.

In this post, we'll focus on refactoring our implementation to consolidate shared logic. Our goal is to extract reusable utilities that improve modularity, readability, and extensibility. This refactoring will also introduce TypeScript types in a more structured way, improving the development experience without adding unnecessary complexity.

By the end of this post, our reactive system will be leaner, more efficient, and easier to maintain. Let's dive in!

Improving the development experience

A good development experience is crucial, and TypeScript helps us achieve that. Until now, we've been using TypeScript without paying much attention to types. In this section, we'll refine our type definitions to improve the development experience. If you're unfamiliar with TypeScript, this might seem intimidating, but don't worry, we'll go through it step by step. Since we're also refactoring parts of the code, these types will naturally integrate into it.

Let's create a types.ts file and define the types we've already been using. These type definitions won't change the logic of our implementation, but they will make our system more explicit and easier to work with.

export interface State<T> extends StateGetter<T>, Subscribable<T> {
  on<U>(subscribable: Subscribable<U>, reducer: StateReducer<T, U>): State<T>;
}

export interface ComputedState<T> extends StateGetter<T>, Subscribable<T> {}

export interface Event<T = void> extends EventEmitter<T>, Subscribable<T> {}

export interface Subscribable<T> {
  subscribe(listener: EventEmitter<T>): void;
}

export interface EventEmitter<T> {
  (payload: T): void;
}

export interface StateGetter<T> {
  (): T;
}

export interface StateReducer<T, U> {
  (state: T, payload: U): T;
}

We won't rush to update the code just yet; instead, we'll take this opportunity to refactor and improve our implementation's structure.

Refactoring the listeners

If you review the code from event, state, and computed, you'll notice they share duplicated logic we can abstract and reuse. The most obvious duplication is in how we handle subscriptions, and that's a great starting point. We can see that all functions store listeners in an array, provide a way to dispatch or emit new values to them, and a way to add new listeners. With that in mind, we can start by creating a handlers.ts file. Since this is a refactoring, we don't need to add more tests, but we do need to ensure that all of our current test suite passes.

Before we start, let's create a function inside the handler.ts file:

export function createListenersHandler<T>() {
}

Inside this function, we'll create an array to store the listeners. This is also a good place to apply the TypeScript types we just defined:

const listeners: EventEmitter<T>[] = [];

Then we create a function to add a listener to the array:

function subscribe(listener: EventEmitter<T>) {
  listeners.push(listener);
}

Finally, we define a function that notifies all listeners when an event occurs:

function emit(value: T) {
  listeners.forEach((listener) => {
    listener(value);
  });
}

That's all we need. We return these functions, and we're good to go.

return { subscribe, emit };

Since we now have well-defined types, let's create an interface for the return value:

interface ListenersHandler<T> extends Subscribable<T> {
  emit: EventEmitter<T>;
}

With all that, our createListenersHandler function should look like this:

interface ListenersHandler<T> extends Subscribable<T> {
  emit: EventEmitter<T>;
}

export function createListenersHandler<T>(): ListenersHandler<T> {
  const listeners: EventEmitter<T>[] = [];

  function subscribe(listener: EventEmitter<T>) {
    listeners.push(listener);
  }

  function emit(value: T) {
    listeners.forEach((listener) => {
      listener(value);
    });
  }

  return { subscribe, emit };
}

Now we can use this in our functions to reduce duplicated code. Let's start with the event. Remove the listeners array and its related logic, then call createListenersHandler.

const { emit, subscribe } = createListenersHandler<T>();

Update the return to replace the non-existing dispatcher with the emit from the handler.

return Object.assign(emit, { subscribe });

Now that we have a properEvent<T> type, we can use it as the return type. With all that, we have the new version of the event function.

export function event<T = void>(): Event<T> {
  const { emit, subscribe } = createListenersHandler<T>();

  return Object.assign(emit, { subscribe });
}

Let's update the state function. Again, we first remove the listeners array and its related code, then call createListenersHandler.

const { emit, subscribe } = createListenersHandler<T>();

Since state already had emit and subscribe, replacing the old listener logic with createListenersHandler requires no further changes. Finally, we use State<T> as the return type, and type the parameters of the on function.

export function state<T>(initialValue: T): State<T> {
  let currentState = initialValue;

  const { emit, subscribe } = createListenersHandler<T>();

  const getter = () => {
    subscribeAutoTracker(subscribe);
    return currentState;
  };

  const on = <U>(
    source: Subscribable<U>,
    reducer: StateReducer<T, U>,
  ) => {
    source.subscribe((payload) => {
      currentState = reducer(currentState, payload);
      emit(currentState);
    });
    return Object.assign(getter, { subscribe, on });
  };

  return Object.assign(getter, { subscribe, on });
}

And now we do the same with computed: we remove the listeners, replace the code related to it with the handlers from createListenersHandler, and use ComputedState<T> as the return type. Similar to state, we were already using the same names here, so no further updates are required.

export function computed<R>(transform: () => R): ComputedState<R> {
  let currentValue: R;

  const { emit, subscribe } = createListenersHandler<R>();

  const getter = () => {
    subscribeAutoTracker(subscribe);
    return currentValue;
  };

  const transformAndEmit = () => {
    currentValue = transform();
    emit(currentValue);
  };

  autoTrackCallback(transformAndEmit);

  return Object.assign(getter, { subscribe });
}

If we run our test cases, they should all pass. After all this, we've significantly simplified the event function, and reduced state, computed, and the overall code.

Refactoring the state

We can still see some duplication between state and computed. Both store an internal value, provide a getter function that automatically subscribes, and emit updates when their values change. We can create a function to handle all that, and again, reduce the amount of duplicated code.

Add a createStateHandler function to our handlers.ts file.

export function createStateHandler<T>(initialValue?: T) {
}

Inside it, let's start by creating a currentValue variable and storing the initial state in it.

let currentValue = initialValue as T;

The cast tells TS that initialValue will always be of type T. I'll explain this later. Now, we need a way to update our state. In the computed function, the state is being replaced with the latest result of the transform callback each time. However, in the state function, we are handling a reducer, and because of this, we need to get the latest value of the internal state to pass it to the reducer. In both cases we need to emit the first value, so we are going to first create our listeners handlers.

const { emit, subscribe } = createListenersHandler<T>();

We can create our updater function:

function update(updater: (value: T) => T) {
  currentValue = updater(currentValue);
  emit(currentValue);
}

This function accepts a callback that receives the current value and returns the updated value. We could use that in both the state and computed, but since computed doesn't actually need the current value, we wrap it to avoid the callback.

We also take this approach to simplify the logic. If the stored state were a function, there would be no reliable way, either in TypeScript or at runtime, to distinguish whether the argument passed to update is a new value or an updater function.

function set(value: T) {
  update(() => value);
}

Finally, we use the same function we are using for the getter:

function getter() {
  subscribeAutoTracker(subscribe);
  return currentValue;
}

We return them all:

return { getter, update, set, subscribe };

And create a type for the return:

interface StateHandler<T> extends Subscribable<T> {
  getter: StateGetter<T>;
  update: StateUpdater<T>;
  set: StateSetter<T>;
}

With all this, our final implementation looks like this:


interface StateHandler<T> extends Subscribable<T> {
  getter: StateGetter<T>;
  update: StateUpdater<T>;
  set: StateSetter<T>;
}

export function createStateHandler<T>(initialValue?: T): StateHandler<T> {
  let currentValue = initialValue as T;
  const { emit, subscribe } = createListenersHandler<T>();

  function set(value: T) {
    update(() => value);
  }

  function update(updater: (value: T) => T) {
    currentValue = updater(currentValue);
    emit(currentValue);
  }

  function getter() {
    subscribeAutoTracker(subscribe);
    return currentValue;
  }

  return { getter, update, set, subscribe };
}

We can use this state handler to update the computed function. Remove all the code and leave only the autoTrackCallback call and the return statement. After that, create the state handlers.

const { getter, subscribe, set } = createStateHandler<R>();

You will notice that we are calling createStateHandler without an argument, which means the internal state will initially be undefined. This is fine, because we are going to initialize the state before we expose a way to get it. But this is why we casted initialValue in the code.

Next, we update the call to autoTrackCallback:

autoTrackCallback(() => set(transform()));

That's it! Our computed function should look like this:

export function computed<R>(transform: StateGetter<R>): ComputedState<R> {
  const { getter, subscribe, set } = createStateHandler<R>();

  autoTrackCallback(() => set(transform()));

  return Object.assign(getter, { subscribe });
}

We can update the state function. Similar to what we did with computed, we remove most of the code except for the on function, and the return statement. Then, we create the state handlers:

const { getter, subscribe, update } = createStateHandler(initialValue);

Finally, we update the subscription callback to use the update function.

const on = <U>(source: Subscribable<U>, reducer: StateReducer<T, U>) => {
  source.subscribe((payload) => {
    update((value) => reducer(value, payload));
  });

  return Object.assign(getter, { subscribe, on });
};

With that, our state function should look like this:

export function state<T>(initialValue: T): State<T> {
  const { getter, subscribe, update } = createStateHandler(initialValue);

  const on = <U>(source: Subscribable<U>, reducer: StateReducer<T, U>) => {
    source.subscribe((payload) => {
      update((value) => reducer(value, payload));
    });

    return Object.assign(getter, { subscribe, on });
  };

  return Object.assign(getter, { subscribe, on });
}

All functions now share as much code as possible, differing only in their specific behavior.

In this post, we focused on sharing logic across our functions. But I don't want you to feel like we didn't made any progress. Now that we have a stable way to store and compute values, it would be great to have a way to listen to those changes and react to them, like an effect function.

Creating the effect

The effect function should take a callback that gets executed whenever any of the states used inside it changes. It works similarly to computed, but without storing a derived value.

As usual, we start by creating the effect.ts and effect.spec.ts files and adding our test suite:

describe("effect", () => {
  it("should run the callback when state changes", () => {
    const updateState = event<string>();
    const myState = state("initial").on(updateState, (_, newState) => newState);
    const spy = mock();

    effect(() => {
      spy(myState());
    });

    expect(spy).toHaveBeenCalledWith("initial");

    updateState("updated");
    expect(spy).toHaveBeenCalledWith("updated");
  });
});

Let's open the effect.ts file and define the effect function. Since the implementation is so simple, rather than explaining each step manually, we can go straight to the final version:

export function effect(callback: () => void) {
  autoTrackCallback(callback);
}

The effect function uses autoTrackCallback to automatically register and re-run the callback whenever its dependencies change.

Optimizing and Extending the System

There is still room for optimization, especially in memory management, if that's something you want to explore. By centralizing listener management in createListenersHandler, any optimizations we implement will automatically apply across the system. Maybe you want to add a manual unsubscription system or explore how an automatic unsubscription system could work? Any improvements you want to make, you just need to update createListenersHandler, and they will be applied system-wide.

What's next?

With this, we now have a robust foundation for a reactive system. From my perspective, this library is feature completed. In the next post, we will explore how to handle asynchronous state in a reactive system and create operators that allow finer control over state updates.

3-Getting derivated values reactively - Building a Reactive System in TypeScript

Michael De Abreu — Tue, 04 Mar 2025 11:00:00 +0000

Getting derivated values reactively

In the previous post, we built a reactive state system that allows us to define a state, subscribe to changes, and update it through event-driven actions. However, as we scale our system, we'll often need to derive new values based on the existing state.

For example, imagine we have a state holding a list of prices, and we need to calculate the total. Sure, we could manually sum them every time we need the value, but that's not a very declarative approach. Instead, wouldn't it be better if we could just say: 'Hey, whenever this list of prices changes, automatically update the total'?

That's exactly where computed values come in. They allow us to:

✔ Automatically derive state from other signals.

✔ Ensure recalculations happen only when necessary.

✔ Keep our code declarative and efficient.

In this post, we'll explore how to implement computed() in our reactive system, making sure it updates efficiently whenever its dependencies change.

Let's get started!

Defining computed values and how they work

This is the most exciting part so far because it's where Reactive Programming really starts to shine. But first, we need to define how we want this function to work. When we defined the state and how to update it, we used the Flux pattern to create something similar to Redux. Considering this, we could say that computed values work similarly to selectors. However, instead of selecting from a single centralized state, each computed function derives its value from multiple state instances.

const total = computed(
  (prices) => prices.reduce((total, price) => total + price),
  [prices],
);

With that, we have a simple computed function that includes a dependency array, similar to what React does. However, there's a key difference: in our approach, the callback receives the state directly.

Coding the computed function

Same as before, we will start by creating two files, computed.ts and computed.spec.ts, and fill the spec file with the initial tests.

import { describe, it, expect } from "bun:test";
import { computed } from "./computed";
import { state } from "./state";
import { event } from "./event";

describe("computed", () => {
  it("should return the computed value", () => {
    const prices = state<number[]>([5, 5, 5]);
    const totalPrice = computed(
      (prices) => prices.reduce((total, price) => total + price, 0),
      [prices],
    );
    expect(totalPrice()).toBe(15);
  });

  it("should update the computed value each time a dependency change", () => {
    const addPrice = event<number>();
    const prices = state<number[]>([5, 5, 5]).on(addPrice, (state, price) => [
      ...state,
      price,
    ]);
    const totalPrice = computed(
      (prices) => prices.reduce((total, price) => total + price),
      [prices],
    );

    expect(totalPrice()).toBe(15);
    addPrice(10);
    expect(totalPrice()).toBe(25);
  });
});

Here, we're testing two things: first, that the computed value is calculated correctly; and second, that it updates whenever a dependency changes.

After that, we need to fill the computed.ts file with:

export function computed<R>(
  transform: (...args: any[]) => R,
  dependencies: any[],
) {
  return () => {};
}

With that, our tests will fail, as expected.

To start with the computed, we need a way to get the latest state from all our dependencies, and since we are marking our dependencies as an array, we can use a map to extract it.

const getValues = () => dependencies.map((dep) => dep());

To set the initial state, we can call the transform function with the values from getValues.

let currentValue = transform(...getValues());

Since our computed function supports subscriptions, we can reuse the logic from state and event, adjusting the type and the naming where necessary.

const listeners: ((value: R) => void)[] = [];
const emit = (payload: R) => {
  listeners.forEach((listener) => listener(payload));
};
const subscribe = (listener: (payload: R) => void) => {
  listeners.push(listener);
};
const getter = () => currentValue;

You may have noticed that something is missing. We still need to update the state whenever any dependency changes. What we need is a way to listen every time any of the dependencies is updated, and we have that already with subscribe, and all of our dependencies have a subscribe method, so we can subscribe and update the internal value of the computed function, each time any of the dependencies are updated.

dependencies.forEach((dep) => {
  dep.subscribe(() => {
    currentValue = transform(...getValues());
    emit(currentValue);
  });
});

With all that, we should be able to create the computed function. It should be something like this:

export function computed<R>(
  transform: (...args: any[]) => R,
  dependencies: any[],
) {
  const getValues = () => dependencies.map((dep) => dep());
  let currentValue = transform(...getValues());

  const listeners: ((value: R) => void)[] = [];
  const emit = (payload: R) => {
    listeners.forEach((listener) => listener(payload));
  };
  const subscribe = (listener: (payload: R) => void) => {
    listeners.push(listener);
  };
  const getter = () => currentValue;

  dependencies.forEach((dep) => {
    dep.subscribe(() => {
      currentValue = transform(...getValues());
      emit(currentValue);
    });
  });

  return Object.assign(getter, { subscribe });
}

Our tests should pass, but Typescript won't be happy about it. To see all the errors you can run:

bun tsc --noEmit

You will get a list of errors. I'll show the first one only, but you can see a pattern.

src/computed.spec.ts:10:34 - error TS7006: Parameter 'total' implicitly has an 'any' type.

10       (prices) => prices.reduce((total, price) => total + price, 0),
                                    ~~~~~

Found 4 errors in the same file, starting at: src/computed.spec.ts:10

We have four errors, all originating from the same issue: TypeScript doesn't infer the type of total and price inside the reduce function. One way to fix this is by explicitly typing the argument: prices: number[]. However, since we are already passing a state object into the dependency list, we should be able to infer this type automatically, shouldn't we?

Of course, we could do that. But wouldn't it be even better if we could eliminate the dependency list altogether? If we could just somehow be able to automatically listen to every update in each state being used inside the computed function? We are already listening to updates, but how can we do it automatically?

Replacing the Dependency List with Auto-Tracking

It might sound like this is a really complex thing to do, but it's actually pretty easy, much like everything we have done so far. Let's define how the computed function should work with an automatic tracker, and how we could integrate it into our code.

const total = computed(() =>
  prices().reduce((total, price) => total + price, 0),
);

Here we don't have a dependencies array. But we have a function, that should be called each time prices is updated, and prices itself. What we want to do, is to register the callback passed to computed to the prices subscription.

But we could also have something like this:

const totalLabel = computed(() => `Total: ${total()} EUR`);

We must support nested computations while ensuring that each computed callback subscribes only to its actual dependencies, avoiding unnecessary subscriptions.

With all that considered, we can make a resume of the things we know.

We have a callback that we need to register.
We are calling a getter in each dependency.
We need to stack callbacks to manage different subscription scopes.

If we maintain a stack of currently tracked computations, we can dynamically capture dependencies when state getters are called inside computed(). This allows for an automatic dependency tracking mechanism without requiring an explicit dependency list.

Adding Auto-Tracking for Computed Values

Let's create an autotracker.ts file. The autotracker won't have a spec file, because its state will be tested as part of the computed spec file. So, let's update the computed.spec.ts.

import { describe, it, expect } from "bun:test";
import { computed } from "./computed";
import { state } from "./state";
import { event } from "./event";

describe("computed", () => {
  it("should return the computed value", () => {
    const prices = state<number[]>([5, 5, 5]);
    const totalPrice = computed(() =>
      prices().reduce((total, price) => total + price, 0),
    );
    expect(totalPrice()).toBe(15);
  });

  it("should update the computed value each time a state change", () => {
    const addPrice = event<number>();
    const prices = state<number[]>([5, 5, 5]).on(addPrice, (state, price) => [
      ...state,
      price,
    ]);
    const totalPrice = computed(() =>
      prices().reduce((total, price) => total + price),
    );

    expect(totalPrice()).toBe(15);
    addPrice(10);
    expect(totalPrice()).toBe(25);
  });

  it("should update the computed value each time a computed change", () => {
    const addPrice = event<number>();
    const prices = state<number[]>([5, 5, 5]).on(addPrice, (state, price) => [
      ...state,
      price,
    ]);
    const totalPrice = computed(() =>
      prices().reduce((total, price) => total + price),
    );
    const totalLabel = computed(() => `Total: ${totalPrice()} EUR`);

    expect(totalLabel()).toBe("Total: 15 EUR");
    addPrice(10);
    expect(totalLabel()).toBe("Total: 25 EUR");
  });
});

We can start creating the array, where we will stack the callbacks.

const trackerStack: (() => void)[] = [];

After that, we need to add a callback to the stack, call it, and remove it from the stack. It will make sense soon.

export function autoTrackCallback(callback: () => void) {
  trackerStack.push(callback);
  callback();
  trackerStack.pop();
}

Lastly, we need a way to subscribe to the latest callback added to the stack.

export function subscribeAutoTracker(
  subscribe: (listener: () => void) => void,
) {
  const tracker = trackerStack.at(-1);
  tracker && subscribe(tracker);
}

With all that, we can start using the tracking in our computed function. First, we need to remove the dependencies array and all related code.

export function computed<R>(transform: (...args: any[]) => R) {
  let currentValue: R;

  const listeners: ((value: R) => void)[] = [];
  const emit = (payload: R) => {
    listeners.forEach((listener) => listener(payload));
  };
  const subscribe = (listener: (payload: R) => void) => {
    listeners.push(listener);
  };
  const getter = () => currentValue;

  return Object.assign(getter, { subscribe });
}

We need to pass a callback to autoTrackCallback, but which one? This callback will be called each time one of the dependencies has been updated, and when it happens, we need to update the internal currentValue and emit the new value. That should be the function of the callback we add to the autoTrackCallback, so let's create it:

const transformAndEmit = () => {
  currentValue = transform();
  emit(currentValue);
};

Finally, we add the transformAndEmit function to the autoTrackCallback.

autoTrackCallback(transformAndEmit);

If we go back one minute to the autoTrackCallback function, we can see that we are pushing the callback and then calling it. This call ensures that the getter functions from all dependencies are executed, making it the perfect place to subscribe to the callback. Popping the callback afterward ensures that the stack is cleared once all subscriptions are registered.

The getter is an inline function returning the currentValue. Let's update it, so it also subscribes to the autotracker.

const getter = () => {
  subscribeAutoTracker(subscribe);
  return currentValue;
};

We also need to apply this change in the state function. Open the state.ts file find the getter function, and update it to, an almost identical version:

const getter = () => {
  subscribeAutoTracker(subscribe);
  return currentState;
};

If we run the tests now, all tests are passing. Yaju!

Wrapping It Up

With this update, our computed values no longer require manually listing dependencies. We now have a fully reactive system that updates automatically whenever any dependent state changes.

Here is an overview of our Reactive System so far:

Event<T>: Allows firing events and subscribing to them.
State<T>: Represents a reactive value that updates in response to events.
Computed<T>: Derives new values reactively, tracking dependencies automatically.
AutoTracker: Manages subscription scopes dynamically, ensuring that computed values track only the state they depend on.

With this architecture, we have a fully declarative and efficient reactive system.

In the next posts, we'll make some optimizations, handle side effects with an effect function, and further enhance our Reactive System.

1-Introduction to Reactivity - Building a Reactive System in Typescript

Michael De Abreu — Tue, 25 Feb 2025 11:00:00 +0000

Recently, I read Writing an Interpreter in Go, a great book that walks you through building the Monkey programming language step by step. Since I wasn’t familiar with Go, I decided to implement the interpreter in TypeScript instead, first following the object-oriented approach used in the book, but after I finished, I updated it using a more functional style. I used generators to handle the state of the Lexer and the stream of tokens in the Parser. I did not have to update the Evaluator, because it was always a set of functions.

While I was happy with the result, because I had moved it to a more functional approach, it still had mutable variables. I liked how in the Evaluator I did not have any "global" variable, but I needed to stream the parser, and I needed to be able to peek into that stream before I moved as well.

This led me to explore how to deal with state management in a way that avoids direct mutation.

Functional Programming and State Management

When we work with states, we often face a common challenge: mutability. In an imperative paradigm, states change over time, leading to side effects, harder debugging, and increased complexity.

This is where functional programming (FP) provides a more predictable and safer approach. In FP, pure functions are a fundamental concept. A function is pure if it meets two conditions:

No side effects: It does not modify any external variable or perform operations like changing global objects, writing to a file, or manipulating the DOM.
Deterministic output: Given the same inputs, it always returns the same output.

Let’s break this down with an example. Imagine we want to add two numbers, a and b. With imperative programming, you would do something like:

const a = 2;
const b = 3;
console.log(a + b);

But, you can do that using a pure function instead:

const add = (a: number, b: number): number => a + b;

console.log(add(2, 3)); // Always returns 5

However, the difference between this and an impure function is clear when some variables are global and mutable.

let total = 0;
const addToTotal = (value: number) => {
  total += value; // Modifies an external variable
  return total; 
};
console.log(addToTotal(3)); // Returns 3
console.log(addToTotal(3)); // Returns 6 (different output for the same input)

Now, each time we call addToTotal we are incrementing the total variable, in a way that is not predictable. This is called a side-effect.
This approach becomes problematic when multiple parts of the code depend on the same state and can modify it without restrictions, leading to race conditions or hard-to-reproduce bugs.

Immutable State and Functional Programming

To avoid these issues, functional programming favors immutable data structures. Instead of modifying the existing state, we return a new version with the applied changes:

const state = { count: 0 };
const incrementState = (state: { count: number }) => {
  return { ...state, count: state.count + 1 };
};
const newState = incrementState(state);
console.log(state.count); // 0
console.log(newState.count); // 1

This approach offers several key advantages:

Predictability: Avoiding mutations, changes are easier to track.
Simpler debugging: If the state doesn’t change unexpectedly, bugs are easier to identify, and reproduce.
Optimization with efficient immutable structures: Libraries like Immer or techniques like structural sharing allow efficient updates without copying entire data structures.

If we can’t update the state directly, how do we maintain a shared state that persists in function calls? The short answer is: we don't, at least, not in the traditional sense.

However, if you’ve worked with React, you’ve probably noticed that functional components can store and update state. But how? If functions are stateless, where does that state live?

This brings us to reactive programming, a paradigm that models state changes declaratively, without relying on direct mutation.

What is Reactive Programming?

When we need to share state across an app, keeping it in sync can be tricky. If anything can update it, how do you know what’s changing and when? That’s where Reactive Programming comes in. It follows a declarative paradigm to solve this problem. Instead of treating data as static values that we manually update, we model it as a stream of updates, ensuring predictable state management throughout the app.

At its core, a reactive system allows us to define relationships between different pieces of data, so that when one value changes, everything that depends on it updates accordingly, without requiring explicit, manual intervention.

This paradigm is particularly useful in a wide range of scenarios, such as:

User interfaces - Efficiently updating components when underlying data changes, avoiding unnecessary re-renders.
Data processing pipelines - Reactively transforming and filtering streaming data.
State synchronization - Keeping distributed systems in sync without polling.
Game development - Managing game state, physics simulations, or AI behaviors.
Automation & event-driven systems - Triggering workflows dynamically based on changes in data.

Unlike imperative programming reactive programming allows us to define what should happen when data changes, and let the system handle the updates efficiently.

How Reactivity Aligns with Functional Programming

If we check what makes a reactive system really effective, it's very similar to what we need from pure functions and FP. First, you want to avoid direct state mutations. Second, function composition makes it easier to build predictable behaviors. And finally, side effects need to be carefully managed.

This is where concepts like signals, computed values, and reactive effects come into play.

The Rise of Signals in Modern JavaScript

One of the most widely adopted patterns in modern reactive systems is the Signal. A signal is a special kind of reactive variable that automatically tracks its dependencies and updates whenever the values it relies on change. Unlike traditional event-driven models, signals offer a fine-grained and efficient way to propagate changes.

Signals have become so popular that many frameworks, like Angular, Solid, Svelte, and Preact, have adopted their implementations. Because of this, the concept of signals is now being considered for standardization in JavaScript. The TC39 committee, responsible for evolving JavaScript, has an active proposal to introduce signals as a built-in language feature, to allow those same frameworks to leverage a better experience and performance when using them.

The fact that Signals are being considered for native support highlights how essential reactive state management has become, not just in UI frameworks but in general programming.

What Comes Next?

With this foundation in place, we are ready to explore how to build a lightweight reactive system from scratch. In this series, we will dive into the core mechanics behind signals and how we can implement them efficiently in TypeScript.

2-Writing a Signal - Building a Reactive System in Typescript

Michael De Abreu — Tue, 25 Feb 2025 11:00:00 +0000

In the previous post, we explored functional programming and how reactive programming offers a way to manage state without direct mutation. We discussed how signals have emerged as a powerful mechanism for fine-grained reactivity, efficiently tracking dependencies and updating values automatically.

Now, it’s time to put these concepts into practice. Instead of relying on an existing library, we will build our own lightweight reactive system in TypeScript.

Defining a Signal

We know what a Signal is, but if you look at different implementations, each library has its own take on it. However, the principle is the same regardless. We need something that will hold a value, and expose a way to get and set that value and subscribe to react when the value changes.

For this exercise, we will do something like this:

const counter = state(0); // We set the initial state.

console.log(counter()) // We get the latest state at this time.

counter.subscribe((count) => {
  console.log(count) // We get the latest state at any time.
});

You can notice the counter does not have yet a way to update it, but we will worry about that later.

Coding the Signal

I'm using Bun because it has built-in TypeScript support and a test runner that is partially compatible with Jest. However, you can use Node with your preferred test runner, whether you're working with plain JavaScript or TypeScript.

First, let's configure our project with

mkdir another-signal
cd another-signal
bun init

bun init helps you get started with a minimal project and tries to guess sensible defaults. Press ^C anytime to quit

package name (another-signal): another-signal
entry point (index.ts): index.ts

Done! A package.json file was saved in the current directory.
 + index.ts
 + .gitignore
 + tsconfig.json (for editor autocomplete)
 + README.md

To get started, run:
  bun run index.ts

With that, we can start coding. Create a src folder, and add a state.ts file and a state.spec.ts file. Open the state.spec.ts file, and write our first test.

import { describe, it, expect } from "bun:test";
import { state } from "./state";

describe("state", () => {
  it("should return the initial state", () => {
    const myState = state("initial");
    expect(myState()).toBe("initial");
  });
});

This test is short, and yet it tests the initial API we defined earlier. Of course, the test will fail, because we don't have yet any export in our state file. To fix that, open the state file, and write:

export function state() {
  return () => {};
};

With this, we can run:

bun test

And we will have an error:

bun test v1.2.3 (8c4d3ff8)

src\state.spec.ts:
2 | import { state } from "./state";
3 |
4 | describe("state", () => {
5 |   it("should return the initial state", () => {
6 |     const myState = state("initial");
7 |     expect(myState()).toBe("initial");
                          ^
error: expect(received).toBe(expected)

Expected: "initial"
Received: undefined

      at <anonymous> (.\src\state.spec.ts:7:23)
✗ state > should return the initial state

 0 pass
 1 fail
 1 expect() calls
Ran 1 tests across 1 files. [37.00ms]

We need the state function, to hold a value, and return a getter function to access that value. It sounds simple, and it is simple:

export function state<T>(initialValue: T) {
  let value = initialValue;

  return () => value;
}

With that, our test now pass:

bun test

bun test v1.2.3 (8c4d3ff8)

src\state.spec.ts:
✓ state > should return the initial state

 1 pass
 0 fail
 1 expect() calls
Ran 1 tests across 1 files. [36.00ms]

Right now, our state function is just a simple getter, it holds a value, but it cannot be updated. Before we jump into making our state updatable, we need to define how we want updates to work.

Should we expose a simple setter function? Should updates be synchronous or asynchronous? And how can we notify subscribers when the state changes?

These are the questions we need to address as we continue designing our reactive system. In the next section, we’ll explore how to introduce updates to our state, ensuring that any dependent values react automatically.

Why Create Another Signal Library?

With so many reactive libraries out there, you might be wondering, why build another one?

Most existing signal libraries allow updating state through a setter method. While this approach is intuitive, in practice, it still feels like a mutable variable stored elsewhere. The signal tracks dependencies and triggers updates efficiently, but ultimately, it’s just another container for a value that gets replaced over time.

However, other libraries take a different approach, they update state in response to an event or action, rather than allowing direct mutations. This aligns more with the Flux architecture, where state changes are triggered by actions rather than manually setting values.

I wanted to explore this idea further and see how a signal-based system could follow a Flux-like approach, ensuring that state updates are structured, predictable, and traceable.

Beyond just building something new, this project was an opportunity to deepen my understanding of reactivity, how dependencies are tracked, how updates propagate, and how different approaches impact performance and maintainability. That’s why I decided to write these posts: to share what I learned along the way.

So, now we know how we want to update the state. But before making it updatable, let’s think about the best way to do it. Instead of directly mutating the state, we want a structured, event-driven approach, one that ensures updates are predictable and traceable. This is where events come into play.

Defining an Event, and how it can be integrated with the state

Since we want to apply the Flux pattern, we need to define how actions are created and how they update the state. We need to build something that works like this:

const increment = event();
const incrementTimes = event<number>();
const counter = state(0)
  .on(increment, (count) => count + 1)
  .on(incrementTimes, (count, times) => count + times);

console.log(counter()); // 0
increment();
console.log(counter()); // 1

counter.subscribe((count) => console.log(count));

increment() // This should fire the subscribe and log 2
incrementTimes(3) // This should fire the subscribe and log 5

Now we have defined a way to update the state, and because we are using the Flux pattern, it's very easy to understand how and when the state is being updated.

Coding the Event

Create an event.ts and a event.spec.ts file, in the src folder. Open the event.spec.ts file, and add the test case:

import { describe, it, expect, mock } from "bun:test";
import { event } from "./event";

describe("event", () => {
  it("should notify listeners when emitted", () => {
    const myEvent = event<string>();
    const mockListener = mock();
    myEvent.subscribe(mockListener);
    myEvent("test");
    expect(mockListener).toHaveBeenCalledWith("test");
  });
});

If we try to run the test runner, we will have a similar error to the one we had when we first ran the state test suite. So, instead, open the event.ts file, and update it to:

export function event() {
  const dispatcher = () => {};
  const subscribe = () => {};

  return Object.assign(dispatcher, { subscribe });
}

With that, the test case will fail as expected.

Now, we need to turn this empty structure into a fully working event system. The goal is simple: whenever the event is triggered, all subscribed listeners should be notified with the provided payload. To achieve this, we need a way to keep track of listeners and notify them when the event is fired.

const listeners: ((payload => T): void)[] = [];

Now, each time we call the created event, we want to notify the listeners that an event has been called.

const dispatcher = (payload: T) => {
  listeners.forEach((listener) => listener(payload));
}

Lastly, we need a way to add a listener to our internal array.

const subscribe = (listener: (payload => T): void) => {
  listeners.push(listener);
}

After that, we should have something like this:

export function event<T = void>() {
  const listeners: ((payload: T) => void)[] = [];
  const dispatcher = (payload: T) => {
    listeners.forEach((listener) => listener(payload));
  };
  const subscribe = (listener: (payload: T) => void) => {
    listeners.push(listener);
  };

  return Object.assign(dispatcher, { subscribe });
}

And with that, our tests should pass.

bun test

bun test v1.2.3 (8c4d3ff8)

src\event.spec.ts:
✓ event > should notify listeners when emitted

src\state.spec.ts:
✓ state > should return the initial state

 2 pass
 0 fail
 2 expect() calls
Ran 2 tests across 2 files. [142.00ms]

Awesome! This is all for the event, so let's go back to the state.

Updating the state

So far, we’ve built a reactive state system that can hold values and allow subscriptions. However, we still haven’t given it the ability to change over time. Let’s take the next step: making our state updateable through events.

First, let's start adding more tests to our test suite:

it("should update state when an event is triggered", () => {
  const increment = event();
  const incrementTimes = event<number>();
  const counter = state(0)
    .on(increment, (count) => count + 1)
    .on(incrementTimes, (count, times) => count + times);

  increment();
  expect(counter()).toBe(1);

  incrementTimes(3);
  expect(counter()).toBe(4);
});

it("should notify listeners the state has been updated", () => {
  const updateEvent = event<string>();
  const myState = state("initial").on(updateEvent, (_, newValue) => newValue);
  const mockListener = mock();
  myState.subscribe(mockListener);
  updateEvent("updated");

  expect(mockListener).toHaveBeenCalledWith("updated");
});

Of course, the test will fail as expected, but we can start updating the state. Since we require it to have a subscribe method, there is no reason why we can't reuse the code from the event, so we do, and add it to the state.

const listeners: ((payload: T) => void)[] = [];
const dispatcher = (payload: T) => {
  listeners.forEach((listener) => listener(payload));
};
const subscribe = (listener: (payload: T) => void) => {
  listeners.push(listener);
};

The second thing we need is the on method. So far, we've kept things really simple here, and we are not going to start complicating it now, the on method is as simple as you would expect:

const on = <U>(
  event: { subscribe: (listener: (payload: U) => void) => void },
  reducer: (state: T, payload: U) => T,
) => {
  event.subscribe((payload) => {
    currentState = reducer(currentState, payload);
    emit(currentState);
  });
};

This might be the most "complex" code that we had so far, but I think it's simple enough. We call on with an event and a reducer. We subscribe to that event, and it's called, we call the reducer with the currentState and the value emitted from the event, and store the result in the currentState variable, and we emit that change for whomever is listening.

Lastly, and since we need to use a similar Object.assign here, we need to move the getter to be a function as well.

const getter = () => currentState;

With that, we can glue it all together, and return:

return Object.assign(getter, { subscribe, on });

But, wait. To be able to chain the on method like we want, we need to return that same object from the state function, and the on method. With that, we've finished the state.

export function state<T>(initialValue: T) {
  let currentState = initialValue;

  const listeners: ((value: T) => void)[] = [];
  const emit = (payload: T) => {
    listeners.forEach((listener) => listener(payload));
  };
  const subscribe = (listener: (payload: T) => void) => {
    listeners.push(listener);
  };

  const getter = () => currentState;

  const on = <U>(
    event: { subscribe: (listener: (payload: U) => void) => void },
    reducer: (state: T, payload: U) => T,
  ) => {
    event.subscribe((payload) => {
      currentState = reducer(currentState, payload);
      emit(currentState);
    });
    return Object.assign(getter, { subscribe, on });
  };

  return Object.assign(getter, { subscribe, on });
}

Wrapping It Up

With this implementation, we now have a fully reactive state management system that:
✔ Uses signals to hold state.
✔ Supports subscriptions for automatic reactivity.
✔ Allows event-driven updates, aligning with Flux principles.

This system might be minimal, but it provides a strong foundation to build upon. This approach was so effective that I used it to replace the mutable variables in my Lexer and Parser.

In the next post, we’ll explore optimizations, computed values, and handling asynchronous updates, making our reactive system even more powerful.

Introducing zustand-entity-adapter

Michael De Abreu — Sat, 21 Sep 2024 09:27:38 +0000

Hello there. If you are following this series, you know I sent this proposal to the Zustand team. After some weeks, their feedback was to wait, stating that this was in the field of third-party libraries. Considering this, and since I didn't find anything similar, I created zustand-entity-adapter.

What is zustand-entity-adapter?

It's a tiny (~3kb/~1kb gzipped) library to create an Entity Adapter for Zustand. It also allows you to create a convenient store that includes any additional structure and the actions and selectors to be used to manage the entities.

Moreover, this library takes advantage of how simple Zustand is and integrates with it very well.

How to use zustand-entity-adapter?

Some of the API for the library has been developed in this series and can be used as documentation. Additionally, you can find more information on Entity Adapters from @ngrx and RTK.

As you may notice, this API draws inspiration from both the @ngrx/entity package and RTK's createEntityAdapter. But since Zustand is not using a reducer, there are some differences between those implementations and this one.

`createEntityAdapter`

When using createEntityAdapter, this will return an object with methods getState, getSelectors, and getActions. They all have similar counterparts in both implementations, but they have subtle differences because of Zustand's nature. Also, the options for createEntityAdapter are a little different from those of @ngrx and RTK.

idSelector: In @ngrx/entity and RTK, this is like the selectId option. This only accepts a function that takes an entity and returns the value that should uniquely identify that entity.
sort: In @ngrx/entity and RTK, this is like the sortComparer option. This only accepts a function that takes two entities and returns a number that will be used to sort them.

`getActions`

In both the @ngrx/entity and RTK implementations, the EntityAdapter has the actions as direct methods of the adapter. This is not possible here because, to do so, we would need the store information, but to create the store, we need the adapter information. Because of this, the actions are generated by a getActions method.

With this approach, we have an additional advantage. In Zustand, we usually have the state and actions together, although it also allows using no-store actions. By externalizing the action generation, you can use either approach to configure your store.

Using state and actions together:

    const adapter = createEntityAdapter<User, string>();
    type StoreState = ReturnType<typeof adapter.getState> & ReturnType<typeof adapter.getActions>
    const store = create<StoreState>((set) => ({
      ...adapter.getState(),
      ...adapter.getActions(set),
    }));

Using external actions:

    const adapter = createEntityAdapter<User, string>();
    const store = create(adapter.getState);
    const actions = adapter.getActions(store.setState);

Although the actions generated are more or less the same as in both @ngrx/entity and @reduxjs/toolkit, you need to consider that here, actions only need the payload to be used.

  actions.addOne({ id: uuid(), name: 'John Doe' });

`getSelectors`

In this initial version of the library, the adapter doesn't have a concept of what a slice is, and because of this, neither do the selectors. The getSelectors method creates the same selectors @reduxjs/toolkit generates with adapter.getSelectors(), but it doesn't allow any argument to compute the property; therefore, the selection will always be from the root of the state.

`getState`

Because Zustand allows adding properties more easily than Redux, instead of having a concept of "initial state", getState only has the state of the entity adapter. If you want to add more properties to the store, just do so.

  const adapter = createEntityAdapter<User, string>();
  interface StoreState extends ReturnType<typeof adapter.getState> {
    selectedUser: User | undefined;
  }
  const store = create<StoreState>(() => ({
    ...adapter.getState(),
    selectedUser: undefined
  }));

That's all folks!

I hope you like this library as much as I enjoyed developing it. In another post, I'll talk more about how to use the useEntityStore function.

Thanks a lot!

Angular CLI is getting better

Michael De Abreu — Mon, 16 Sep 2024 16:00:00 +0000

Angular CLI is a great tool for Angular developers, and for years the experience working with it has been a love/hate relationship. I love how easy most things work out of the box, and the experience you get creating components, and services, although it can be overwhelming, because it has so many options, and configurations, you can easily get distracted and confused.

However, there were a couple of things that just didn't work with vanilla Angular CLI, and then you would need to use a meta-framework, a wrapper, or a bash script hook to be able to do these things. You could even convince yourself you don't need them. 1 2

But that is about to change. Introducing:

Server-side Routing Configuration

You know that now if you want to prerender a route with URL params you need to create a text file to tell Angular what URLs will it prerender? Well, with the introduction of the PR#28346 we will be able to do things like configuring routes with dynamic params to be pre-rendered and even configure a fallback in case it hasn't.

const serverRoutes: ServerRoute[] = [
  {
    path: '/product/:id',
    renderMode: RenderMode.Prerender,
    async getPrerenderParams() {
      const dataService = inject(ProductService);
      const ids = await dataService.getIds(); // Assuming this returns ['1', '2', '3']
      return ids.map(id => ({ id })); // Generates paths like: [{ id: '1' }, { id: '2' }, { id: '3' }]
    }
  }
];

This will be part of the release of Angular 19, which will be released in mid-November.

Even if we need to wait for official documentation, the PR lets us see an excellent API to work with, and maybe we can eliminate the need for a pre-script, or a meta-framework.

Environment variables-ish

Currently, Angular doesn't support environment variables, not even from the environment itself, not from an environment file, like a .env, however, with the introduction of the PR#28362 that might change.

And I say it might because I want to be optimistic about this, but it doesn't look like it. The PR doesn't give us much information like the SSR Routing does. But it definitively lets us see that it won't be supporting environment variables directly, but it will introduce a new option called --define. And we'll see how that works.

ng build --define "BUILD_TIME=$(date)"

This will also be part of Angular 19, so we won't wait much until this is available.

That's all folks!

When we are closer to the date, I'll try to update you about this, and maybe we can create an app or something to see how much of an improvement these features really are.

Having been the original requestor for a way to be able to create a server-side Route configuration does create some bias in me about this, but it also makes me realize why people don't choose Angular as its first option. I mean, other frameworks have had these features for years, and they are really easy to use, but when we wanted to use them in Angular, you would need to create several hacks and workarounds to be able to do something similar.

Hopefully, things like these and the Signal API change some minds about Angular, because I think it's a great framework that doesn't get the love it deserves.

How to add Jest into your Vite project with TS

Michael De Abreu — Sat, 30 Mar 2024 13:12:29 +0000

Hi future me! I'm sure you are as amazed as I am right now to find that the guide you are looking for was written by yourself, it happens to the best of us.

Remember you wrote this for:

Vite 5
Jest 29
Typescript 5.2
And... React 18 in case we have something else in the future

Let's get started!

First, you need to add a couple of dependencies:

npm i -D jest jest-environment-jsdom jest-transform-stub ts-jest @types/jest @testing-library/react

jest: The testing framework

jest-environment-jsdom: Jest environment for testing in a browser-like environment

jest-transform-stub: Jest transformer for handling non-JS files

ts-jest: Jest preset for TypeScript

@types/jest: TypeScript type definitions for Jest

@testing-library/react: Testing utilities for React components

Ok, I agree they are a lot. But that's the reason why you are writing this, ain't?

Creating the Jest Config file

So, by default Jest doesn't parse TS, even if you have the required dependencies. So you need to tell Jest how to parse it, and you do that using a jest.config.cjs file.

Notice that it is a cjs file, because we want to use the old CommonJs module resolution here. Vite supports the new ES module standard by default, and creates a package.json configuration to load .js files as ES module, so by using a cjs we are telling Node to load this file using the CommonJs module resolution instead.

Lucky for us, there is a command we can use to create it:

# Initialize a Jest configuration file for TypeScript
npx ts-jest config:init

That will create a base jest.config.js, that we need to rename to jest.config.cjs and update it with the following content:

/* eslint-disable */

const { pathsToModuleNameMapper } = require("ts-jest");
const { compilerOptions } = require("./tsconfig");

/** @type {import('ts-jest').JestConfigWithTsJest} */
module.exports = {
  roots: ["<rootDir>"],
  preset: "ts-jest",
  testEnvironment: "jsdom",
  modulePaths: [compilerOptions.baseUrl],
  moduleNameMapper: pathsToModuleNameMapper(compilerOptions.paths ?? {}),
  transform: {
    ".+\\.(css|less|sass|scss|png|jpg|gif|ttf|woff|woff2|svg)$":
      "jest-transform-stub",
  },
};

So, yes, you found a command a ran it, and then you create another file and updated it until it worked.

You'll notice that this config file already supports for the path mapping feature from TS. You are welcome!

That's all! Right? -- No

There is an import in the App.tsx created by Vite by default, that is importing a logo from a root like route:

import viteLogo from '/vite.svg'

I don't know what's that, I don't know where that is being imported from, and I don't need that, so I removed it to make this configuration works.

Extra: Adding Path mapping support for Vite

Vite doesn't support Path mapping either, but we have a plugin available for that.

Path mapping is a TypeScript feature that simplifies file imports by allowing developers to create aliases for directory paths relative to the project root. It enhances code readability and maintainability by replacing lengthy or complex import paths with custom aliases.

npm i -D vite-tsconfig-paths

With that, we can update our vite.config.ts file with that.

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import tsconfigPaths from "vite-tsconfig-paths";

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [react(), tsconfigPaths()],
});

That's all future me!

I hope this has been useful to you, and maybe others, but I know you'll forget this as soon as I publish this. If this is no longer valid, and you are me please update the post so future us can use it. If you are not me, please, let me know in the comments, so I can update the post.

As always, thanks for reading!

Zustand EntityAdapter - A bookshelf example

Michael De Abreu — Mon, 11 Mar 2024 12:39:42 +0000

In the first post, we learned how to create an EntityAdapter for Zustand. In this one, we'll learn how to use it in our projects.

For this example, we want to manage a book collection, and we are going to use the books as entities. We'll use a clean React project, the React setup you choose is fine. In my case, I'm using StackBlitz, as I do with most of my experiments. This is not sponsored.

Creating the store

First, let's create the interface for each book.

Interface

interface Book {
  bookId: string;
  title: string;
}

It's a simple interface, with two properties: the title and the bookId.

Note
I would like to showcase the idSelector, and that's why we are using another property to hold the entity ID.

With that interface, we can create our entityAdapter.

bookAdapter

To create our bookAdapter, let's create the idSelector function and use the createEntityAdapter function.

const idSelector = (book: Book) => book.bookId;

const bookAdapter = createEntityAdapter({ idSelector });

If we weren't providing an idSelector, we would have to provide the Book interface as the generic type.

const bookAdapter = createEntityAdapter<Book>();

With that, we will have the bookAdapter with the correct typings for all the methods.

Now we can use our bookAdapter to create the store.

useBookStore

To create the store itself, we have different alternatives. All using approaches that are present on the Zustand docs.

The first one is the basic approach to be used with Typescript.

import { create } from 'zustand';

...

type StoreState = EntityState<Book> & EntityActions<Book>;

export const useBookStore = create<StoreState>()((set) => {
  return {
    ...bookAdapter.getState(),
    ...bookAdapter.getActions(set),
  };
});

It may be counterintuitive to call a function twice and declare the StoreState type, but as I mentioned, this is the recommended approach to use Zustand with Typescript.

The second one is an alternative option in the basic usage guide with Typescript using combine:

import { create } from 'zustand';
import { combine } from 'zustand/middleware';

...

export const useBookStore = create(
  combine(bookAdapter.getState(), bookAdapter.getActions)
);

As you can see, the adapter we created is flexible enough for both approaches.

The last one is not suggested as part of the Zustand with Typescript usage, but a section called Practice with no store actions. This approach allows us to set our actions outside the store.

import { create } from 'zustand';

export const useBookStore = create(bookAdapter.getState);

export const bookActions = bookAdapter.getActions(useBookStore .setState);

While the first two alternatives will create the same store, with actions within, the last one will create a store with the actions outside. There is no recommended way to do it, you can choose the one you prefer.

I'll use the last one for the rest of the example, but it won't affect much if you choose to use one of the first two.

Lastly, we will generate our selectors, using the bookAdapter.

export const bookSelectors = bookAdapter.getSelectors();

If we put it all together, we will have this:

import { create } from 'zustand';
import { Book } from 'src/models/book';
import { createEntityAdapter } from 'src/zustand-entityadapter/creators';

const idSelector = (book: Book) => book.bookId;

const bookAdapter = createEntityAdapter({ idSelector });

export const useBookStore = create(bookAdapter.getState);

export const bookActions = bookAdapter.getActions(useBookStore.setState);

export const bookSelectors = bookAdapter.getSelectors();

Let's create our components

Ok, so now we have all the ingredients to show our entities. But where are we going to show them? Well, in this case, I think what's important is to showcase how to interact with the store, so, let's just create a list component to show the books, a book component that allows us to edit the book, and one to add a book to our list.

BookList

Let's start creating our BookList component. Here we want to show all the books that are in the store.

import { FC } from 'react';
import { bookSelectors } from './useBookStore';
import { BookItem } from './BookItem';
import styles from './BookList.module.css';

const { selectAll } = bookSelectors;

export const BookList: FC = () => {
  const books = useBookStore(selectAll);
  return (
    <ul className={styles.BookList}>
      {books.map((book) => (
        <BookItem book={book} key={book.bookId} />
      ))}
    </ul>
  );
}

As you can see, getting a list of our books is as simple as this.

Note
I won't go into styles, they are simple enough for this not to be too ugly. However, you can find the styles in the StackBlitz at the bottom.

BookItem

I think this one will be the more complex component. As you notice, this one will get the book as a prop. This component will be responsible for that book edition and removal.

import { ChangeEventHandler, FC } from 'react';
import { Book } from '../models/book';
import { bookActions } from './useBookStore';
import styles from './BookItem.module.css';

interface BookItemProps {
  book: Book;
}

const { updateOne, removeOne } = bookActions;

export const BookItem: FC<BookItemProps> = ({ book }) => {
  const handleChange: ChangeEventHandler<HTMLInputElement> = (e) => {
    const title = e.target.value;
    updateOne({ id: book.bookId, update: { title } });
  };

  return (
    <li className={styles.BookItem}>
      <>
        <form className={styles.BookItemForm}>
          <input type="text" onChange={handleChange} value={book.title} />
        </form>
        <button
          type="button"
          onClick={() => removeOne(book)}
          className={styles.BookItemAction}
        >
          Remove
        </button>
      </>
    </li>
  );
};

We could improve this implementation with an edit/submit pattern, to avoid rendering on every change. But I want to focus here on the simplicity of this.

AddBook

From this component, we will allow the user to add a book to the list.

import { FC, FormEventHandler, useState } from 'react';
import { bookActions } from './useBookStore';
import styles from './AddBook.module.css';

let id = 1000;

const { addOne } = bookActions;

export const AddBook: FC = () => {
  const [title, setTitle] = useState('');

  const handleSubmit: FormEventHandler = (e) => {
    e.preventDefault();
    if (title.trim() === '') {
      return;
    }
    addOne({ bookId: `${id++}`, title });
    setTitle('');
  };

  return (
    <div className={styles.AddBook}>
      <form className={styles.AddBookForm} onSubmit={handleSubmit}>
        <input
          type="text"
          value={title}
          onChange={(e) => setTitle(e.target.value)}
        />
        <button className={styles.AddBookAction} type="submit">
          Add
        </button>
      </form>
    </div>
  );
};

This is a simple form to edit the book's name and submit it to the store.

Putting it all together

With all this, we can update our App component to use the components we have created:

import './App.css';
import { AddBook } from './components/AddBook';
import { BookList } from './components/BookList';

function App() {
  return (
    <>
      <BookList />
      <AddBook />
    </>
  );
}

export default App;

This is where Zustand flexes. There is no Provider configuration, of any kind. Zustand doesn't need them, and we don't need them either.

I think this is powerful because it allows us to create stores close to the components that will be using those stores, again, just like you would do with a Service when you use Angular. I'm sure three folks will get that feeling, but I'm fine with it.

Adding a favorite book

So far, we have seen what we can do with our entity adapter, but what about those extra properties we want to handle as well?

Well, I think that one of the benefits of using Zustand is being able to manage little pieces of standalone data. For example, if I want to handle a favorite book, I could do something like:

export const useFavoriteBookStore = create<{ favorite?: Book }>(() => ({}));

This will work, but for something simple like this, maybe it would be better to add it to the same store, right? On the other hand, depending on the complexity of the state you want to manage, it would be better to split it into its own store. That's why it's better to have a choice.

Extending the store

To extend the example, I'll show you how you could add your properties to the store that we have created. We will update our store code to:

export const useBookStore = create(
  devtools(() => ({
    ...bookAdapter.getState(),
    favorite: undefined as Book | undefined,
  }))
);

Note:
We are casting here, because if we don't then TS won't infer this as Book | undefined. We could also use the generic parameter in create for this, and extend our state from EntityState.

Likewise, we need to update our actions to:

export const bookActions = {
  ...bookAdapter.getActions(useBookStore.setState),
  setFavorite(favorite: Book) {
    useBookStore.setState({ favorite });
  },
  resetFavorite() {
    useBookStore.setState({ favorite: undefined });
  },
};

And that's all! We have all what we need to show what is our favorite book.

Updating the components

To allow users to select their favorite book, we only need a small update to the BookItem component.


const { setFavorite } = bookActions;

export const BookItem: FC<BookItemProps> = ({ book }) => {
  ...
  return (
    ... 
        // input
        <button type="button" onClick={() => setFavorite(book)}>
          ❤️
        </button>
        // reset button
    ...
  );
}

To show the favorite book, we do a small update on the BookList component.

...
const { resetFavorite } = bookActions;
...

export const BookList: FC = () => {
  ...
  const favoriteBook = useBookStore((state) => state.favorite);

  ...

  return (
    <> // opening fragment
      {favoriteBook && (
        <div>
          Favorite book is: {favoriteBook.title}{' '}
          <button onClick={resetFavorite}>💔</button>
        </div>
      )}
    // rest of the list
    ...
  );
};

With that, you'll be able to select a favorite book!

Check out what you have done!

Here is a link to the StackBlitz project of this example and you can also check it out in the embed view.

That's all folks!

Thank you! I hope this can be something you find useful, let me know in the comments what you think about this approach. I'm using this series as a showcase for a formal proposal for this to be introduced in Zustand, and here is the link to the discussion, feel free to send your feedback in the repo as well.

Image generated with Microsoft Designer AI A bear looking for a book on a shelf, in a living room with a sofa and firewood, with a 16 bits palette

One more thing!

While this example is simple enough, there is a feature on the EntityAdapter that this implementation is missing, and that is sorting. I didn't want to include it here, because it adds another layer of complexity I didn't want to bring.

Lucky you, I have an implementation in StackBlitz with sorting and additional features. This is the same implementation used in the proposal discussion, you will find more information about it there.

Here is the link to the Zustand Discussion of the proposal

Here is a link to the StackBlitz project of the proposal implementation and you can also check it out in the embed view.

Zustand EntityAdapter - An EntityAdapter example for Zustand

Michael De Abreu — Mon, 11 Mar 2024 12:25:25 +0000

Hi there! Recently, I came across this amazing library to manage states in React, called Zustand. This library allows you to create simple stores that can be consumed inside the components like a hook. It's simple to learn and use but also very powerful.

What's Zustand?

Zustand is a state library with a Flux-like API. It gave me vibes of what a Service is for Angular's state management, a simple solution to share state between components. It's like creating a Redux store, with zero boilerplate code, that can be accessed anywhere and it doesn't require to configure a central state manager.

The example Zustand has in its introduction page does nothing but show what simple, yet useful it is:

// useBearStore.ts
import { create } from 'zustand'

export const useBearStore = create((set) => ({
  bears: 0,
  increasePopulation: () => set((state) => ({ bears: state.bears + 1 })),
  removeAllBears: () => set({ bears: 0 }),
  updateBears: (newBears) => set({ bears: newBears }),
}))

// BearCounter.tsx
import { useBearStore } from '..../useBearStore' // This can be anywhere;

export function BearCounter() {
  const bears = useBearStore((state) => state.bears)
  return <h1>{bears} around here...</h1>
}

// Controls.tsx
import { useBearStore } from '..../useBearStore' // This can be anywhere;

export function Controls() {
  const increasePopulation = useBearStore((state) => state.increasePopulation)

  return <button onClick={increasePopulation}>one up</button>
}

As you can see, we have defined a store somewhere, and then we can consume that store elsewhere the app. This alone can be very helpful to avoid prop drilling and improve your application-wide state management.

You might notice that when I said it gave me vibes of what a Service is for Angular's state management, I didn't say it lightly, this is as simple as creating a Service when you are using Angular. Even simpler because here we don't need classes or DI configurations, just a hook and that's all.

What is an EntityAdapter?

An EntityAdapter is a function that generates the same set of prebuilt actions and selectors, allowing it to interact with a list of objects sharing the same structure and perform efficient CRUD operations. This concept, originally from the ngrx team, has already been ported to RTK, and I thank both teams for their effort.

If you check them @ngrx/entity and @reduxjs/toolkit both their API is very similar. They both have a createEntityAdapter function that will return an object with a state creator, a bunch of actions, and some selectors.

Why should we create our own EntityAdapter for Zustand?

But if this is already been developed for ngrx and RTK, why can we just use those implementations instead? They were developed to be used with each library, and even if they do the same, they do so differently. That's why we can't use either directly with Zustand. But it allows us to learn more from both, the EntityAdapter functionality, and Zustand.

Let's start!

I want us to focus on what we want from this function, a state creator, a bunch of actions, and some selectors.

The initial state

The state that we want to create will be consistent, and we are going to be using the same shape both libraries are using:

type EntityId = string | number;

interface EntityState<Entity, Id extends string | number = EntityId> {
  ids: Id[];
  entities: Record<Id, Entity>;
}

The simpler function we can create to return this shape is:

function stateFactory<Entity>(): EntityState<Entity> {
  return { ids: [], entities: {} };
}

But they don't do that. Instead, both ngrx and RTK allow for more properties to be added, and at first, I wanted to give this ability to the users, but, I think doing so misses the point of using something as simple as Zustand.

Zustand allows us to create encapsulated state managers, and because of this, instead of having our factory to handle this merging, we can do that merging ourselves when we are creating our store. We can even create another store and have one store to handle the entities and other store to handle any additional state.

So, we finish with the stateFactory. Let's move on to the actions!

Random actions go!

Same as we did with the state, it would be better to identify what would be the same that we would need to express better the actions we want. This is where the libraries start to diverge, while both libraries provide methods to add, set, update, upsert, and delete one or many entities, and other methods to delete and replace all entities, each also provides additional functionality.

ngrx additionally provides a way to map directly through the entities list to update one or many entities.
RTK also provides a signature overload for each method enabling them to be used directly as a reducer case.

After that review, I think the bare minimum methods that we need are to add, set, update, upsert, and delete one or many entities, one to remove them all, and another one to replace them all. We can follow the same logic to handle the difference between add and set, if we try to add one entity, we verify that the entity doesn't exist, and if we set that value, we introduce or replace that entity. A similar difference can be made with update and upsert methods, but consider that update requires an object with an id property and an update property containing the updates, but the upsert needs the whole entity to be passed.

So, we will need something like this:

interface EntityActions<Entity> {
  addOne(entity: Entity): void;
  addMany(entities: Entity[]): void;

  setOne(entity: Entity): void;
  setMany(entities: Entity[]): void;

  updateOne(entity: Entity): void;
  updateMany(entities: Entity[]): void;

  upsertOne(entity: Entity): void;
  upsertMany(entities: Entity[]): void;

  removeMany(entities: Entity[]): void;
  removeOne(entity: Entity): void;

  removeAll(): void;
  setAll(entities: Entity[]): void;
}

Since we are following the Flux pattern, we don't want our actions to return anything, instead, we need to query for what we need from the main store.

To implement those methods in Zustand, we can leverage Zustand's feature that allows us to return just a slice of the state, so we can focus on what we want to interact with, and we can also consider that to update the state in Zustand, our update method needs to call a setState function. Because of this, we will create our methods to accept two parameters, the current state, and the arguments for what we want to do, an entity most of the time. Those methods will return the updated state.

To add an entity, we can do something like this:

const addOne = (state: S, entity: Entity): S => {
  const id = idSelector(entity);

  if (state.ids.includes(id)) {
    return state;
  }


  const entities = {
    ...state.entities,
    [id]: entity,
  };

  const ids = [...state.ids, id];

  return {
    entities,
    ids,
  };
};

We will talk later more about the idSelector and the State type, but for now, the first one is just a function that gets the value of that property's id, and the State type is a type alias for the store state.

So, to add an entity to the collection, we shallow copy the current state merging it with the new entity and its id. Does the user have additional properties in that state? We don't know, and better than that, we don't care, because as I mentioned, Zustand will use this and update the state merging it with any other properties that the user could have.

But we need to call this using the setState function. To use this we can have a method like:

  addOne(entity: Entity) {
    setState(state => addOne(state, entity))
  }

That method has the same signature as the addOne we want to use as our EntityActions. We can also reuse that method to create the "many" one as well, just by reducing the list of the entities.

  addMany(entities) {
    setState((state) => entities.reduce(addOne, state));
  }

To implement the other methods, we can do something like that, we can create one function for each type of operation we want, and use it to implement both alternatives, the single one and the "many" one.

After we do that, we'll have all basic C*UD operators, but to complete the implementation we want, we would be missing two methods, one to replace all entities, and one to remove them all.

Again, we are going to leverage the simplicity of Zustand for this, and when we want to remove all values from the collection, all we have to do is return an empty state.

  removeAll() {
    setState({ ids: [], entities: {} });
  }

Likewise, for our replace all function, we can still use reduce on the entities list we want to add, but instead of passing the state as the initial value as we are doing with the "many" alternatives, we will pass the empty state.

  setAll(entities: Entity[]){ 
    setState(() => entities.reduce(setOne, { ids: [], entities: {} });
  }

Now we have all the actions we need to interact with our application! Awesome! We can create our actionFactory now. This is when we will talk about the idSelector and setState functions, and the State type.

The idSelector is a function we will provide when we create each adapter. The idSelector should have this signature:

type IdSelector<Entity> = (model: Entity) => string | number;

The setState is the Zustand function to set the state. The signature for this one is complex, as the simpler version in Zustand has been deprecated, so we will have to trust the process.
The State type, is a type alias for a EntityState:

type State = EntityState<Entity>;

Considering this, for our actionsFactory we will need the Entity generic, and the setState and the idSelector functions as props.

interface ActionsFactoryProps<Entity extends object> {
  setState: SetState<Entity>;
  idSelector?: IdSelector<Entity>;
}

We'll mark idSelector as optional because we will use a default implementation:

const defaultIdSelector = (entity: any): string | number => entity.id;

With all that, we can create our actionsFactory.

export function actionsFactory<Entity extends object>({
  setState,
  idSelector = defaultIdSelector,
}: ActionFactoryProps<Entity>): EntityActions<Entity> {
  type State = EntityState<Entity>;

  const addOne = (state: State, entity: Entity): State => {
    ...
  }
  ...
  return { 
    addOne(entity: Entity) {
    ...
    }
    ...
 };
}

Unlike the state, I won't be adding the whole factory function for actions, because it's large, and I consider it will create noise in the post. But you can still check the implementation in the linked StackBlitz. Sorry!

Gimme, gimme, gimme... an entity

So far, we have the state and the actions. But, at the end of the day, we need to display that data somewhere, and the best way to handle this is by using selectors. Zustand itself is very unopinionated about the usage of complex selectors, if you want to use memoized selectors, that's on you. But when you use the store, you still need to pass a simple selector function.

Both libraries provide pretty much the same set of selectors, but RTK also provides a selectById selector, that we are going to implement. You need to consider that, because those selectors are going to be used within a Redux-like store, they can memoized them for you.

In our case, what we need is a simple selector function, and we can again leverage Zustand's features to ensure we won't have extra renders.

interface EntitySelectors<
  Entity,
  State extends EntityState<Entity> = EntityState<Entity>
> {
  selectIds(state: State): EntityId[];
  selectEntities(state: State): Dictionary<Entity>;
  selectAll(state: State): Entity[];
  selectTotal(state: State): number;
  selectById(id: EntityId): (state: State) => Entity | undefined;
}

Those are the methods we want to define. Maybe the new thing here is the State extends EntityState<Entity>. We already saw what the EntityState interface is, and what we want to do with this is to allow the user to use another State type, as long as it has the required properties in EntityState. We use a default value, to allow the user to only set the Entity generic type, and we can infer the other generic type.

And readers, it doesn't get any easier than this:

  const selectIds = (state: State) => state.ids;
  const selectEntities = (state: State) => state.entities;
  const selectAll = ({ entities, ids }: State) => ids.map((id) => entities[id]);
  const selectTotal = (state: State) => state.ids.length;
  const selectById = (id: EntityId) => ({ entities }: State) => entities[id];

Five inline functions allow us to get the slice of state that we want.

Be an adapter, my friend

With all the pieces we have, we can already create the adapter function:

type IdSelector<Entity> = (model: Entity) => EntityId;

interface EntityCreatorsProps<Entity extends object> {
  idSelector?: IdSelector<Entity>;
}

export function createEntityAdapter<Entity extends object>({
  idSelector,
}: EntityCreatorsProps<Entity>) {
  return {
    getState() {
      return stateFactory<Entity>();
    },
    getActions(setState: SetState<Entity>) {
      return actionsFactory({ setState, idSelector });
    },
    getSelectors() {
      return selectorsFactory<Entity>();
    },
  };
}

Here we see again our idSelector function, but it's clearer here what it is doing. We have a function, that will be called with an entity, and should return an ID for that entity. We have a default implementation for this, selecting the property id, so we don't have to implement this each time, as long as the default is a valid selector.

And that's it. We have created our version of the EntityAdapter. We are generating our state, our actions, and our selectors. And we have done so, thinking about Zustand first. Funny enough, we are not using any Zustand directly just yet, those are plain JS functions that we are creating!

That's all folks!

We had covered how to implement the main methods and functions we need to recreate our version of the EntityAdaptor for Zustand. In another post, I'm showing you how to use it right here!

Image generated with Microsoft Designer AI using as a prompt "A bear sits on a sofa reading a book in a living room with a firewood, with a 16 bits palette"

How to add Module Federation into your Angular micro-frontend apps

Michael De Abreu — Wed, 18 Oct 2023 09:50:37 +0000

Photo by Arseniy Kapran on Unsplash

Hi there! I am very grateful for the overwhelming reception that my first post in this series got. At first, I thought you would like to know about sharing styles between your apps, or maybe how to integrate the dependencies better, but instead, and by far, the most requested feature was how to add Module Federation into my app. Even some of you are saying that all the work without MF is not updating into a micro-frontend, but into apps that become libraries, and you would be right actually.

Nevertheless, I mentioned Module Federation at the beginning of the article. I pointed out that if you want to start a project with micro-frontend in mind upfront, you should use NX instead of plain Angular, because it has a great system to integrate MF, among other features.

This doesn't mean we can integrate Module Federation with plain Angular, and I think the state we got in my last post is the perfect state to do so.

Knowing our tools 🛠️

For this, we are going to use the @angular-architects/module-federation library. This library has been developed to be integrated with Angular CLI, enabling the Module Federation integration with very little configuration on our end.

Keep in mind that currently, Angular CLI doesn't provide a way to load custom Webpack configuration, so this will update the Angular CLI builder with a custom builder that does allow extending the Webpack config file. You can keep that custom builder or replace it with another if you know how to do it, but I won't talk about it here, so we will trust this library.

What does the library do? 📖

As I mentioned, the library first is going to update our build configuration to allow us to extend the Webpack config file, with a file that we are going to fill to enable the Federation Module using the functions this library provides.

The library also allows us to serve the applications individually, so we can interact with the application normally through the browser, or as a micro-frontend.

There are several alternatives to integrate this library into our apps, including static and dynamic hosting. The library provides schematics to set up both the remote app and the host, but in my tests no matter what you choose, you will need to update some things yourself.

Setting up the Module Federation in the main app 🎤

As I mentioned, we are going to use the library's schematics to initialize the configuration, so, open your terminal at the root of the project, and use the schematics as:

ng add @angular-architects/module-federation --project app-micro --type dynamic-host --port 4200

This will configure the main project, update the Angular CLI config with the new builders, create a manifest file with the information to load the remote entry of our secondary projects, and also, will split our bootstrapping into two files, once for the actual bootstrap, and one to allow Angular CLI to handle the bootstrapping.

This most likely won't affect you, but some schematics (e.g.: @angular/pwa and @angular/material) expect the bootstrapping process to happen in the main.ts file. If you want to add one of these libraries you can temporarily disable this.
ng g @angular-architects/module-federation:boot-async false -- project {{ YOUR MAIN PROJECT }}

ng add {{ your-libraries-of-chioce }} --project yourProject

ng g @angular-architects/module-federation:boot-async true -- project {{ YOUR MAIN PROJECT }}

If you check the changes, the manifest file mf.manifest.json expects a file to be served in port 4200, but that's the port we use for the main app. Additionally, if you check the app-routing.module.ts file, you can see that we are loading the secondary app as a library, just as we did before this change. So, after the schematic has run, we still going to need to do some updates in our code.

First, open the manifest file and update the port accordingly. In this case, we are going to set up the secondary app with the port 4201, so you should end up with something like this:

{
  "login": "http://localhost:4201/remoteEntry.js"
}

For this example, we are keeping things simple, by having this information statically in a JSON file, but in a real-life application, this should be served dynamically, replacing the JSON with a prod version, or you can set up an endpoint in your server returning the manifest configuration. If you choose the latter, you should update the main.ts, to change the URL that the initFederation function is using to get the information. Keep in mind that if you configure it this way, the application won't be able to load at all if there is no internet connection, but if you set up a static replace, you can handle the connection error in case your app has been cached previously.

After we have updated the manifest file accordingly, we'll need to use the manifest file in our routing configuration to load the secondary app. Open the app-rounting.module.ts file, remove the import('@@login') code, and replace it with a call of the loadRemoteModule function (import the function from the @angular-architects/module-federation module). You need to pass a configuration object to the function, and we are going to use this one:

{
  type: 'manifest',
  remoteName: 'login',
  exposedModule: './Module',
}

type: The type of remote configuration we are using. In this case, we are using 'manifest' as we are loading the configuration with a manifest file, but you could load the module directly.
remoteName: The name of the module that we are going to load, as it is being declared as the key in the manifest file.
exposedModule: The route of the module we are loading. This is the only thing that's defined in the secondary app.

All of this is configurable, but these are the values we are going to use in this example.

You should end up with something like this:

...
const routes: Routes = [
... 
  {
    path: '',
    canMatch: [isNotLogged],
    loadChildren: () =>
      loadRemoteModule({ type: 'manifest', remoteName: 'login', exposedModule: './Module' }).then(
        (m) => m.LoginModule,
      ),
  },
...

With all this, we would have configured the main app to be able to load the other apps through a remote configuration. Now we need to configure the secondary apps we want to be loaded this way.

Configuring the secondary apps remote config ⏏️

Just as we did with the main app, we are going to use the schematics that are provided with the package. In this case, instead of using --type dynamic-host, we are going to use --type remote instead.

ng add @angular-architects/module-federation --project login --type remote --port 4201

And, just as this did with the main app, it will update several parts of the project, but it won't create a manifest file, and if you check the webpack.config.js file, you can see it has more content than the one that the main app is using

Specifically, it has an exposes property, with an object configuration, with a key that looks like a route and a value that looks like another route. If you remember earlier, when we were configuring the route, we used the exposedModule property, with a value that looks like a route.

The exposes property configures how and what should the module expose to the loader, and with the exposedModule property we access that configuration to load what we need. However, you can notice that we currently are trying to load a './Module' in the route configuration, but this Webpack configuration doesn't have that property.

We need to update that. Remove the './Component' key, and add the './Module' key with a relative path to load the app module. It should look like this now:

...
  exposes: {
    './Module': './projects/login/src/app/feature/login/login.module.ts',
  },
...

That's all the update we need to do in the secondary app.

Running it 🎭

Now, let's test this.

First, run only the main app

ng serve

If you try to access the application, because we are not serving our login app, the load of that module is going to fail, and the application is going to go directly to our dashboard. (Yes, very secure). After verifying that the login part is not loading, we serve the login app.

ng serve login

Now, that we have served the login app, we need to refresh the main application to watch the changes. You will see our login app being correctly mounted into our main app.

Additionally, if you open the browser with the localhost:4201 you will see the login app running independently.

What's next? 🔮

After this, we could improve the build configuration, as currently, we are using the shareAll function of the '@angular-architects/module-federation/webpack package to share all the dependencies. However, we should only share the dependencies we really need to share, using the share function, and configuring each library as needed.

That's all folks! 🐇

We have successfully served our application using the Module Federation feature. I know this took longer than expected, but some exciting things happened in my life, and I needed some time to adjust myself.

I really hope you enjoyed this, and I hope I can write more about this topic, so just as before, what do you think I should talk about next? I was thinking maybe we could integrate two different apps within a shell-like app, so instead of moving from one big app to several micro apps, move from several apps and integrate them with a micro app. But let me know in the comments what you think.

Learning Angular's Signal by creating a query helper

Michael De Abreu — Fri, 06 Oct 2023 13:24:04 +0000

Photo by Toa Heftiba on Unsplash

I know you have been waiting for the follow-up of my guide to migrate an Angular app to a micro-frontend, but you would have to wait a little longer. As you may know, or maybe not, Angular is updating its change detection model with a reactivity approach, using a new feature called Signal.

What is a Signal?

A signal is a new way to declare and manage states. Until now, to create a state in a component, we usually just create a property and update the property when we need to. This was a good feature for Angular back in the day, but to implement that feature Angular had to use some other features such as the infamous Zone.js. Zone.js was a great idea, just monkey-patch every possible event emitter, and then listen to them and update the UI by checking what was changed, or what should be changed. I won't talk deeply about how the current model of Angular works, but that's mostly it.

Now, you can think of Signals, like a React hook. They are both internal functions that allow us to keep track of an internal state and react to updates, and with features to update the state when we want. By using Signal instead of plain properties, Angular can now track and update only the values of the Signals that have been updated, without the need to listen to every event in the DOM. This will allow zone-less applications, among other features.

How can you use a Signal?

Signals are officially in developer preview and are available in the latest version of Angular, Angular 16. With the next version of Angular, additional features will be enabled for developers, such as Signal-only components, that will use inputs based on signals to work, and zone-less applications. We can talk about those features once they become widely available, but right now, we can play with the signal function.

To use and update a signal, we need to import the signal function from @angular/core, call the function with an initial value, and assign it to a property in a component. With that, if we want to update the value, we can use the methods of the signal to do so.

import { Component, signal } from "@angular/core";

@Component({
  selector: "app-root",
  template: `
    <h1>{{ title() }}</h1>
    <button (click)="title.set('Updated title')">Update title</button>
  `,
})
export class AppComponent {
  title = signal("Some title");
}

That's it. It's really simple, more explicit, and internally it will allow Angular to perform better.

But we usually don't have a setup this simple, right? That's why we are going to build a function that helps us to query.

The query helper

What do we need when we query for something? Most of the time, we care about the data, some kind of status like if the query is loading, or if it had an error.

What would a helper need to work? Well, the query function. That should be it, at least that I think is the minimum, and that's what we are going to do here.

So, let's start by creating a function that stores the query value once it has been completed:

import { signal } from "@angular/core";

export const querySignal = (queryFn: Function) => {
  const internalData = signal(void 0);

  const fetch = async () => {
    try {
      let response = await queryFn();
      internalData.set(response);
    } catch (e: any) {}
  };

  fetch();

  return internalData.asReadonly();
};

We are returning internalData.asReadonly() because this will return a new read-only signal that will prevent undesired external updates to the query data.

And then, we can use the helper as:

import { effect, Component } from "@angular/core";

@Component({
  selector: "app-root",
  template: `
    <pre>
    {{ users() | json }}
  </pre
    >
  `,
})
export class AppComponent {
  users = querySignal(() =>
    fetch(`https://fakerapi.it/api/v1/persons`)
      .then((response) => {
        if (!response.ok) {
          throw new Error(`HTTP error, status = ${response.status}`);
        }
        return response.json();
      })
      .then((res) => res.data as any[])
  );
}

Of course, you could use a service to handle the query, but the important part here is that we are using plain promises, instead of Observables.

Moving forward, we will use a PersonService, with a getAll method and assume the code returns a promise.

You may notice that we are not using typings for this, and because of that "users" is typed as Signal<any>. We can fix that by using generics. Now, since we have our helper already working, maybe we could add some features, such as a state to know if the query had any errors, or if it is still loading, etc. Let's update our query helper.

First, let's add the generic typing so we can leverage of TS type system. Let's add the Data generic type, and also, let's create a QueryFn type to handle the type of the query function instead of using the Function type ourselves.

import { signal, Signal } from "@angular/core";

export const querySignal = <
  Data,
  QueryFn extends (...args: unknown[]) => Data | Promise<Data>
>(
  queryFn: QueryFn
): Signal<Data | undefined> => {
  const internalData = signal<Data | undefined>(void 0);

  const fetch = async () => {
    try {
      let response = await queryFn();
      internalData.set(response);
    } catch (e: any) {}
  };

  fetch();

  return internalData.asReadonly();
};

With this, we can update our component as:

import { effect, Component } from "@angular/core";

@Component({
  selector: "app-root",
  template: `
    <pre>
    {{ users() | json }}
  </pre
    >
  `,
})
export class AppComponent {
  users = querySignal(this.persons.getAll); // Correctly typed as QuerySignal<Person[] | undefined>

  constructor(private readonly persons: PersonService) {}
}

We can learn a few things about Signals now that we are here. Notice that we are calling directly the internal fetch function in the QuerySignal. This is fine, since our persons.getAll method doesn't have any argument dependencies, but don't you agree it would be awesome if we could trigger this automatically each time we update one of the arguments? Well, we can use effect to achieve just that. First, we need to update our code service with an argument, then we update the code of the query helper, then we update our component to implement those changes.

import { Injectable } from "@angular/core";

@Injectable({
  providedIn: "root",
})
export class PersonsService {
  constructor() {}

  public async getAll(quantity: number): Promise<Person[]> {
    const response = await fetch(
      `https://fakerapi.it/api/v1/persons?_quantity=${quantity}`
    );
    if (!response.ok) {
      throw new Error(`HTTP error, status = ${response.status}`);
    }
    const res = await response.json();

    return res.data;
  }
}

import { effect, signal, Signal } from "@angular/core";

export const querySignal = <
  Data,
  QueryFn extends (...args: any[]) => Data | Promise<Data>
>(
  queryFn: QueryFn,
  queryParams: Parameters<QueryFn>
): Signal<Data | undefined> => {
  const internalData = signal<Data | undefined>(void 0);

  const fetch = async (params: Parameters<QueryFn>) => {
    try {
      let response = await queryFn(...params);
      internalData.set(response);
    } catch (e: any) {}
  };

  effect(() => {
    fetch(queryParams);
  });

  return internalData.asReadonly();
};

import { Component, signal } from "@angular/core";
import { querySignal } from "./query-signal";
import { PersonsService } from "./persons.service";

@Component({
  selector: "app-root",
  template: `
    <button (click)="quantity.set(10)">10 users</button>
    <button (click)="quantity.set(20)">20 users</button>

    <pre>{{ users() | json }}</pre>
  `,
})
export class AppComponent {
  title = signal("query-signal-app");
  quantity = signal(10);

  users = querySignal(this.persons.getAll, [this.quantity()]);

  constructor(private readonly persons: PersonsService) {}
}

If we use this code as it is, you will soon find out that it doesn't update the query when we click on the buttons. That's because we are passing the quantity directly as a value, and to be able for Angular to pick up the changes, we need to call a signal inside the effect callback function and to call a signal, we need to pass a signal. We will keep it simple from now and use some type helpers as we did to extract the argument types to do the type checking. Additionally, we will be using the compute function to create a new signal with the value of the arguments that we need.

import { effect, signal, Signal } from "@angular/core";

export const querySignal = <
  Data,
  QueryFn extends (...args: any[]) => Data | Promise<Data>
>(
  queryFn: QueryFn,
  queryParams: Signal<Readonly<Parameters<QueryFn>>>
): Signal<Data | undefined> => {
  const internalData = signal<Data | undefined>(void 0);

  const fetch = async (params: Readonly<Parameters<QueryFn>>) => {
    try {
      let response = await queryFn(...params);
      internalData.set(response);
    } catch (e: any) {}
  };

  effect(() => {
    fetch(queryParams());
  });

  return internalData.asReadonly();
};

import { Component, computed, signal } from "@angular/core";
import { querySignal } from "query-signal";
import { PersonsService } from "./persons.service";

@Component({
  selector: "app-root",
  template: `
    <button (click)="quantity.set(10)">10 users</button>
    <button (click)="quantity.set(20)">20 users</button>

    <pre>{{ users() | json }}</pre>
  `,
})
export class AppComponent {
  title = signal("query-signal-app");
  quantity = signal(10);
  getAllParams = computed(() => [this.quantity()] as const);

  users = querySignal(this.persons.getAll, this.getAllParams);

  constructor(private readonly persons: PersonsService) {}
}

effect and compute are two functions that will help us to react to signal changes.

The effect function is called with a callback function, that will run each time one or more signals used inside are updated.

The compute is also called with a callback function but will help you to get a derivate value from other signals, updating itself each time any of the signals has been updated. It returns a signal storing the returning value of the function callback.

After this, you will notice that once you go between the two buttons, you will get the list refreshed.

Wrapping up!

You can see some of this code in action below, although I have to say I'm using Bootstrap here to demo, and additionally, it's using some features that I didn't explain here, which you can use in the library @barelyshaped/query-signal.

So long Observables, I won't miss you

Until now, all we had to manage states were observables, and because of this, all we did was use and misuse them for everything. And if you had enough of them, you know how painful it could be to detect and fix an issue, and don't you dare to say to me "You should use marble testing instead", just don't. Observables are difficult to reason, test, and understand. Promises are plain, just "do something, and then...". I won't argue though, that Observables have their benefits, of course, but in my experience, most people using Observables don't understand them enough to use those benefits, and because of that we end up with overly complicated code that it's not using any of the benefits.

Maybe some Angular developers with more experience will think they will miss something by losing Observables, but we won't. Observables were a nice feature, same as Zone, decorators, and even modules. But web development has moved away from those features, and Angular has been updated with that movement.

Forem: Michael De Abreu

5-Operators and Composition in Our System - Building a Reactive System in TypeScript

Defining an operator

Coding our first operator

The filter operator

Composing with pipe

Other operators

Debounce

Merge

MapAsync

One more thing...

That's all, folks!

4-Optimizing and Refactoring the Code - Building a Reactive System in TypeScript

Improving the development experience

Refactoring the listeners

Refactoring the state

Creating the effect

Optimizing and Extending the System

What's next?

3-Getting derivated values reactively - Building a Reactive System in TypeScript

Getting derivated values reactively

Defining computed values and how they work

Coding the computed function

Replacing the Dependency List with Auto-Tracking

Adding Auto-Tracking for Computed Values

Wrapping It Up

1-Introduction to Reactivity - Building a Reactive System in Typescript

Functional Programming and State Management

Immutable State and Functional Programming

What is Reactive Programming?

How Reactivity Aligns with Functional Programming

The Rise of Signals in Modern JavaScript

What Comes Next?

2-Writing a Signal - Building a Reactive System in Typescript

Defining a Signal

Coding the Signal

Why Create Another Signal Library?

Defining an Event, and how it can be integrated with the state

Coding the Event

Updating the state

Wrapping It Up

Introducing zustand-entity-adapter

What is zustand-entity-adapter?

How to use zustand-entity-adapter?

createEntityAdapter

getActions

getSelectors

getState

That's all folks!

Angular CLI is getting better

Server-side Routing Configuration

Environment variables-ish

That's all folks!

How to add Jest into your Vite project with TS

Let's get started!

Creating the Jest Config file

Extra: Adding Path mapping support for Vite

That's all future me!

Zustand EntityAdapter - A bookshelf example

Creating the store

Interface

bookAdapter

useBookStore

Let's create our components

BookList

BookItem

AddBook

Putting it all together

Adding a favorite book

Extending the store

Updating the components

Check out what you have done!

That's all folks!

One more thing!

Zustand EntityAdapter - An EntityAdapter example for Zustand

What's Zustand?

What is an EntityAdapter?

Why should we create our own EntityAdapter for Zustand?

Let's start!

The initial state

Composing with `pipe`

`createEntityAdapter`

`getActions`

`getSelectors`

`getState`