DEV Community: Alex Bespoyasov

Explicit Software Design. Preliminary Conclusions

Alex Bespoyasov — Mon, 18 Sep 2023 09:00:00 +0000

I planned this series as a playground for various methods of software development and design, using a single application as an example.

The original content plan was much broader: I wanted to add the server side, discuss distributed systems, talk about error handling and its functional alternative, delve deeper into DDD principles through examples, and explore the topic of type safety in functional code.

However, once I started working on it, I realized that it would be impossible to fit everything into one series all at once—there's just too much material. I was afraid I might give up halfway and not publish a single post.

Instead, I decided to package the first batch of posts in this series as a “foundation” that can be later used to dive into other topics in more detail. I am currently planning to take a break and, perhaps, return to this series in the future.

As a conclusion though, I think it would be useful to look at the code we managed to write while working on the application and discuss it.

By the way, all the source code for this series is available on GitHub. Give these repo a star if you like the series!

Created Application Analysis

For a simple converter, this whole carnival of principles and constraints is superfluous. At the beginning of the series, we agreed to not pay attention to this, but now I want to remind you of it.

The complexity of the project structure and application composition increases the maintenance costs. If the application does not contain complex logic, the extra structural complexity will only be a problem.

In general, any new tool should bring more benefits than constraints and costs. This heuristic will remind itself throughout this article.

However, we can still draw some conclusions about the benefits and issues of the ideas we tested in the previous posts.

Features Slices Seem Beneficial

Dividing the application functionality “by features” seems useful even in small applications.

Feature slices show “clusters” of semantically related functionality and define boundaries between them. This helps in breaking down large tasks, managing code complexity, and giving the reader at any given moment only necessary information.

Boundaries between features help to keep coupling between modules under control. By the way, we don’t have to physically build adapters between features; it’s enough to remember or document the place of their interaction to see how the coupling is growing.

Control over coupling gives a chance to react if different parts of the code start to know too much about each other’s internals.

Lastly, feature slices help to design each feature and manage its complexity independently from others. We can choose and use only the tools that are suitable for a specific task, without having to choose them for the entire application at once.

Trade-Offs Everywhere

Every decision carries benefits and costs. Design is an attempt to find a balance between meeting requirements, low costs, and high benefits. This is an ongoing process, and it doesn't end after the release of the first version of the application.

Priorities and weights of costs and benefits will change depending on the project's situation. For fixing a bug in production, for example, you can disregard code cleanliness and fix it later. On the other hand, when implementing a new feature or cleaning up technical debt, the priorities might not be so apparent.

Additionally, the same solution in different projects can lead to different outcomes, so analyzing benefits and costs is necessary, even if we use common architectural patterns to solve problems.

In general, there is no silver bullet; you will have to think a lot in any case

...Therefore, simply “taking one principle and using it everywhere” won’t work. Extracting a domain model in a CRUD application is hardly justified, and splitting the code of a simple form in an online store into layers is probably excessive.

“Almost, but not Quite”

JavaScript (and consequently TypeScript) is a multi-paradigm language. It allows the use of different tools to solve problems, but somewhat “half-heartedly”.

For true™ functional programming in JS, native pattern matching and partial function application are missing (at least for now: 1, 2). For proper OOP, it lacks real interfaces and compile-time dependency injection.

As a result, you can use either of them, but none will be convenient

The problem can be solved with additional libraries and constraints, using linters and third-party tools, but this increases maintenance costs and sometimes makes the code less resilient to changes.

Constant Battle with Entropy

The multi-paradigm nature also leads to problems with “non-standard solutions”.

For example, I’m not sure that the idea of “explicit composition” will be appealing to a significant number of developers. Such a way to compose modules looks weird, unfamiliar, and “non-standard”.

Even if hypothetically a non-standard idea can bring a lot of benefits, its “non-mainstream” and “strangeness” can easily overshadow it. Tools and ideas are developed by the community, and if an idea doesn't go mainstream, there will be problems with its development and support.

This is neither good nor bad; it's just is how it works. But whether to fight it and swim against the mainstream, advocating some ideas, is... well 🤷

Excessive Purism Costs Money

In some previous posts, I emphasized how you can “cut corners” when using one concept or another.

For many of the solutions shown, you can distinguish “degrees” of their strictness. The stricter the implementation of an idea, the closer it is to the “standard”* and the more costly it is. Conversely, the looser the implementation, the easier it is to use, but the further it is from the original concept.

The word “standard” is in quotes because all the solutions shown by me are just my interpretation, and it’s not necessarily a correct one.

In many cases, “freedom in implementation” has little effect on benefits but can reduce its costs. (As, for example, direct imports of hooks used as DI.)

You'll have to keep all this balance in mind when deciding how to write code. Striving for pure and strict implementation just for the sake of pure and strict implementation can be a useful exercise, but it is not always profitable. Excessive purism takes development resources and can be costly.

Using tools blindly is dangerous. It is easy to add layers of abstraction and indirection, but if it doesn’t bring any tangible benefits, they will only harm, raising maintenance costs and the barrier to entry for the project.

When It Might Be Useful

I can see several situations where the described development approach could be useful.

Experiments with Code

If you want to get hands-on experience with ideas and principles to understand the problems they solve, it makes sense to do so. Experiments will help you evaluate ideas and form your own opinion about them.

Doing this through books, posts, or learning materials might be difficult because they are often biased by the authors' experience and project their attitudes towards development, design, or problem-solving.

Legacy Code Exploration

Trying to break down a complex system with code written before your time into explicit parts and describing their interactions simplifies the exploration and understanding of the system. Bounded contexts and explicit composition can help with this.

You don't even have to commit the results of the exploration to the project repository; doing this locally to understand the structure of module interactions and then rolling back the result is enough. The actual changes in code after this can greatly vary in the “strictness” of implementation and can be much simpler.

Long-Living Side Projects

By long-living projects, I mean those that last longer than 5-7 years. By side projects, I mean those that don't have significant resources for daily maintenance and which developers return to sporadically or systematically, but rarely.

For such projects, explicit design can help with two things:

Document more knowledge about the project and describe it in code or as close to it as possible.
Make the project more resilient to external changes, like chaotic updates of libraries or tools.

A ubiquitous language and explicit description of processes in code help to get into the context of a task faster after a long break. An explicit structure, dependency direction, and buffer zones can help limit the spread of changes in code when updating tools or infrastructure.

Again, the patterns of using a particular tool will depend heavily on the balance of benefits and costs, but secondary and tertiary tools can be isolated so that their maintenance or replacement does not consume many resources.

Framework Supports the Idea

If the project is built on a framework that supports the described principles, facilitates their implementation, and reduces friction when following them, the balance of benefits and costs may change. With the presence of “guidelines” within the framework, it is easier to follow the rules, which reduces costs.

When It's Harmful

Besides cases when the described approach can be useful, there are also situations when its use would be more harmful than helpful.

Project Doesn't Need It

By “doesn't need it” various things can be implied:

The application is small or doesn’t contain complex logic;
The team doesn’t see any benefits in these rules, and they slow down their work;
The cost-benefit ratio doesn’t favor the approach;
The already accepted coding rules partially or completely contradict the approach.

In all cases, the solutions will be different: don’t use the approach at all, use it partially, use only ideas but not the implementation, and of course—communicate, communicate, communicate.

Any approach, methodology, idea is a tool for achieving a certain goal. If the tool doesn't help to achieve it, there's no need to use it.

Prototypes and Simple Applications

If the project doesn’t require long-term support, obsessing over cleanliness and strictness is costly and pointless. The same applies to simple applications, where additional structure only complicates it without any benefit.

Resources Already Allocated

One of the ideas described is the isolation of tools and features from each other. If the project has enough resources for rhythmic updating of dependencies, tools, and infrastructure, tool isolation might not be needed.

Direct coupling to a tool might sometimes save more time in daily use than what would be needed to rewrite code when changing the tool or updating its version. (Which might not even occur).

Approach Contradicts Accepted Rules

If a project uses a framework or set of rules that don’t support new ideas, it might be more beneficial to not use them.

Trying to combine incompatible elements requires a large amount of not only development resources but also management and communication. The risk of failure is high, which can result in unmaintainable code that neither takes advantage of the framework nor the new ideas.

A failed attempt will waste resources, frustrate the development team, and have a negative impact on the project as a whole.

Benefits Smaller Than Costs

Ultimately, it all boils down to the cost-benefit ratio. We already mentioned this before, so I’ll just reiterate:

If the tool doesn’t provide benefits, it’s not worth using it

Excess abstractions, indirection, implicitness, and so on are only useful when their benefits greatly outweigh the costs of using them. Otherwise, we get a tool that is difficult to use, the benefits of which are not noticeable, and most likely sooner or later it will be abandoned.

Real-Life Examples

To the question “Have I used something similar in real projects?” I usually give Tzlvt as an example. It’s a finance management app that I made back in 2015. It has undergone several rewrites and has generally been the main testing ground for new ideas.

This app is a prime example of when a project has a long lifespan, but no resources for working on it or maintaining it.

In Tzlvt, I use the ideas of tool isolation. They help to not abandon the project completely because maintenance doesn’t require a lot of resources. In it, I also began to try out the ideas of explicit composition to simplify testing and reduce the number of dependencies.

I tried some of the described ideas in other projects as well. The impression was mixed, so let me repeat the disclaimer:

This is not a recommendation on how to write code

It's rather a buffet of ideas and my opinions about them. Don't take my word for it, try everything in a sandbox, and form your own opinion 🙃

Future Posts?

I have several ideas for future posts that would expand this series. So far, the plans include topics such as:

Applicability of the approach with frameworks like Next or SvelteKit.
A more detailed dive into functional DDD.
Type safety and type branding.
Code-splitting, routing, and performance with React 18.
Error handling in a functional style.
Use with other JS libraries.

If you have ideas that could complement this list, create an issue in the project repository. I’d be happy to discuss! 👋

Sources and References

Links to books, articles, and other materials I mentioned in this post.

Source code for all the steps in this series

From My Blog and Projects

Other Resources

P.S. This post was originally published at bespoyasov.me. Subscribe to my blog to read posts like this earlier!

Explicit Design, Part 9. Decoupling Features with Events

Alex Bespoyasov — Mon, 11 Sep 2023 09:30:00 +0000

Last time, we created a new feature and implemented it, exploring how to develop and refine various modules with different levels of depth depending on the requirements.

In this post, we will discuss how to make application slices more independent using events and when it may be justified.

But first, disclaimer

This is not a recommendation on how to write or not write code. I am not aiming to “show the correct way of coding” because everything depends on the specific project and its goals.

My goal in this series is to try to apply the principles from various books in a (fairly over-engineered) frontend application to understand where the scope of their applicability ends, how useful they are, and whether they pay off. You can read more about my motivation in the introduction.

Take the code examples in this series sceptically, not as a direct development guide, but as a source of ideas that may be useful to you.

By the way, all the source code for this series is available on GitHub. Give these repo a star if you like the series!

Vertical Slices Reviewed

Earlier, we mentioned that slices in the application help to scope bounded contexts and represent features as independent parts of the application.

For small applications, the benefits of such separation may not be particularly noticeable and may not outweigh the costs of “slicing” the app. However, for larger projects, this can be useful, especially for micro frontends, where each feature can be a separate application written in a different technology stack.

Of course, it is possible to link features through direct calls in micro frontends, but this greatly limits the freedom of development and undermines the meaning of micro frontends. (Teams will have to synchronize work and wait for each other to publish significant changes in the project.)

Instead of direct calls in such projects, it is more convenient to organize communication between features through events.

Coupling via Adapters

Last time, we connected features to each other through an adapter for the converter. In simple cases, this may be enough, but let's agree that our application is going to grow.

If, in addition to notes, the converter needs to notify other features about refreshed rates, the number of adapters can increase uncontrollably:

Each of the signals to other features is a point of coupling and a potential failure point. If we want to avoid direct coupling between features, we should not “notify each” feature by hand, but “send a signal” to the outside world that the rates have been updated. Following this principle, in response to this event, other features will decide for themselves which of them and how to react to this event.

In the second case, the point of contact between the use case and the external world is only one, and no matter how many other reactions to this event we need to add, we will add them separately “somewhere outside”. This way of organizing is sometimes called event-driven, and the place where events are sent is called an message bus.

Message Bus

Let's try to apply the idea of a message bus to our application. Instead of directly calling another feature, the converter will publish an event indicating that the rates have been updated and pass the values of these rates:

// core/ports.output
type PublishRefreshed = (rates: ExchangeRates) => void;

These messages will be sent to a “hub”, which will forward these messages to all interested parts of the application. “Interest” will be expressed by modules subscribing to specific events that they need to process. We will call this “hub” a message bus.

Message bus, message queue, message broker, pub-sub model—each term has its own distinctive features, and in some aspects, they intersect. We won't go into detail about the differences between them, but I will leave useful links on the topic.

Our bus will provide 3 interfaces: for publishing events, subscribing to them, and unsubscribing. These interfaces will be shared among all modules, so we will place them in the Shared Kernel:

// shared/kernel

export type PublishEvent = (event: InternalEvent, data: EventPayload) => void;
export type SubscribeTo = (event: InternalEvent, handler: EventHandler) => void;
export type Unsubscribe = (event: InternalEvent, handler: EventHandler) => void;

Also, in the Shared Kernel, we will describe the types of events that can occur in different parts of the application:

// shared/kernel

type ConverterEvent = 'RatesRefreshed';

// Maybe in the future, we'll also have:
// type NotesEvent = "NoteCreated"
// type UserEvent = "SessionExpired"

export type InternalEvent = ConverterEvent; /* | NotesEvent | UserEvent | etc */

We can use Shared Kernel because events (and the bus interface) will be used in different parts of the application anyway. We don't create any “extra” coupling between modules, except for what is necessary for modules to “communicate.” For more information on what Shared Kernel is and why it is used, see this post.

The implementation can vary widely depending on the requirements. For our application, we will take a small library that will do almost everything for us:

// shared/infrastructure/bus

import mitt from 'mitt';

const emitter = mitt<Record<InternalEvent, Optional<string>>>();

export const publishEvent: PublishEvent = emitter.emit;
export const subscribeTo: SubscribeTo = emitter.on;

Generally, the choice of library will strongly depend on requirements and conditions of use. For example, in distributed systems (such as micro frontends), it is important that the message is guaranteed to be delivered to all subscribers, and only once.

In our case, the application is “monolithic,” and delivery will mainly be synchronous, so we can afford a simple in-memory bus.

Decoupling Features

We use our message bus to decouple features. In the use case of the converter, the first thing we do is replace the adapter with event publishing:

// converter/refreshRates

type Dependencies = {
    // ...
    publishRefreshed: PublishRefreshed;
};

export const createRefreshRates =
    ({ publishRefreshed /* ... */ }: Dependencies): RefreshRates =>
    async () => {
        // ...
        publishRefreshed(rates);
    };

Let's rewrite the adapter so that it doesn't call a specific feature, but triggers the publish method on the bus:

// converter/infrastructure/bus

import type { PublishEvent } from '~/shared/kernel';
import type { PublishRefreshed } from '../../core/ports.output';

export const createPublisher =
    (publish: PublishEvent): PublishRefreshed =>
    (rates) => {
        const noteContent = JSON.stringify(rates, null, 2);
        publish('RatesRefreshed', noteContent);
    };

// converter/infrastructure/bus.composition

export const publishRefreshed: PublishRefreshed = createPublisher(publishEvent);

Then, we'll register the publisher:

// converter/refreshRates.composition

import { publishRefreshed } from '../../infrastructure/bus';

export const refreshRates: RefreshRates = withAnalytics(
    createRefreshRates({
        fetchRates,
        readConverter,
        saveConverter,
        publishRefreshed
    })
);

...And update tests:

// converter/refreshRates.test

// ...
const publishRefreshed = vi.fn();
const refreshRates = createRefreshRates({ publishRefreshed /*...*/ });

describe('when called', () => {
    // ...

    it('calls a message bus with the rates refreshed event', async () => {
        await refreshRates();
        expect(publishRefreshed).toHaveBeenCalledWith(rates);
    });
});

At first glance, nothing much has changed, but now, instead of changing the refreshRates use case code to notify the third feature about the update, we can allow the third feature to subscribe to the event itself, if it needs to.

The use case also does not need to know about the format in which other features want to work with the data. The event format is the same throughout the application, so it is enough to publish the event with the necessary data, and each subscriber will decide for itself how to convert this data into the format it needs for its work.

Subscription to Events

Inside the notes feature, we will create a mechanism for subscribing to an event:

// notes/infrastructure/bus

import { subscribeTo, unsubscribeFrom } from '~/shared/infrastructure/bus';
import { createNote } from '../../core/createNote';

const subscribe = () => subscribeTo('RatesRefreshed', createNote);
const unsubscribe = () => unsubscribeFrom('RatesRefreshed', createNote);

In general, this could be a separate use case, but for simplicity we will skip this step. Let's subscribe to the event when the component is mounted, for example:

export const useBus = () => {
    useEffect(() => {
        subscribe();
        return unsubscribe;
    }, []);
};

...And initialize the subscription:

export function Notes() {
    useBus();
    // return ...
}

Using hooks is not necessary again because subscribing to the event bus is not dependent on the framework and generally not dependent on the UI.

But isn't it... Redux? 🤨

The working principle of our message bus is suspiciously similar to Redux. If we don't delve into the details, the mental model almost coincides: events are actions, the bus is the store, subscriptions are well... subscriptions.

The difference here is probably in who initiates the subscription: in Redux, the entry point is the global store, while in our example, features themselves decide when and what to subscribe to. Events only come to those parts of the code that have decided to follow them.

Actions are also slightly different from events. Events describe what has already happened, while actions often say what should happen. But in general, the approaches are indeed similar.

By the way, I have even seen implementations of event buses made with Redux. I wouldn't recommend pulling in the entire RTK just for a pub-sub pattern, as it seems excessive, but if the application is already using Redux, you could, in principle, create a separate store and use it as a “message bus.”

However, not only Redux, but any tool that helps to establish “more or less decoupled” communication between modules is similar to a “message bus.” If you want to, you can reduce to an event-based model even atomic stores or observers.

The essence of the idea is in low coupling and communication through contracts (events, messages, actions, etc.), so “borrowing” ideas from such tools comes naturally 🙃

Events and DDD

In DDD, events play an even more important role. They help coordinate the work of different bounded contexts and serve as the result of business workflows.

In the use case of the converter, we did something similar. We published the RatesRefreshed event based on the results of the user scenario:

Handle Command:       Perform Use Case:        Publish Event:
RefreshButtonClick -> [ FetchRates        ] -> RatesRefreshed
                      [ -> ReadConverter  ]
                      [ -> LookupRate     ]
                      [ -> CalculateQuote ]
                      [ -> SaveConverter  ]

This approach helps to think about workflows in the application as a transformation of commands into events.

DDD in its “canonical” form is not always necessary, but the idea of a proper separation of subdomains, representing processes as sequences of transformations and events, can help in designing an application.

Next Time

In this series, we looked at how to write an application using various principles from books and discussed their benefits and usefulness. In the next post, we will summarize everything we've done, create a list of topics we haven't covered yet, and make a plan for continuing the series some time in the future.

Sources and References

Links to books, articles, and other materials I mentioned in this post.

Source code for the current step on GitHub

Architecture and Micro Frontends

Messaging and Messaging Patterns

DDD and “Dogmatism”

Explicit Design, Part 8. Adding New Feature

Alex Bespoyasov — Mon, 04 Sep 2023 08:10:00 +0000

Let's continue experimenting with explicit software design.

In previous posts, we wrote an application with one feature—a currency converter.

In this post, we will add a new feature, implement it (in a bit simpler way than the previous one 🙃), discuss how to keep the coupling under control, and talk about the benefits of vertical slices.

But first, disclaimer

This is not a recommendation on how to write or not write code. I am not aiming to “show the correct way of coding” because everything depends on the specific project and its goals.

My goal in this series is to try to apply the principles from various books in a (fairly over-engineered) frontend application to understand where the scope of their applicability ends, how useful they are, and whether they pay off. You can read more about my motivation in the introduction.

Take the code examples in this series sceptically, not as a direct development guide, but as a source of ideas that may be useful to you.

By the way, all the source code for this series is available on GitHub. Give these repo a star if you like the series!

Domain Model

Let's say the product owner wants to conduct an experiment and add user notes to the application. We are not sure if this feature will stay in the application, so we want to add a quick solution that can be easily improved in the future if necessary.

To keep this post concise, we will describe only one use case: creating a note. This use case is a CRUD operation, and there is no domain logic involved. The entire process can be reduced to the following data flow:

// Get a string from the UI,
// if the string is valid,
// create a note object from it,
// save the data to the storage.

FormSubmitEvent ->
  ContentString ->
  Note ->
  Persistence

The input port for this use case will be of type CreateNote. It takes a string (potential note content) and starts an asynchronous saving process:

// core/ports.input
type CreateNote = (content: string) => Promise<void>;

We will have only one output port for now, of type PersistNote. It takes the note draft, saves it to the storage, and returns the saved note:

// core/ports.output
type PersistNote = (note: DraftNote) => Promise<SavedNote>;

The note data model will consist of 2 types: a note draft and a saved note. We'll use a union type to make it easier to extend the data model in the future if necessary:

// core/types

type Note = DraftNote | SavedNote;

type DraftNote = { content: LocalizedString };
type SavedNote = { content: LocalizedString; id: EntityId };

We use union types instead of boolean flags so that we can describe the evolution and transformation of data in the code. In addition, distributed types help to make some invalid states unrepresentable.

Also note that the note data should be internally consistent, so we will consider it an aggregate. In a simple case, this will not affect the code, but in the future, it may determine the choice of tools for the task.

Implementing Use Case

This time, we will not use “explicit composition” to implement the use case, but instead try to import modules directly:

// core/createNote
import type { CreateNote } from '../ports.input';
import { persistNote } from '../../infrastructure/persistence';

export const createNote: CreateNote = async (content: string) => {
    const draft = { content };
    await persistNote(draft);
};

Despite the fact that composition is right in this file, we can still ensure that the use case relies primarily on the type, not the specific implementation:

// infrastructure/persistence
import type { PersistNote } from '../../core/ports.output';

// TODO: implement the port.
export const persistNote: PersistNote = async () => {};

To test the use case, we can mock the infrastructure/persistence module and substitute the persistNote function with a spy.

Services and Output Ports

In the storage module, we explicitly indicate that the persistNote function should implement the PersistNote output port. This way, we ensure that services adapt to the application, and not the other way around. (Since composition in this feature is implicit, it is easier to make a mistake with the direction of dependencies, and we want to prevent it.)

Specifying the type in this case serves as a “buffer zone”: if we implement the port incorrectly, the compiler will flag it and prevent the application from being built. With all this in mind, inside the implementation, we can generally rely on libraries and tools directly:

// infrastructure/persistence

import type { NoteCollection } from '../../core/types';
import type { PersistNote } from '../../core/ports.output';

import { nanoid } from 'nanoid';
import { persist, retrieve } from '~/services/persistence';

export const persistNote: PersistNote = async (draft) => {
    // Imagine the ID is assigned
    // by the persistence service:
    const note = { ...draft, id: nanoid() };
    const notes = retrieve<NoteCollection>(persistenceKey) ?? [];

    persist(persistenceKey, [...notes, note]);
    return note;
};

“Decoupling” libraries in the future will not be difficult precisely because of the reliance on types and the correct direction of dependencies.

UI and Input Port

A similar situation will arise with input ports. Components will rely on the CreateNote type, which will be implemented by the createNote function:

import { createNote } from '../../core/createNote';
import { useField } from '~/shared/ui/useField';
import { Input } from '~/shared/ui/Input';

export function NoteForm() {
    const [value, update, clear] = useField('');
    const onSubmit = useCallback(
        (e: FormEvent) => {
            e.preventDefault();
            createNote(value);
            clear();
        },
        [value]
    );

    return (
        <form onSubmit={onSubmit}>
            <label>
                <span>Make a note:</span>
                <Input type="text" value={value} onChange={update} />
            </label>
        </form>
    );
}

The composition is “mixed” with the component code, but ideologically it still “relies on abstraction” and is “sufficiently decoupled” from the application core.

In real projects, we'll probably see code similar to this than the code we wrote in the previous posts because of import convenience and amount of “extra” code. The main idea, however, stays valid: when the application core is fairly decoupled from the UI and infrastructure, the project becomes more versatile.

The level of “purity” and versatility, of course, should be decided for each project specifically and depend on the project and business requirements.

Cross-Cutting Concerns

Suppose we want to add analytics to test a hypothesis. Based on the type of the use case, we can write a decorator that adds the analytics to the use case without interfering with the use case code:

// infrastructure/analytics

import type { CreateNote } from '../../core/ports.input';
import { sendEvent } from '~/services/analytics';

export const withAnalytics =
    (fn: CreateNote): CreateNote =>
    async (content) => {
        sendEvent('NOTE_CREATED', `Content size of: ${content.length}`);
        return await fn(content);
    };

Since the use case composition is located directly in its source code, we can apply the decorator right there:

import { withAnalytics } from '../../infrastructure/analytics';

//                                    ↓ Decorator   ↓ Use Case Function
export const createNote: CreateNote = withAnalytics(async (content: string) => {
    const draft = { content };
    await persistNote(draft);
});

However, we still keep in mind that the decorator depends on the use case, and therefore we can separate them from each other. Conceptually, these two modules are decoupled and both rely on the type of the use case.

For more information on decorators and their composition, refer to our previous post.

Using New Feature

To use the notes feature in our application, we can create a public API for it:

// ui/Notes

export function Notes() {
    return (
        <section>
            <h2 className="visually-hidden">Notes</h2>
            <NoteForm />
        </section>
    );
}

// notes/index

export * from './ui/Notes';

...And add it to the dashboard:

// pages/Dashboard

import { Converter } from '~/features/converter';
import { Notes } from '~/features/notes';

export function Dashboard() {
    return (
        <>
            <Converter />
            <Notes />
        </>
    );
}

In the dashboard component, it is visible how it composes widgets from different features together. This helps to visualize the “bounded contexts” for which each feature is responsible, and avoid their intersection, that is, to divide the entire application into so-called slices.

Vertical Slices

Each feature in our application describes one bounded context. It contains a domain model, code for use cases, input-output ports, and adapters to all the services it needs to work with. Another name for this part of the application is a slice.

The benefit of this architectural style is the independence and self-sufficiency of features. They can be added, removed, and developed independently of each other and with different levels of elaboration.

For a slice, it doesn't matter how other slices work. In one slice, we can write code as cleanly and neatly as possible, while in another slice we can write code as if we were writing a prototype. We can split one slice into layers, while in another we can write all the code in one file.

Since slices are isolated from each other, solutions adopted in the code of one feature may not affect the code of other features. This makes it possible to add complexity in the code as needed. That is, we do not have to think through the “architecture of the entire application” as a whole, choose tools “all at once,” and become hostages to these decisions in the future.

Features may well have different structures, and their complexity may depend on the requirements and complexity of the domain. For a simple CRUD slice, we can write less tidy and simple code, while for a feature with complex business logic, we can outline the domain model, design use cases, and divide the code into layers:

Slices help us keep all the knowledge related to a particular subdomain together, without scattering it throughout the codebase. And isolation enables us to avoid making big decisions for the entire project.

In addition, slices force us to perceive data we work with differently. Since the focus of slices is on a specific part of the domain, we start seeing seemingly identical data through the prism of a specific subdomain. For example, the abstract concept of “price” in the context of procurement may come to mean “price from the supplier,” while in the context of sales, it may mean “the price on the label including shipping.”

This division helps us understand the essence of the data we work with, as well as the differences between “seemingly identical things” in the light of different parts of the domain.

Feature Communication

The main idea of slices is their independence. Features in the application ideally should not know about each other's existence and not affect each other's work.

Proper context allocation and data separation between slices help achieve this. If we notice that we need data from another context, then we most likely divided them incorrectly. (This is especially noticeable if two features change with suspiciously equal frequency and operate with a similar set of data.)

However, for various reasons, full independence not always achievable, and we may need to configure communication between features. We can do this by either directly accessing one feature from another, or by using events.

In this post, we will look at an example of direct communication between features and discuss its pros and cons. In the next post, we will talk about event-driven communication and compare these two approaches.

Direct Communication Example

Let's imagine we have a task to automatically create a new note with fresh exchange rates when updating them. (Yeah, it's kinda far-fetched, but anyway 🤷)

To implement this, we need to “ask” another feature after receiving data from the server to create a new note. For the converter, this operation will be a signal to the “external world”. It is not very important to know exactly where we will send this command.

For the notes feature, such a signal is literally a lever on the input port that will launch the use case.

Such communication between features still increases their coupling because the converter will have to know about the existence of a neighboring feature. But by connecting them through ports, we still allow ourselves to decouple them in the future. (We will talk about this in the next post.)

Coupling via Ports

By coupling features through their ports, we create only one point of contact. This is convenient because it creates consistent expectations about how communication is organized between different parts of the application. We don't have to think about where to look for the connection between different features.

In the case of notes, we already have an input port:

// notes/ports.input

type CreateNote = (content: string) => Promise<void>;

The function that implements this port will be the entry point into the feature, and the code that will call it will run the use case, i.e. act as a “driving adapter”.

As for the converter, we will have to think about how to limit the spread of knowledge about notes and not let it “spread out” throughout the converter. For example, if we place CreateNote directly in the use case dependency, we will couple the core of the converter directly with the external world:

// converter/refreshRates

import type { FetchRates, ReadConverter, SaveConverter } from '../ports.output';
import type { CreateNote } from '~/features/notes/ports.input';
// Direct coupling...            ↑

type Dependencies = {
    fetchRates: FetchRates;
    readConverter: ReadConverter;
    saveConverter: SaveConverter;
    createNote: CreateNote;
};

...However, we would like to avoid this, because such coupling “smudges” the connection points between features, and knowledge about notes begins to spread throughout the converter code.

In addition, this option will encourage us to change the code of the converter when the logic of notes changes:

export const createRefreshRates =
    ({}: /*...*/ Dependencies): RefreshRates =>
    async () => {
        // ...

        // In order to “serialize the note correctly”,
        // we would have to modify the converter code:
        const message = JSON.stringify(rates);
        createNote(message);

        // ...However, how to transform the note's content
        // does not belong to the responsibility of the converter.
    };

To prevent the “spreading out” of knowledge about notes and maintain the independence of the converter use case, we will write an adapter to the notes feature.

Adapter to Feature? 🤨

The word “adapter” may suggest that this pattern is only needed to connect the application to third-party tools or services. But in reality, the task of the adapter is to make one some interface comparable to another some interface.

Both of these interfaces can be feature ports, which we will use. Let's write the CreateNoteAdapter type for the converter. This type will be an output port because its task is to send a signal to the outside world:

// converter/ports.output

type CreateNoteAdapter = (rates: ExchangeRates) => void;

The use case will only need to call the function implementing the CreateNoteAdapter type:

// converter/refreshRates

import type { CreateNoteAdapter /*...*/ } from '../ports.output';

type Dependencies = {
    fetchRates: FetchRates;
    readConverter: ReadConverter;
    saveConverter: SaveConverter;
    createNote: CreateNoteAdapter;
};

export const createRefreshRates =
    ({}: /*...*/ Dependencies): RefreshRates =>
    async () => {
        // ...

        // All the use case has to worry about
        // is calling this function and passing it fresh rates.
        // Everything else, it promises to take care of.
        createNote(rates);
    };

Then, all the knowledge about how to work with notes, what to convert them to, how to serialize them, etc. will be located in the implementation:

// converter/adapters

// The adapter depends only on the output port of the converter
// and the input port of the other feature:
import type { CreateNoteAdapter } from '../../core/ports.output';
import type { CreateNote } from '~/features/notes/core/ports.input';

// Accept one interface, return the other:
type AdaptInterface = (realFeature: CreateNote) => CreateNoteAdapter;

export const createAdapter =
    (callFeature: CreateNote): CreateNoteAdapter =>
    // Return a function that contains all the necessary information
    // to correctly send a signal to the outside world
    // and start the use case in the notes feature:
    (rates) => {
        const noteContent = JSON.stringify(rates, null, 2);
        callFeature(noteContent);
    };

Partially apply the factory function by passing it the actual createNote function that implements the input port for notes:

// adapters/createNote.composition

import { createAdapter } from './createNote';
import { createNote as callFeature } from '~/features/notes/core/createNote';

export const createNote = createAdapter(callFeature);

Now, the only place in the entire use case that is coupled with the code of another feature is the adapter and its composition:

This way, we create a foundation for an even deeper decoupling of features in the future.

Adapter Registration

We now need to register the created adapter in the use case composition and cover it all with tests. Let's update the composition:

// converter/refreshRates.composition

// ...
import { createNote } from '../../adapters/createNote';

export const refreshRates: RefreshRates = withAnalytics(
    createRefreshRates({ createNote /* ...Other dependencies. */ })
);

Then, update the tests composition:

const fetchRates = async () => ({ ...rates });
const readConverter = () => ({ ...converter });
const saveConverter = vi.fn();
const createNote = vi.fn();

const refreshRates = createRefreshRates({
    fetchRates,
    readConverter,
    saveConverter,
    createNote
});

And let's add a new test that verifies that when updating rates, the use case calls the adapter function with the correct arguments:

describe('when called', () => {
    // ...

    it('calls a note creations out of the fresh rates data', async () => {
        await refreshRates();
        expect(createNote).toHaveBeenCalledWith(rates);
    });
});

Next Time

In this post, we created a new feature and implemented it, looking at how we can develop and work on different modules with varying depths depending on the requirements. Additionally, we described the direct interaction between the slices of the application and left room for future improvements to reduce coupling.

In the next post, we will discuss how to make slices even more independent using events and in which cases it can be justified.

Sources and References

Links to books, articles, and other materials I mentioned in this post.

Source code for the current step on GitHub

Isolation, Coupling, and Cohesion

Architecture and Patterns

Vertical Slices

Data States and Transformations

P.S. This post was originally published at bespoyasov.me. Subscribe to my blog to read posts like this earlier!

Explicit Design, Part 7. App Composition without Hooks

Alex Bespoyasov — Mon, 28 Aug 2023 06:00:36 +0000

Let's continue experimenting with explicit software design.

In the previous posts, we've built the converter app from its parts, composed everything with hooks, discussed ways to simplify composition, and talked about various types of testing.

In this post, we'll take a small side road and discuss how to compose an app without hooks, how to inject dependencies “before runtime,” and whether there's any benefit to doing so.

But first, disclaimer

This is not a recommendation on how to write or not write code. I am not aiming to “show the correct way of coding” because everything depends on the specific project and its goals.

My goal in this series is to try to apply the principles from various books in a (fairly over-engineered) frontend application to understand where the scope of their applicability ends, how useful they are, and whether they pay off. You can read more about my motivation in the introduction.

Take the code examples in this series sceptically, not as a direct development guide, but as a source of ideas that may be useful to you.

By the way, all the source code for this series is available on GitHub. Give these repo a star if you like the series!

Problems with Hooks

This post is probably going to be the most subjective in the entire series.

My criticism of hooks is just my opinion, I could be wrong, and I am probably wrong. So before we start writing code, I want to explain the reasons why hooks have recently become less attractive to me as a tool.

High Infectiousness and Multiple Limitations

Hooks infect everything around them. If we decide to use a hook somewhere to solve a particular problem, we have to use them in all other parts of the code that are somehow related to that problem, even if they're not needed there.

Developing with hooks requires making too many decisions too early. We have to deal with low-level implementation details before it becomes really necessary.

In addition, hooks introduce not always justified restrictions, which can suddenly change for weakly substantiated reasons.

The volatile restrictions of a tool decrease trust in it, because it becomes expensive to maintain in the long term. Changing, such tools add extra work and inflate technical debt, consuming resources that could have been saved.

Vendor Lock-In

Hooks tightly bind the project to specific technologies and tools, making it excessively costly to switch them.

This may not be critical for every project, especially if the project is short-lived. But if we are going to write code that will live for 5+ years, we should allocate resources in advance to update the codebase and consider the likelihood of switching to another framework or library.

Implicit Dependencies and Leaking Abstractions

Hooks encourage combining data and behavior. Composing hooks leads to a composition of side effects, which is called one of the main problems of OOP, for example.

Hidden dependencies and the influence of effects on each other are difficult to grasp, making it harder to control program behavior.

By “encouragement” I mean not so much the examples from the documentation as the difference in how easy it is to write code by combining data with behavior versus not doing so. With hooks, the latter is even more difficult on a syntactical level.

Implementation details of hooks are often overly or insufficiently abstracted. A single hook may contain functionality from different abstraction levels, which requires mentally jumping between different levels while reading. This increases cognitive load and clouds the interaction between parts of the application.

For the same reasons, testing hooks can be difficult. Composing effects requires not only preparing input data for the hook but also “recreating its state,” and implicit dependencies require complex testing infrastructure. For example, to test such a hook:

const useUser = () => {
    const { data, isLoading } = useSWR(['/users', id], fetchUser);
    const role = useRoles(data);
    const session = useStore((s) => s.session);
    return { ...data, session, role };
};

For example, to test such a hook, we need to mock fetch (or useSWR), set up a store provider, check what useRoles consists of, so that we can mock it or its dependencies if necessary.

Finally, since the composition of effects and excessive abstraction do not fit in our heads, we may forget to test edge cases: a specific user role, an incorrect server response, data revalidation, overwriting session data from old to new, etc.

As a result, we have to keep in mind not only the code of the hook itself but also many other aspects:

Complicated Mental Model

It is difficult to give a comprehensive definition of hooks, and in my observations, their mental model raises many questions for new developers.

They seem to be similar to functions, but behave differently. Conditions for re-rendering complicate the understanding of how component re-rendering works. The concept of hooks seems to be established, but details and rules can change drastically from version to version.

This, again, reduces confidence in the stability of the API and complicates learning.

Disclaimer

All of this doesn't mean that it's impossible to write good and well-structured code with hooks. It's possible, of course.

I just feel that if a technology imposes restrictions, they should guide developers and make it impossible or at least difficult to write code “incorrectly”. With hooks, however, I get the feeling that they don't provide a clear mental framework for understanding how to write code using them.

For me, hooks are a way of composing different functionality. I think of them as “injectors” of services, functions, and data that trigger component re-renders. If the functionality is not directly related to the UI state or component re-rendering, then I will first consider whether it can be written without using hooks.

By the way, in the new React documentation I found something similar to this idea.

Composition without Hooks

Now that we have aligned our understanding of hooks, let's try to rebuild the converter without using them. Since the application itself is already designed, we can immediately move on to choosing the appropriate tools for the task.

By the way, this section can be an example of why it's better to choose tools later, when you know as much as possible about the project. It's clear that our requirement “to be able to work without hooks” is artificial, but it can be replaced with a more significant requirement that is directly related to the business needs.

The service that requests data from the API doesn't use hooks, so we will leave it unchanged, but we will slightly modify the store. Instead of using context, we will use the Zustand library. It is a state manager that is somewhat similar to Redux, but simpler and doesn't require providers.

Store Service

After installing Zustand in the project, we can describe a basic implementation of the store using it:

// infrastructure/store.ts

export const converter = createStore<Converter>(() => ({
    // ...Default model values.
}));

Next, let's describe the composition, that is, how this service will implement the application ports declared earlier:

// infrastructure/store.composition.ts

// Output ports connect the service
// with the use cases:

export const readConverter: ReadConverter = converter.getState;
export const saveConverter: SaveConverter = converter.setState;

// Input ports will be implemented directly,
// since there's no “domain logic” in the selectors:

export const useBaseValue: SelectBaseValue = () => useStore(converter, (vm) => vm.baseValue);
export const useQuoteCode: SelectQuoteCode = () => useStore(converter, (vm) => vm.quoteCode);
export const useQuoteValue: SelectQuoteValue = () => useStore(converter, (vm) => vm.quoteValue);

We will leave the data selectors unchanged. These are precisely the “reactive data” that should update the UI, so providing them through hooks makes sense.

On the other hand, the implementation of output ports will be used by use cases, which we will implement as functions. Therefore, readConverter and saveConverter will be references to read and write functions, not hooks.

Composition of Use Cases

Let's update the composition of use cases to use readConverter and saveConverter functions directly:

// core/updateBaseValue.composition

// ...
import { readConverter, saveConverter } from '../../infrastructure/store';

export const useUpdateBaseValue: Provider<UpdateBaseValue> = () => {
    return useCallback(
        (value) => updateBaseValue(value, { readConverter, saveConverter }),
        [readConverter, saveConverter]
    );
};

Since the imported functions won't change their references, we can remove the useCallback:

// core/updateBaseValue.composition

import { readConverter, saveConverter } from '../../infrastructure/store';

export const useUpdateBaseValue: Provider<UpdateBaseValue> = () => {
    return (value) => updateBaseValue(value, { readConverter, saveConverter });
};

After that, it will become clear that creating an extra lambda in the hook and passing dependencies to the updateBaseValue function at runtime no longer makes sense. Instead, we will use “bake in” dependencies and prepare the entire use case in advance.

Currently, the code for the updateBaseValue function looks like this:

// core/updateBaseValue

const stub = {} as Dependencies;

export const updateBaseValue: UpdateBaseValue = (
    rawValue,
    { readConverter, saveConverter }: Dependencies = stub
) => {
    // ...
};

We will change the function signature so that it can be partially applied by specifying dependencies. We will extract the dependency argument, put it first, and make the function “curried”:

// core/updateBaseValue

export const createUpdateBaseValue =
    ({ readConverter, saveConverter }: Dependencies): UpdateBaseValue =>
    (rawValue) => {
        // ...
    };

I have covered dependency “baking” in more detail in a previous post about infrastructure. If you're not quite clear on what's happening here, I recommend reading that post first.

Also, technically it's not quite accurate to call this “currying” in JS, but we won't delve into terminology here. Also, the current way to make the function partially applicable is somewhat cumbersome. However, when native partial application is introduced to JS, working with this concept will be slightly easier.

Next, we can partially apply the factory function by passing in the dependency argument and obtain a prepared use case:

// core/updateBaseValue.composition

export const updateBaseValue: UpdateBaseValue = createUpdateBaseValue({
    readConverter,
    saveConverter
});

As we mentioned earlier, partial application is more type-safe than an optional argument with dependencies, so we have less chance of passing the wrong service or forgetting to pass it. And since the real values are substituted only once, such composition should not affect performance.

Composition of Components

Since the use case is now just a function, components can use it directly:

// ui/BaseValueInput

type BaseValueInputDeps = {
    // Using the function directly:
    updateBaseValue: UpdateBaseValue;
    useBaseValue: SelectBaseValue;
};

// In the component itself, we'll remove the `useUpdateBaseValue` call
// and will use the given `updateBaseValue` function directly.

The composition of the component itself will not change significantly:

// ui/BaseValueInput.composition

// ...Import the function:
import { updateBaseValue } from '../../core/updateBaseValue';

export const BaseValueInput = () =>
    // ...Pass it when “registering” the component:
    Component({ updateBaseValue, useBaseValue });

Let's do the same with other components that depend on this use case.

Again, if we don't use explicit composition, it would be enough to import and use the function directly in the component. More details about explicit and implicit composition can be found in one of the previous posts.

Composition of Tests

Since we are not touching the logic, in tests, we only need to update the preparation of stubs and mocks:

// core/updateBaseValue.test

const readConverter = () => ({ ...converter });
const saveConverter = vi.fn();
const updateBaseValue = createUpdateBaseValue({
    readConverter,
    saveConverter
});

// ui/BaseValueInput.test

const updateBaseValue = vi.fn();
const useBaseValue = () => 42;
const dependencies = {
    updateBaseValue,
    useBaseValue
};

The test code and its logic will remain unchanged.

Exchange Rates Refresh

We can do the same with the update quotes use case. First, we change the function's signature to be prepared for the partial application:

// core/refreshRates

export const createRefreshRates =
    ({ fetchRates, readConverter, saveConverter }: Dependencies): RefreshRates =>
    async () => {
        //...
    };

Next, we can partially apply it, passing freshly created functions for working with the store as dependencies:

// core/refreshRates.composition

import { readConverter, saveConverter } from '../../infrastructure/store';
import { fetchRates } from '../../infrastructure/api';

export const refreshRates: RefreshRates = createRefreshRates({
    fetchRates,
    readConverter,
    saveConverter
});

After this, we need to decide how we want to work with the asCommand adapter and update its code. For example, we want the use case to be independent and work without hooks, but we want to see the reactive status of the operation in the UI.

Then we can rewrite asCommand so that it turns the use case function into a hook that returns the { result, execute } interface:

// shared/infrastructure/cqs

export const asCommand =
    <F extends AsyncFn>(command: F): Provider<Command<F>> =>
    () => {
        // ...

        const execute = async () => {
            // ...
        };

        return { result, execute };
    };

The component in this case will continue depending on a hook:

// ui/RefreshRates

type RefreshRatesProps = {
    useRefreshRates: Provider<Command<RefreshRates>>;
};

...But at composition time, we can provide a regular function to a component, the adapter will transform it into a hook:

// ui/RefreshRates.composition

import { refreshRates } from '../../core/refreshRates';
import { asCommand } from '~/shared/infrastructure/cqs';

export const RefreshRates = () => Component({ useRefreshRates: asCommand(refreshRates) });

Other Tools

In this example, we chose Zustand as our state manager because it is suitable for working with objects where multiple fields can be inter-related. In other applications, we might need other tools, such as Jotai or MobX.

In the repository, I left a couple of examples of how to implement the store using these two libraries as well.

Sources and References

Links to books, articles, and other materials I mentioned in this post.

Source code for the current step on GitHub

React Hooks and Components

State and Effect Management

Abstractions and Decomposition

Infrastructure Tools

Explicit Design, Part 6. Cross-Cutting Concerns and Extendable Infrastructure

Alex Bespoyasov — Mon, 21 Aug 2023 08:17:46 +0000

In the previous posts, we composed a basic version of the application that handled the main use cases.

In this post, we will discuss functionality that is related to business logic indirectly: infrastructure expansion, analytics, alert monitoring, logging, and so on.

But first, disclaimer

This is not a recommendation on how to write or not write code. I am not aiming to “show the correct way of coding” because everything depends on the specific project and its goals.

My goal in this series is to try to apply the principles from various books in a (fairly over-engineered) frontend application to understand where the scope of their applicability ends, how useful they are, and whether they pay off. You can read more about my motivation in the introduction.

Take the code examples in this series sceptically, not as a direct development guide, but as a source of ideas that may be useful to you.

By the way, all the source code for this series is available on GitHub. Give these repo a star if you like the series!

Types of Code and Density

In applications, in addition to business logic code, there is also “supporting” code that is not directly related to the domain. It can be “glue” that connects different parts of the application and third-party tools together, or “non-primary” functionality that is indirectly needed by the business, such as analytics or monitoring.

Usually, the more complex the application, the lower the proportion of business logic and the more supporting code it has. We can call this relationship the density: the more supporting code, the lower the logic density. Business rules in it are as if “diluted” by various auxiliary things.

The main danger of low density is that the logic can “dissolve” and “get lost” in the supporting glue. However, business logic and “glue” change for different reasons and with different speeds, so ideally they should be clearly separated and not interfere with each other's work.

On the other hand, supporting code is often difficult to place and encapsulate in any one part of the application because its functionality is used by multiple other modules.

To work conveniently with such code, we can try to divide it into a “service” part that does not depend on the domain, and an “adapter” part that will contain knowledge specific to our application. In this post, we will look at how achievable this is and what limitations may arise along the way.

Logging and Analytics

Let's say that the product owners want to conduct a UX experiment and for that, we need to collect data on how users interact with the application. We need to integrate an analytics service that would register actions on the screen.

In our case, the third-party analytics service will be this code:

// services/analytics
export const sendEvent: SendEvent = async (event, payload) => {
    const dateTime = new Date().toISOString();
    const eventData = payload ? `Additional data: ${payload}` : '';
    const message = `[Analytics ${dateTime}]: Captured event “${event}”. ${eventData}`;
    console.log(message);
};

...That implements the SendEvent type:

// shared/kernel
type SendEvent = (event: string, payload?: string) => Promise<void>;

We don't really care about how events are registered at the moment, so we're just outputting them to the console. At this point, there could be a request to some service like Google Analytics, Firebase, or another.

Let's say we want to link the call to this service with, for example, a click on the “Refresh Rates” button. The simplest way to do this is to put the service in the use case dependencies and call it:

// core/refreshRates

type Dependencies = {
    fetchRates: FetchRates;
    readConverter: ReadConverter;
    saveConverter: SaveConverter;

    // New dependency:
    sendAnalytics: SendEvent;
};

export const createRefreshRates =
    ({ fetchRates, readConverter, saveConverter }: Dependencies): RefreshRates =>
    async () => {
        // Sending the analytics event:
        sendAnalytics('CLICKED_CONVERTER_BUTTON_OR_WHATEVER');

        // ...The rest of the code.
    };

This is a working solution, but it has a problem. The use case didn't know anything about analytics and wasn't dependent on this service, so analytics actually has nothing to do with the use case.

Analytics is important for the business, but it is not a part of the domain model. We can conclude that it is “cross-cutting” code, and we shouldn't mix it directly with the use case function. We can improve the situation by using decorators.

Composition in Decorators

A decorator is a function that enriches another function with some additional functionality. In our case, decorators will “attach” different “additional” calls like analytics to user cases.

Let's create a function withAnalytics, which will expect the RefreshRates use case as input:

// infrastructure/analytics

export const withAnalytics =
    // Accept `RefreshRates` as an argument,
    // return `RefreshRates` as the result:


        (refresh: RefreshRates): RefreshRates =>
        async () => {
            // Calling the service:
            sendEvent('CLICKED_CONVERTER_BUTTON_OR_WHATEVER');

            // Calling the real use case
            // and returning its result:
            return await refresh();
        };

Note that the result of the decorator's work is a new function that implements the same type as the decorator argument. Thus, the decorator enriches the use case, but does not change its public interface. This means that to compose this decorator together with the use case, we only need to wrap the use case function with it:

// core/refreshRates.composition

export const refreshRates: RefreshRates = withAnalytics(
    createRefreshRates({
        fetchRates,
        readConverter,
        saveConverter
    })
);

This allows us to easily compose multiple decorators together, enriching the use case with “additional” functionality without modifying its code.

The type of the withAnalytics function can be made generic to work with different use cases, if necessary.

Benefits of Decorators

Decorators encapsulate all the knowledge about how to work with the analytics specific to a particular feature. The name of the event, the order of the call, and the data that needs to be passed along with the call—all of this is located in one place and not scattered throughout the codebase.

Mixing or removing a specific part of functionality with decorators becomes easier because we only need to add or remove a specific function, without digging into the source code of the use case itself. And the unchanged interface of the use case itself helps to conveniently compose calls.

In general, the idea of decorator composition is not new. If you have worked with OOP code, you are probably familiar with validating or logging decorators. Here we use the same idea, but in the form of a function rather than a class.

Limitations of Decorators

If it's important for us to run analytics in the middle of a use case or depending on certain conditions, a decorator may not be suitable. In such cases, it is generally not too bad to insert a service call into the logic code, but by default, it is worth considering whether this can be avoided.

In addition, a call, such as for analytics, may require data from other restricted contexts. How to solve this depends on the specific project conditions, but you can look towards extracting a Shared Kernel, a common context, or decoupled communication between features. We will talk more about the latter in detail in the next two posts 🙃

Alert Monitoring

In addition to the main error handling mechanisms, it can also be useful to track specific errors in certain use cases. This can be conveniently done with decorators, too.

Let's create the withAlertMonitor decorator, specify the dangerous function as an argument, and return a function wrapped in try-catch that implements the same interface:

// shared/error-handling

const withAlertMonitor =
    (workflow: T): T =>
    () => {
        try {
            // Try to invoke a dangerous operation:
            return workflow();
        } catch (error) {
            //
            // If there's an error we're interested in,
            // send it to the alert monitoring service:
            if (error instanceof DomainError) {
                captureError(error);
            }

            // Finally, re-throw the error up,
            // so that the main error handling mechanism
            // could handle it and, say, tell the user about it:
            throw error;
        }
    };

Decorators can also be used for error handling itself, not just monitoring. It all depends on the project requirements and how the handling is implemented.

The need to rethrow the error will, of course, depend on how the error handling is made in our project too.

In this example, we assume that we handle errors at the top level, and in decorators, we only report them to the monitoring service. We could use such a decorator like this:

// core/refreshRates.composition

import { withAlertMonitor } from '~/shared/error-handling';

export const refreshRates: RefreshRates = withAlertMonitor(
    createRefreshRates({
        /*...*/
    })
);

Performance Profiling

Another scenario for using decorators is performance profiling. For example, to measure how long it takes for a use case to execute, we could write a function like this:

// infrastructure/performance

import type { RefreshRates } from '../../core/ports.input';

export const withPerfMeasure =
    (fn: RefreshRates): RefreshRates =>
    async () => {
        const start = performance.now();
        await fn();
        const end = performance.now();
        console.log(`RefreshRates took ${end - start}ms.`);
    };

And then wrap in it the function we're interested in:

// ...
import { withBenchmark } from '../../infrastructure/performance';

export const refreshRates: RefreshRates = withBenchmark(
    createRefreshRates({
        /*...*/
    })
);

The profiling decorator can also be generic so that it's convenient to use it with different functions.

Persistence

Most of the state management libraries usually provide tools for saving data to the device's local storage. For example, Zustand has a separate package for persistence.

However, sometimes such tools may not exist, or they may not be customizable enough. In such cases, we can write data saving ourselves. For example, first let's describe the data saving “service”:

// shared/kernel

type Persist = <T>(key: PersistenceKey, value: T) => void;
type Retrieve = <T>(key: PersistenceKey) => Nullable<T>;

// services/persistence

export const persist: Persist = (key, value) =>
    window.localStorage.setItem(key, JSON.stringify(value));

export const retrieve: Retrieve = (key) => {
    const value = window.localStorage.getItem(key);
    return value ? JSON.parse(value) : null;
};

Next, we'll describe a decorator that will wrap the SaveConverter output port:

// infrastructure/persistence

const key = 'converter-app:rates';

export const withPersistence =
    (fn: SaveConverter): SaveConverter =>
    (converter) => {
        persist(key, converter.rates);
        return fn(converter);
    };

Then, we'll be able to compose persistence with the service:

// infrastructure/store.composition

import { withPersistence } from '../persistence';

const saveConverter = withPersistence(converter.setState);

Composition of Multiple Decorators

As we mentioned earlier, decorators preserve the type of the function they enhance with new functionality. This means that one use case can be wrapped in multiple decorators at once:

export const refreshRates: RefreshRates = withAlertMonitor(
    withAnalytics(
        withBenchmark(
            createRefreshRates({
                fetchRates,
                readConverter,
                saveConverter
            })
        )
    )
);

For aesthetics, you can use functional utilities like pipe or compose to make the chain look a bit flatter:

export const refreshRates: RefreshRates = pipe(
    // Decorators, in order of applying them:
    withBenchmark,
    withAnalytics,
    withAlertMonitor
)(
    // Use case “baking”:
    createRefreshRates({
        fetchRates,
        readConverter,
        saveConverter
    })
);

This way, the separation of logic and “additional” functionality will be expressed directly in the code, and adding or removing a new decorator will only involve changing the list inside pipe.

Switching Tools and Extending Infrastructure

In addition to using decorators, this method of composition creates a “buffer zone” between different modules of the app allowing for updating or expanding the infrastructure if needed. We have already touched on this topic in the previous post, when discussing replacing the state manager, now let's look at other options.

API Client

For example, if we need to replace fetch with axios, it will be enough to implement the ApiRequest<T> type:

// services/network

import axios from 'axios';

export const get = (url: Url) =>
    axios
        .request({ ...config, url })
        .then((response) => response.data)
        .catch((cause) => {
            throw new Error('Failed to perform request', { cause });
        });

Since the public API of the module hasn't changed, the composition of this service and interaction with other layers of the application will remain the same as it was.

Localization

Localization is a bit more complex topic. It can be either simply part of the UI or somehow intertwined with the use case logic; it depends on the project. In our converter, we can isolate localization at the UI layer level, so it will be sufficient to update the components:

type Localize = (key: string) => LocalizedString;

type BaseValueInputDeps = {
    updateBaseValue: UpdateBaseValue;
    useBaseValue: SelectBaseValue;

    // Declare the localizer as a dependency:
    useLocales: Provider<Localize>;
};

export function BaseValueInput({ updateBaseValue, useBaseValue, useLocales }: BaseValueInputDeps) {
    // Use it inside the component:
    const l = useLocales();

    return (
        <label>
            <span>{l('BaseValueInput.Label')}:</span>
            {/* ... */}
        </label>
    );
}

Then, we'll update composition, passing the localization service:

// ui/BaseValueInput.composition
// ...
import { useLocales } from '~/shared/ui/localization';

export const BaseValueInput = () => Component({ updateBaseValue, useBaseValue, useLocales });

Again, as we discussed in one of the previous posts, the “explicit composition” might not be necessary. If so, we can import the service directly:

export function BaseValueInput() {
    // Import the localizer and use it directly:
    const l = useLocales();

    return (
        <label>
            <span>{l('BaseValueInput.Label')}:</span>
            {/* ... */}
        </label>
    );
}

In the latter case, for testing purposes, a localization provider may be required if we use a library that depends on the context.

Caching and Deduplication

If we need to deduplicate or cache server requests, we can extend the tooling by adding a library for that. Most network libraries currently use hooks, so we will use them in the example too.

By the way, I think that useSWR and React Query take on too much. They go too deep into the multiple application layers, making themselves no longer “non-opinionated,” and in some cases, using them becomes inconvenient. There are libraries that implement the SWR standard and do not use hooks, but there are not many of them.

We already have an infrastructure hook that turns an asynchronous use case into a “command result” for the UI. Let's extend it and add useSWR there:

// shared/cqs.swr

type RequestId = List<Unique<string>>;

// Adding a request ID by which we will
// deduplicate requests and cache the results:
export const asCommand =
    <F extends AsyncFn>(command: F, requestId: RequestId): Provider<Command<F>> =>
    () => {
        const [run, setRun] = useState(false);
        const { data, error, isLoading } = useSWR(run ? requestId : null, command);
        // Under the hood we call useSWR.
        // I don't really like how they recommend
        // to “defer” the call with `null` in their docs,
        // but whatever.

        const execute = (() => setRun(true)) as F;
        const status: Status = isLoading ? 'pending' : !!error ? 'failure' : 'idle';
        const result = { is: status, data, error };
        // We adapt the result of the `useSWR` call to the required interface,
        // so that all components relying on `asCommand` continue to work as before.

        return { execute, result };
    };

Since we have added a new argument to asCommand, we need to add this argument to the composition of components that use it:

// ui/RefreshRates.composition

export const RefreshRates = () =>
    Component({ useRefreshRates: asCommand(refreshRates, ['refresh']) });

...The rest will remain unchanged.

There's a weird quirk though: with this implementation, we have to pass to useSWR not only the network request function but the whole use case. It seems “not quite right” because useSWR is specifically a tool for working with the network. On the other hand, we would still have to restart the use case after updating the data, so I decided that it was “good enough”.

But again, it's not a “tutorial” for writing production code but just an idea of splitting composition of different functionality. It might not fit real-project code because of its “non-standardness”.

Next Time

In this post, we discussed cross-cutting concerns and infrastructure extension. Next time, we'll add a new feature to the application and see how to build vertical slices and why they are useful.

Sources and References

Links to books, articles, and other materials I mentioned in this post.

Source code for the current step on GitHub

Architecture and Design

Error Handling

Networking

Explicit Design, Part 5. App Composition

Alex Bespoyasov — Tue, 15 Aug 2023 07:43:55 +0000

We continue the series of posts and experiments about explicit software design.

Last time we implemented the infrastructure for the application and connected it to the application core's output ports. In this post, we'll talk about composition, assemble the converter from its components, and discuss various types of testing.

But first, disclaimer

This is not a recommendation on how to write or not write code. I am not aiming to “show the correct way of coding” because everything depends on the specific project and its goals.

My goal in this series is to try to apply the principles from various books in a (fairly over-engineered) frontend application to understand where the scope of their applicability ends, how useful they are, and whether they pay off. You can read more about my motivation in the introduction.

Take the code examples in this series sceptically, not as a direct development guide, but as a source of ideas that may be useful to you.

By the way, all the source code for this series is available on GitHub. Give these repo a star if you like the series!

Building “Bottom-Up”

We will be building the application from its components “bottom-up.” We already have use cases, infrastructure services, and a certain number of UI components. From these, we can build a feature.

I cannot give a clear definition of a feature, but to explain roughly, a feature is a set of functionality that distinguishes a bounded context. You could say that a feature is a “microservice” that handles the work of a particular part of the domain.

Scott Wlaschin has a great diagram in his book “Domain Modeling Made Functional”, which I think is the closest to how I understand features. In his view, the composition of the application looks like this:

Functions we can combine in services:
[low-level operation] >> [low-level operation] => [service]

Services into processes:
[service] >> [service] >> [service] => [use case]

Combining processes in parallel, we get an application:
[use case]
[use case] => [application]
[use case]

In my view, there is one more step missing before the final step:

Functions we can combine in services:
[low-level operation] >> [low-level operation] => [service]

Services into processes:
[service] >> [service] >> [service] => [use case]

Combining processes from 1 bounded context, we get a feature (part of an app):
[use case]
[use case] => [feature]
[use case]

Combining features, we get a full application:
[feature]
[feature] => [application]
[feature]

Actually, the converter is a “feature.” It contains a set of 3 use cases that are logically related (i.e. through the domain), combined into a single bounded context (currency conversion rules).

“Update Value” Use Case Composition

The function updateBaseValue, which implements the UpdateBaseValue input port type, is currently responsible for the use case of updating the base currency value. To attach infrastructure and UI to it, we'll use a hook.

By the way, in the next post, we'll discuss whether it's possible to do without hooks in a React application, how the composition of the application will change, and whether there is any benefit to this.

First, let's create the useUpdateBaseValue hook, which will provide the functionality of the use case to the components (inject the use case):

// core/updateBaseValue.composition

export const useUpdateBaseValue: Provider<UpdateBaseValue> = () => {
    // ...
};

Then let's remember what dependencies this use case needs:

type Dependencies = {
    readConverter: ReadConverter;
    saveConverter: SaveConverter;
};

...And gather the actual instances of all the required services:

// core/updateBaseValue.composition

export const useUpdateBaseValue: Provider<UpdateBaseValue> = () => {
    const readConverter = useStoreReader();
    const saveConverter = useStoreWriter();

    // ...
};

We can now pass these services to the use case function:

// core/updateBaseValue.composition

export const useUpdateBaseValue: Provider<UpdateBaseValue> = () => {
    const readConverter = useStoreReader();
    const saveConverter = useStoreWriter();

    return (value) => updateBaseValue(value, { readConverter, saveConverter });
};

Finally, to avoid unnecessary re-renders, we'll use useCallback:

// core/updateBaseValue.composition.ts

export const useUpdateBaseValue: Provider<UpdateBaseValue> = () => {
    const readConverter = useStoreReader();
    const saveConverter = useStoreWriter();

    return useCallback(
        (value) => updateBaseValue(value, { readConverter, saveConverter }),
        [readConverter, saveConverter]
    );
};

...And create the public API for the module:

// core/updateBaseValue/index

export * from './updateBaseValue.composition';

Hooks as a Way of Composition

We can notice that we use the hook only as a means of composing the use case. That is, we do not keep application logic in it, but only the logic of interaction between modules.

In a hook, we describe which dependencies need to be created, where to pass them, and what interface the function should provide as a result. With a stretch, we can say that we use hooks as a “poor man's DI container.”

A “DI container” because it frees the application code from the need to worry about its composition with other modules. “Poor man's” because we have to do a lot of the work manually: calling hooks of the necessary services, injecting dependencies into the use case, and so on.

The problem with this “container” is that the composition code will be executed at runtime. This check will be executed on every re-render of the hook, and we would like to avoid that:

useCallback(
    (value) => updateBaseValue(value, { readConverter, saveConverter }),
    [readConverter, saveConverter]
);

And in general, the code doesn't look like code from a standard React application. But if we look at its equivalent in a more conventional form, we would realize that in “standard” hooks, we would have done the same thing, just less explicitly.

More Conventional Hook

The composition with dependency injection that we wrote above is a result of our desire to keep the core of the application independent of libraries and third-party tools.

While this is valid from an experimental perspective, it may not always be reasonable in real projects. In conventional code, it is likely that the use case code itself would be a hook:

export const useUpdateBaseValue: Provider<UpdateBaseValue> = () => {
    const model = useConverter();
    const saveConverter = useStoreWriter();

    return () => {
        const baseValue = createBaseValue(rawValue);
        const currentRate = lookupRate(model.rates, model.quoteCode);
        const quoteValue = calculateQuote(baseValue, currentRate);
        saveConverter({ baseValue, quoteValue });
    };
};

The idea remains the same, we only sacrifice the independence of the application core from tools and mix composition with logic for convenience.

In general, there is nothing terrible about such a compromise, as long as we take into account the direction of dependencies, loose coupling, first-class reliance on abstractions, and functional core approach. This way, the code will be extensible and debuggable.

In the end, even in the “conventional hook” code, it is visible where we prepare dependencies and where the use case begins:

export const useUpdateBaseValue: Provider<UpdateBaseValue> = () => {
    // Prepare dependencies and data.
    // (Impure section.)
    const model = useConverter();
    const saveConverter = useStoreWriter();

    // Declare the use case function.
    // Implement the input port type,
    // so that the components are decoupled
    // from the application core.
    return () => {
        //
        // Transform the data.
        // (Pure section.)
        const baseValue = createBaseValue(rawValue);
        const currentRate = lookupRate(model.rates, model.quoteCode);
        const quoteValue = calculateQuote(baseValue, currentRate);

        // Call the service to save the model.
        // (Impure section.)
        saveConverter({ baseValue, quoteValue });
    };
};

If necessary, such a hook can be split back into “independent core” and “composition,” because we have taken into account all the limitations in its implementation. This rule can even be used as a mental linter when writing conventional hooks: if we can extract a function with business logic outside, pass dependencies to it, and it works, then the hook is well-written.

I even have the impression that the React team originally conceived hooks as an “injector” of functionality into components, which should not contain the logic itself. However, because of the useState hook, this idea could have been “smudged,” so we now see code where everything is intertwined.

That is partly why the code in this series doesn't directly rely on hooks, because in my understanding, they are just a composition tool, not a place to keep logic. But of course, “cleaner” code should not be perceived as an only guide to action, because explicit composition also has its problems.

If desired, this hook itself can also be decoupled from specific implementations such as useStoreWriter, useStoreReader, and useConverter. I won't go into detail about this in the text, but I'll leave a link to an example where I describe different ways of composing the use case in hooks.

Moving on in the text, we will agree to use the first option (with explicit dependency injection in the use case), solely to make the composition ideas more visible and clear.

Connecting Use Case to UI

We have connected the use case with the infrastructure, now let's connect everything with the UI layer. First, we'll update the dependencies of the component with the base currency field and indicate that we'll be accessing the use case through a hook:

type BaseValueInputDeps = {
    useUpdateBaseValue: Provider<UpdateBaseValue>;
    useBaseValue: SelectBaseValue;
};

Since the use case itself and its type remain unchanged, inside the component we just need to access the function. No other code changes will be required:

export function BaseValueInput({ useUpdateBaseValue, useBaseValue }: BaseValueInputDeps) {
    const updateBaseValue = useUpdateBaseValue();
    // ...The rest of the code stays untouched.
}

While the logic of the component and its interaction with the application's input port remains the same, only their composition has been updated—that is, how we combine them and with what tools. Previously, we passed the use case function directly through props, and now we use a hook to “inject” this function.

The benefit of starting the design from the domain is that it allows us to compose the application in different ways depending on the task, making the interaction between modules more flexible.

After changing the public API of the component, all we have to do is update the tests. Again, since the essence of the component's work has not changed, we only need to adjust the composition of the hook in the tests:

const updateBaseValue = vi.fn();

// New line:
const useUpdateBaseValue = () => updateBaseValue;
const useBaseValue = () => 42;

const dependencies = {
    // Update dependencies:
    useUpdateBaseValue,
    useBaseValue
};

// ...The test stays the same.

Component “Registration”

The last thing we need to do is create a wrapper with a “public API” in the component module. This wrapper will take on the responsibility of connecting all the necessary dependencies in the component and providing its “production version” with already connected dependencies to the outside world:

// ui/BaseValueInput.composition

// Import it so that the real name
// could be re-used in this file later:
import { BaseValueInput as Component } from './BaseValueInput';

// Import real versions of dependencies for the component:
import { useUpdateBaseValue } from '../../core/updateBaseValue';
import { useBaseValue } from '../../infrastructure/store';

// “Register” the component with the same name
// but without requirement for the dependency props:
export const BaseValueInput = () => Component({ useUpdateBaseValue, useBaseValue });

Here, we are building a facade over the internal implementation, which is not relevant to neighboring modules. All required dependencies of the component are obtained just before entering the public API. External modules are not aware of these dependencies, and therefore the coupling between them will not increase.

Let's add the re-export of the component and declare what exactly in this module is the public interface:

// ui/BaseValueInput/index.ts

export * from './BaseValueInput.composition';

More Conventional Component

As with the “unconventional hook,” the code of the component does not look like a typical React component, and the point here is also in explicit composition. In fact, hook imports in the component can also be directly specified in the implementation code and used like this:

import { useUpdateBaseValue } from '../../core/updateBaseValue';
import { useBaseValue } from '../../infrastructure/store';

export function BaseValueInput() {
    const value = useBaseValue();
    const updateBaseValue = useUpdateBaseValue();
    // ...
}

The difference will be the same as with the hook: we sacrifice weak coupling in favor of convenient imports and lack of additional code. In real projects, we are more likely to see this kind of code.

Tests for such a component will probably mock hooks and services. The coupling between the component and the application core and infrastructure will be slightly higher but the amount of “glue code” will be much smaller.

DI, Side Effects, and Functional Core

The just-created use case and its processes lean towards functional programming and repeat the Impureim sandwich we discussed earlier. All side effects are gathered on its edges (in the UI and infrastructure) while pure domain functions that deal only with data transformation reside in the core.

At the same time, we use concepts such as dependencies, DI, “registration,” etc. It may seem like we're contradicting ourselves since there can be no dependencies in FP, but in reality, we use these concepts precisely on the edges of the sandwich—where side effects live.

If you take a closer look at the layout of the use case, you will see that its core is assembled as a set of sequential calls to several functions. Such composition is functional. In the core of the use case, we do not use the concept of “dependencies,” only input and output data.

However, at the edges, we are still forced to work with side-effects: read data from a field, display information on the screen, update the store. It is at this point, outside, that we use “impure” and “non-functional” techniques. This is a compromise, but we allow it for the sake of convenience in composition.

In terms of ideas, if we discard all the “patterns” and the so-called “DI,” we still follow the tenets of functional programming, namely wrapping pure transformations in an impure context, which provides all the necessary data.

“Refresh Rates” Use Case Composition

Now let's discuss asynchronous processes. In order to compose the use case of updating quotes, we will also wrap it in a hook:

// core/refreshRates.composition

export const useRefreshRates: Provider<RefreshRates> = () => {
    const readConverter = useStoreReader();
    const saveConverter = useStoreWriter();

    return useCallback(
        () =>
            refreshRates({
                fetchRates,
                readConverter,
                saveConverter
            }),

        // No need to watch over `fetchRates`
        // because it won't change.
        [readConverter, saveConverter]
    );
};

However, in the component dependencies, we see a different return value:

type RefreshRatesDeps = {
    useRefreshRates: () => {
        execute: RefreshRates;
        status: Status;
    };
};

To “befriend” the types of both hooks, we can write a separate adapter that will transform the hook returning an asynchronous function into a hook returning this type.

Writing an adapter for the hook

To do this, we need a higher-order function. Higher-order functions take other functions as arguments or return functions as results. In our case, the higher-order function asCommand will take one hook and return another:

// shared/infrastructure/cqs

type Adapted = {
    execute: RefreshRates;
    status: Status;
};

export const asCommand =
    (useRefresh: Provider<RefreshRates>): Provider<Adapted> =>
    () => {
        const [status, setStatus] = useState<Status>({ is: 'idle' });
        const refresh = useRefresh();

        const execute = async () => {
            setStatus({ is: 'pending' });
            await refresh();
            setStatus({ is: 'idle' });
        };

        return { status, execute };
    };

Next, we can use this adapter to attach to the component the hook that provides the use case:

// ui/RefreshRates.composition

import { RefreshRates as Component } from './RefreshRates';
import { useRefreshRates } from '../../core/refreshRates';
import { asCommand } from '~/shared/infrastructure/cqs';

// Pass as a dependency not the use case hook
// but its “adapted” version.

export const RefreshRates = () => Component({ useRefreshRates: asCommand(useRefreshRates) });

Implementation of such an adapter may vary greatly depending on the requirements. If it was important for us to reflect the status of the operation in the model, the hook would probably look different.

Extracting Utility Code

In general, the functionality of the asCommand adapter seems somewhat “utility-like,” because:

It will likely be necessary to adapt not just one asynchronous process in this way
The adapter itself does not depend on a specific use case

We can generalize this adapter a bit and get a utility function that we can reuse. First, let's declare helper types that will explain to other developers what we want to express:

type AsyncFn = (...args: unknown[]) => Promise<unknown>;

type Command<F extends AsyncFn> = {
    execute: F;
    status: Status;
};

Yes, the Command type is not exactly the canonical Command pattern, but I couldn't come up with a better name, so I left it like that.

Next, let's extract a higher-order function that will use it:

// shared/infrastructure/cqs

export const asCommand =
    <F extends AsyncFn>(useHook: Provider<F>): Provider<Command<F>> =>
    () => {
        const [status, setStatus] = useState<Status>({ is: 'idle' });
        const command = useHook();

        const execute = async () => {
            setStatus({ is: 'pending' });
            await command();
            setStatus({ is: 'idle' });
        };

        return { status, execute } as Command<F>;
    };

Since the working principle has not changed, there is no need to update the places of use.

Handling Errors

Asynchronous workflows are unreliable. An error can occur during their execution, and we would like to catch it and (for now just) tell the user about it.

Let's expand the Command<T> interface and add handling for different cases: success and error.

type Command<F extends AsyncFn> = {
    execute: F;
    result: Result;
};

type Status = Result['is'];
type Result = { is: 'idle' } | { is: 'pending' } | { is: 'failure'; error: Error };

In a more complex application, the Result type would most likely be a generic that contains data from the successful execution of the asynchronous process. In such a case, we would also probably need to separate it into a result for Query and Command to follow CQS.

Now let's update the adapter:

export const asCommand =
    <F extends AsyncFn>(useHook: Provider<F>): Provider<Command<F>> =>
    () => {
        // Add local state for an error:
        const [status, setStatus] = useState<Status>('idle');
        const [error, setError] = useState<Nullable<Error>>(null);
        const command = useHook();

        // Add `try-catch` and naive error handling:
        const execute = async () => {
            setStatus('pending');
            setError(null);

            try {
                await command();
                setStatus('idle');
            } catch (error) {
                setError(error as Error);
                setStatus('failure');
            }
        };

        // Update the result so that it implements the `Command<T>` type:
        const result = status === 'failure' ? { is: status, error } : { is: status };

        return { result, execute };
    };

Generally, error handling based on exceptions is not the best option. We could use functional techniques for error handling, but we'll talk about them separately someday. I hope sometime I'll write about it in detail with examples.

Now we need to update the component and tests because we've changed the interface it depends on:

export function RefreshRates({ useRefreshRates }: RefreshRatesDeps) {
    // Destructure the result
    // to get required properties:

    const { execute, result } = useRefreshRates();
    const pending = result.is === 'pending';

    // ...
}

In tests:

// Change the stubs' types:
const idle: Result = { is: 'idle' };
const pending: Result = { is: 'pending' };

describe('when in idle state', () => {
    it('returns an enabled button', () => {
        // Update dependencies:
        const useRefreshRates = () => ({ result: idle, execute });

        // ...The rest of the test code is the same.
    });
});

Now we can render an error message below the button:

export function RefreshRates({ useRefreshRates }: RefreshRatesDeps) {
    const { execute, result } = useRefreshRates();
    const pending = result.is === 'pending';
    const failure = result.is === 'failure';

    return (
        <>
            <Button type="button" onClick={execute} disabled={pending}>
                Refresh Rates
            </Button>

            {failure && <span>{result.error.message}</span>}
        </>
    );
}

...And cover it with tests:

const failure: Result = {
    is: 'failure',
    error: new Error('Test error.')
};

describe('when in failure state', () => {
    it('returns a message error', () => {
        const useRefreshRates = () => ({ result: failure, execute });
        render(<RefreshRates useRefreshRates={useRefreshRates} />);

        const button = screen.getByText(/Test error./);

        expect(button).toBeDefined();
    });
});

Feature Composition

After we've prepared all the use cases, we can compose the converter from them.

The converter component will be the “entry point” to the feature and will gather other components inside it, which are entry points to the use cases:

// ui/Converter

import { BaseValueInput } from '../BaseValueInput';
import { QuoteSelector } from '../QuoteSelector';
import { RefreshRates } from '../RefreshRates';

export function Converter() {
    return (
        <form>
            <BaseValueInput />
            <QuoteSelector />
            <RefreshRates />
        </form>
    );
}

We can think of this component as the “public interface” of the feature that is available to the outside world.

Note that the components used no longer need to pass any dependencies through props, because this was done during their composition.

Despite the fact that in the near-functional approach we try to keep dependencies explicit, when presenting some functionality “outside” the module, we hide dependencies. For example, Scott Wlaschin, in “Domain Modeling Made Functional”, recommends doing this in such a way:

For functions issued as public APIs, we hide dependencies from their consumers
For internal functions of the module, we express dependencies explicitly

Next, we attach a provider for the store and ErrorBoundary:

// ...

import { StoreProvider } from '../../infrastructure/store';
import { ErrorBoundary } from '~/shared/ui/ErrorBoundary';

export function Converter() {
    return (
        <ErrorBoundary>
            <StoreProvider>
                <form>
                    <BaseValueInput />
                    <QuoteSelector />
                    <RefreshRates />
                </form>
            </StoreProvider>
        </ErrorBoundary>
    );
}

...And “register” this component as the public API for the module:

// ui/Converter/index
export * from './Converter';

// features/converter/index
export * from './ui/Converter';

Folder Structure and Architecture

So far, we haven't paid much attention to the folder structure in the project. I intentionally didn't focus on this because the folder structure is not as important as the interaction between the parts of the system.

I would even say that the project structure is the product of how the modules communicate with each other, what data they share, and how dependencies are organized.

I like to think that the “right” project structure is the one that has evolved as a result of evolutionary design. That is, the one that reflects the real relationships between the modules.

The essence of this idea is that the “correct” structure will emerge even if we start writing the project in a single file. Gradually, as we complicate the application and add new parts, keeping in mind the directions and flows of data and organizing the code according to the principles of loose coupling, we will inevitably divide this one file into different modules.

By dividing the modules in a way that does not contradict the identified domain rules and the relationships between the parts, we automatically get the “most correct” structure for a particular project.

This approach may seem excessively “frivolous,” but I consider it an advantage. Because if we choose a strict folder structure in advance, at the very beginning of the project, when we know almost nothing about it, it can become an unnecessary limitation that will hinder making certain decisions.

In our case, the current folder structure resembles Feature-Sliced Design:

src/

  We store features in separate folders
  to prevent coupling between them.
  (We will discuss this in more detail in the upcoming posts.)

  features/converter/

    The core of the application (domain, use cases, and ports)
    is located in the `core` folder.
    Files in this folder can be easily restricted
    from importing anything other than the domain and ports,
    for example, by a linter.

    core/
      domain/
      refreshRates/
      updateBaseValue/
      changeQuoteCode/
      ports.input.ts
      ports.output.ts

    Application components are in the `ui` folder.
    Note that this includes so-called containers
    that connect the core with the UI.

    ui/
      RefreshRates/
      UpdateValueInput/
      QuoteSelector/

    Adapters to services are in the `infrastructure` folder.
    Here we make interfaces of third-party tools compatible
    and keep knowledge specific to this feature.

    infrastructure/
      api/
      store/

  Service implementations are in the `services` folder.
  These are utilities, reusable modules
  that do not depend on the project's domain.

  services/
    network/

 “Language extensions”, library code, stubs and mocks,
  UI kit, reusable components are in the `shared` directory.
  This is also where we can store the Shared Kernel.

  shared/
    kernel.ts
    extensions/
    infrastructure/
    testing/
    ui/

This division of features helps, firstly,
to make them as independent as possible,
and secondly, to add, remove, and replace modules
without the need to rewrite or update
a lot of neighboring code.

The main difference from FSD, perhaps, is the explicit highlighting of application ports. But again, it is not necessary to make all concepts explicit, we use them only to more clearly demonstrate the idea of composition.

I will also not dwell on what a Shared Kernel is, but I will leave a link to a great post by Herberto Graça about it.

It is important to note that we did not create this structure from the very beginning—it gradually became more complex as needed. You can track its evolution by looking at the project structure during different stages on GitHub.

Integration Testing

After composing the feature, we can write integration tests for it. In these tests, we'll verify the functionality of the public API of this module, i.e., the Converter component.

Integration tests should be close to “real usage” and interaction between modules. This way, we can reduce test-induced damage and make them more resilient to refactoring.

For brevity, we'll skip the implementation of the integration tests in the text, as well as the code. We've already provided examples of using the React Testing Library in our code, so I think we can skip this part.

Application Composition

At the next level of composition, we have the whole application. In general, if we had multiple features, we would compose a “set of widgets” for these features here and create “pages” or “screens.”

In our case, the application is only one feature wrapped in a layout, so the code will be quite simple:

// pages/Dashboard

import { Converter } from '~/features/converter';

export function Dashboard() {
    return <Converter />;
}

// src/App.tsx

export function App() {
    return (
        <main>
            <Header />
            <Dashboard />
            <Footer />
        </main>
    );
}

It's important to ensure that no logic or description of complex processes “leaks” into this level. We should compose fully ready-made blocks that can be replaced, removed, and rearranged without rewriting a large amount of code.

E2E Testing

After composing the application, we can write a set of End-to-end tests to verify the integration of different features together and the overall operation of the application.

Such tests are a way to check the application as real users would use it. These tests are especially useful if the application has complex business processes that involve multiple features sequentially or even simultaneously.

E2E tests are usually heavy and require a browser to be deployed, so we keep them separate from integration and unit tests. We will keep such tests next to the pages because pages are the “entry point” to the application for users.

For an example of E2E tests, we can use Playwright. For instance, we can write a test to check that after clicking a button in the converter, the expected values appear:

import { test, expect } from '@playwright/test';

test('refresh rates use case', async ({ page }) => {
    const valueInitial = /1 RPC = 0.3 IMC/;
    const valueExpected = /1 RPC = 0.98 IMC/;

    await page.goto('/');
    expect(page.getByText(valueInitial)).toBeDefined();

    const button = page.getByRole('button');
    await button.click();
    await expect(button).toBeDisabled();

    await page.waitForResponse('**/rates');
    expect(page.getByText(valueExpected)).toBeDefined();
});

We won't dive into the implementation of other E2E tests in detail, as this is the topic for a separate post. However, you can play around with the set of tests for this feature in the source code on GitHub.

Next Time

In this post, we talked about application composition, built the application from its component parts, and touched on different types of testing.

Next time, we'll talk about how to achieve the same thing without hooks, how to inject dependencies “in advance” before runtime, and what potential benefits this approach may have.

Sources and References

Links to books, articles, and other materials I mentioned in this post.

Source code for the current step on GitHub

Books

Architecture and Module Interaction

Dependency Management

Common Patterns

Tools and Methodologies

Explicit Design, Part 4. Ports, Adapters, and Infrastructure

Alex Bespoyasov — Mon, 07 Aug 2023 09:45:03 +0000

Let's continue the series of posts and experiments about explicit software design.

Last time we created UI components and discussed the interaction between the UI and the application core. In this post, we will prepare the project infrastructure: create a store for the data model and a service for API requests.

But first, disclaimer

This is not a recommendation on how to write or not write code. I am not aiming to “show the correct way of coding” because everything depends on the specific project and its goals.

My goal in this series is to try to apply the principles from various books in a (fairly over-engineered) frontend application to understand where the scope of their applicability ends, how useful they are, and whether they pay off. You can read more about my motivation in the introduction.

Take the code examples in this series sceptically, not as a direct development guide, but as a source of ideas that may be useful to you.

By the way, all the source code for this series is available on GitHub. Give these repo a star if you like the series!

Output Ports

If previously the UI was communicating with the application through input ports, then with the infrastructure, the application will communicate through output ports: the types FetchRates, ReadConverter, and SaveConverter.

Output ports are the “levers” on the “other side” of the application core. They describe what “service” functionality the application core needs to solve a particular task.

The core relies on these types and “orchestrates” the work of use cases, initiating the work of necessary services at the right moments.

Since the application core relies on abstract types, it becomes decoupled and independent of the infrastructure. Such deliberately explicit separation of code is often excessive and not needed, but we are trying to follow the principles and guidelines from programming books, so we will leave everything completely decoupled.

API Service

The first service that we will need is a module for communicating with the API server. We could describe the function for making requests to the server like this:

// services/network

export async function get<T>(url: Url): Promise<T> {
    const absolute = new URL(url, config.base);
    const response = await fetch(absolute);
    if (!response.ok) throw new Error('Failed to perform the request.');

    return await response.json();
}

The get function constructs the URL of the API endpoint, runs the browser's fetch function under the hood, and parses the data from the server's JSON response.

Note that the code of this function is generic. It does not know what data will come from the server, except that it will be JSON.

The distinctive feature of services is that they are conceptually not related to the domain and can work with any application. A function like get can move from project to project, residing in some lib or shared folder.

Services typically solve a specific utility task: network communication, internationalization, reading and writing to local storage, etc. In the case of the get function, we can check this by describing its type:

type ApiRequest<R> = (url: Url) => Promise<R>;

The ApiRequest<T> type does not touch high-level application concepts. It expresses itself in low-level terms: “request,” “API,” “URL.” It doesn't even know what kind of data it will get from the API, instead it uses the R type-argument, which says that specific data for this function is not important. What matters is the scheme of operation and communication with the server.

Because of their “genericness”, services can be reused in different projects:

Obviously, such a reusable service will not work exactly as our application core wants it to. To resolve this conflict, we will write an adapter—a function that will transform this service's interface to the type of the application's output port.

Service Adapter

We can divide all the work of the adapter for the API service into 3 stages:

Getting data from the API: calling the external get service;
Converting the data to the format of the domain model: deserializing the API response;
Passing the formatted data to the application core: implementing the FetchRates output port.

Let's assume that we know that the server sends us data in the following format:

{
    "rates": {
        "RPC": {
            "IMC": 0.98,
            "WPU": 1.23,
            "DRG": 2.2,
            "ZKL": 1.07
        },
        "IMC": { "//": "..." },
        "WPU": { "//": "..." },
        "DRG": { "//": "..." },
        "ZKL": { "//": "..." }
    }
}

Then the work of an adapter can be expressed as a sequence of the following transformations:

RefreshRates:
  API -> ServerRates
  ServerRates -> ExchangeRates
  ExchangeRates -> Application Core

Let's write a function fetchRates that will implement the FetchRates type:

// infrastructure/api

export const fetchRates: FetchRates = async () => {
    // TODO:
    // 1. Call the API service.
    // 2. Convert the data format.
    // 3. Return the data.
};

...And now let's implement each step.

Data Serialization

Let's start with something simple: since we know in what format the server returns the response, we can write a function to transform the data format.

// infrastructure/api.serialization

type ServerRates = { rates: Record<BaseCurrencyCode, ExchangeRates> };
const toDomain = (dto: ServerRates): ExchangeRates => dto.rates.RPC;

In this function, we access the value of the required field in the server response and return it. In real projects, deserialization can be much more complicated depending on the server response and model data format. (We may need to rename fields or, for example, enrich them with data from another request.)

The purpose of the toDomain function is to encapsulate the knowledge of how to convert server data into a model. When such a deserializer is explicitly separated in the code, it is easier for us to find the place where we need to make changes if the shape of the data on the server changes.

Moreover, with the explicitly defined deserialization, we can support multiple API response schemas simultaneously:

// infrastructure/api.v1.serialization.ts
type ServerRates = { rates: Record<BaseCurrencyCode, ExchangeRates> };
const toDomain = (dto: ServerRates): ExchangeRates => dto.rates.RPC;

// infrastructure/api.v2.serialization.ts
type ServerRates = { default: [BaseCurrencyCode, ExchangeRates] };
const toDomain = (dto: ServerRates): ExchangeRates =>
    dto.default.find(([key]) => key === 'RPC').at(1);

Again, whether to make deserialization explicit or not depends on the task, project size, and how volatile the data on the server is. If the server response never changes, it's probably not necessary.

The response from the server that we describe as the ServerRates type is a so-called data transfer object, DTO. We will not delve into this concept in detail, but Scott Wlaschin has a dedicated chapter on deserialization and working with DTOs in the book “Domain Modeling Made Functional.” I highly recommend reading it.

Using the deserializer, we can fill in the 2nd step of the fetchRates function:

// infrastructure/api

import { toDomain } from './api.serialization';

const fetchRates: FetchRates = async () => {
    // TODO:
    // 1. Call the API service.

    // 2. Convert the data format.
    const data = toDomain(response);

    // 3. Return the data.
    return data;
};

Request to Service

Next, we will call the service itself and retrieve the data from the API:

// infrastructure/api

import type { FetchRates } from '../../core/ports.output';
import type { ServerRates } from './api.serialization';
import { toDomain } from './api.serialization';

import { get } from '~/services/network';

const fetchRates: FetchRates = async () => {
    // 1. Get the data from the API:
    const response = await get<ServerRates>('/rates');

    const data = toDomain(response);
    return data;
};

Notice that we keep the endpoint URL directly in this module, and not in the network service. The reason for this is that the service should remain reusable and independent of the domain and specific project.

The specific endpoint URL is part of a particular feature of the current project. Knowledge of where to retrieve data for the converter from should be kept nearby to the converter itself so that we can quickly locate the necessary places for updates. This increases the cohesion of the feature, as it does not scatter knowledge of it across different parts of the application.

Such a “knowledge packaging” is also known as a vertical slice. We will discuss this architectural pattern in one of the upcoming posts 🙃

Overall, this implementation is already sufficient to integrate the API call with the core of the application. Accessing this adapter will make it call the service, transform the data into the required format, and return it.

Testing, Mocks, and Dependencies

To test such an adapter, we need to create a mock for the ~/services/network module and verify that the get function is called with the required parameters.

// infrastructure/api.test

const spy = vi.fn(() => serverStub);
vi.mock('~/services/network', () => ({ get: spy }));

// ...

it('triggers API call', async () => {
    await fetchRates();
    expect(spy).toHaveBeenCalledOnce();
    expect(spy).toHaveBeenCalledWith('/rates');
});

Using mocks to replace dependencies is a valid option in JS and TS code. In real tests of functions that work with side effects, we will most likely see mocks. However, if our goal is to make the function dependencies explicit, we can “bake” them in.

Partial Application and Explicit Dependencies

Again, the code we will be writing from now on is somewhat non-standard™. We will write it this way to demonstrate the idea of loose coupling and explicit dependencies. It's probably not a good idea to write production code in exactly the same way unless you have good reasons to do so.

We will discuss when it's justified to write code this way and when it's not. For now, please keep in mind that we are writing demonstration code from which you can draw ideas for contemplation, but not necessarily do everything exactly the same way.

In the world of OOP, the idea of “substituting” the necessary dependencies at the right moment is the basis of dependency injection. In general terms, the idea is to free a module from the need to import specific dependencies and work with the reliance on their guarantees—public interfaces.

This way, modules become decoupled from each other, and “glued” together via a DI container. The DI container automatically injects the required concrete dependencies into the places where their interfaces are declared. In object-oriented code, this helps solve the problem of composing objects and their related side effects.

Dependency injection is actually a special case of inversion of control, which helps to make the code more flexible. I wrote a separate article about the idea of inversion of control, dependency injection, and how to do it in an object-oriented style.

Unlike in OOP, in more functional code, all dependencies are passed explicitly, so we won't be using a DI container. Instead, we'll use partial application and the Factory pattern to “bake in” the dependencies.

It doesn't mean, however, that a DI container can't be used together with a near-functional approach. This is more of a matter of taste and tooling but, for simplicity, we'll go with the “raw” approach without additional tools.

Also note that in pure functional code, the concept of “dependencies” cannot exist in the first place, because any dependency brings with it a side effect, and functional code should be pure. All side effects (and therefore dependencies) in such code will be located at the edges of the application.

We do not follow this approach only for the sake of convenience and easier understanding. If you are interested in how to compose a React application in a purely functional style, let me know!

In one of our previous posts, we used the fact that inside a function, we can refer to its arguments and use them, relying on their types:

// core/changeQuoteCode

// Declare types of all required dependencies:
type Dependencies = { saveConverter: SaveConverter };

// Get access to them from the `deps` argument:
export const changeQuoteCode = (quoteCode, deps: Dependencies) => {
    // Use them inside the function
    // knowing that they implement specific types:
    saveConverter({ quoteCode });
};

Dependencies were passed as the last argument in this variant:

const result = changeQuoteCode(realArgument, dependencies);

However, such a “dependency injection” approach raises a contradiction: we either need to always require the argument with dependencies to be passed, or make it optional. Neither option is convenient or sufficiently reliable.

This contradiction can be resolved by making the function “remember” the references to its dependencies:

const result = changeQuoteCode(realArgument); // + Remembered Dependencies

In fact, we can “put” the dependencies in a closure of an outer function:

const createChangeQuoteCode = (dependencies) => {
    // Return another function that has access to `dependencies`
    // because it's in the parent scope which is visible to it.
    return (realArgument) => {
        // Do the stuff with `realArgument` AND `dependencies`.
    };
};

And then partially apply the function createChangeQuoteCode to get a function with “remembered” dependencies:

// Returns a function with “remembered” dependencies:
const changeQuoteCode = createChangeQuoteCode(dependencies);

// Return the result of calling that function:
const result = changeQuoteCode(realArgument);

The technique is called partial application because we execute a function of the form a -> b -> result “halfway,” as if stopping along the way and getting b -> result as a result. A little more about this is written on learnyouhaskell and on Scott Wlaschin's website.

This technique of working with dependencies is sometimes called “baking” dependencies. It is exactly what we'll use to prepare the adapter for the API.

“Baking” Adapter

To “bake” the dependencies, we will create a factory function that takes the adapter dependencies and returns FetchRates:

import type { FetchRates } from '../../core/ports.output';
import type { ServerRates } from './api.serialization';

type Dependencies = { request: ApiRequest<ServerRates> };
type CreateFetchRates = (dependencies: Dependencies) => FetchRates;

In the code, we can express this as:

// infrastructure/api

import { toDomain } from './api.serialization';

// Implement the factory that takes dependencies as argument
// and returns a prepared adapter function:

const createFetchRates: CreateFetchRates =
    ({ request }) =>
    async () => {
        const response = await request('/rates');
        const data = toDomain(response);
        return data;
    };

Then, to create and configure an adapter, we will call the factory and pass an object with the actual service to it:

// infrastructure/api.composition

import type { FetchRates } from '../../core/ports.output';
import { get } from '~/services/network';

export const fetchRates: FetchRates = createFetchRates({ request: get });

Note that the function returned by createFetchRates depends only on the types of services. We perform the substitution of specific service implementations separately, during composition. The intention (functionality of the function) and the implementation (composition) are separated again, making modules more independent.

Functionality and Composition

Let's take a closer look at the structure and composition of the module. We can notice that the implementation of the factory and its result—the function that implements the input port—depends only on two things:

the internals of this same module;
the types of everything else.

// infrastructure/api

// When using something outside the module,
// we import only types:
import type { ApiRequest } from '~/shared/kernel';
import type { FetchRates } from '../../core/ports.output';

// Inside the module we can import anything:
import type { RatesDTO } from './api.serialization';
import { toDomain } from './api.serialization';

export const createFetchRates =
    ({ request }: Dependencies): FetchRates =>
    async () => {
        // ...
    };

This “isolation” from other modules through abstraction helps to avoid unnecessary coupling. The module has one clear entry point for other modules—the public interface:

This entry point reduces coupling and stops the spread of changes across the codebase, because other modules no longer need to know the internals of this module, and vice versa.

On the other hand, substituting concrete implementations increases coupling, and this happens at the final stage, during the composition of the module:

// infrastructure/api.composition

import { createFetchRates } from './api';
import { get as request } from '~/services/network';

export const fetchRates: FetchRates = createFetchRates({ request: get });

Finally, to hide what should not be exposed, we can configure re-exports through index.ts:

// api/index

export * from './api.composition';

Then, from all the module internal details:

infrastructure/api/
  - api.ts                — implementation and factory;
  - api.serialization.ts  — data serialization;
  - api.test.ts           — implementation tests;
  - api.composition.ts    — composition of the module;
  - index.ts

...The other modules can access only the contents of api.composition.ts.

It's clear that in JS you cannot completely forbid importing something from specific files. However, firstly, it expresses intention and structure, and secondly, the restriction can be enforced with a linter or other tools if desired.

On the other hand, such purism may not be necessary for a real project. Remember that the code is only experimental 🙃

Runtime Data Store

In addition to requests to the API, we also need a runtime storage for loaded exchange rates and values entered by users. Today we will write an implementation of the store using the Context API, but in the future we will look at more suitable tools and libraries for this task.

Ports and Implementation

Let's start with an overview of the required functionality. The core of the application requires 2 functions from the store: for reading and saving model data.

// core/ports.output.ts

type ReadConverter = () => Converter;
type SaveConverter = (patch: Partial<Converter>) => void;

To implement this, we can create a context with this type:

// infrastructure/store

// The `Store` type describes the store.
// It's private so that neighboring modules do not depend
// on the details of the store implementation.
type Store = {
    value: Converter;
    update: SaveConverter;

    // As an option, we can also explicitly
    // create a function to read data,
    // but in the case of context, it's not necessary.
    read: ReadConverter;
};

const ConverterContext = createContext<Nullable<Store>>(null);
export const useStore = () => useContext(ConverterContext);

Then, we'll create a provider:

// infrastructure/store

export const StoreProvider = ({ children }: PropsWithChildren) => {
    const [value, setValue] = useState<Converter>(initialModel);

    // If we're using a separate function for reading data
    // (this is not mandatory):
    const read = () => value;

    const update: StoreWriter = (patch) => setValue((state) => ({ ...state, ...patch }));

    return (
        <ConverterContext.Provider value={{ value, read, update }}>
            {children}
        </ConverterContext.Provider>
    );
};

Implementing a store in this way will lead to unnecessary re-renders of components that depend on it. In real projects, try to avoid using context as a state manager and use appropriate libraries for this purpose.

Service Composition

Now we need to associate the types of application ports with the implementation of specific functions by “registering” the service:

// infrastructure/store.composition

import type { ReadConverter, SaveConverter } from '../../core/ports.output';
import { StoreProvider, useStore } from './store';

export const useStoreWriter: Provider<SaveConverter> = () => useStore().update;
export const useConverter: ReadConverter = () => useStore().value;

// If we need a separate function for reading data:
export const useStoreReader: Provider<ReadConverter> = () => useStore().read;

Note that we made the decision about which technology to use for the storage service only at the very end, when the application core was ready. This is a sign of fewer artificial constraints on our choice of tools. When we make a decision about the tooling, we already know a lot more about the project and can choose a more appropriate library for our tasks.

In one of the next posts, we will look at how to choose tools if there are constraints that have been discovered during the design phase, and how loose coupling between modules can help us.

Skipping Application Core

In addition to updating the converter via SaveConverter, we also need to read data from the store in the UI:

// shared/kernel.ts
type Selector<T> = () => T;

// core/ports.input.ts
type SelectBaseValue = Selector<BaseValue>;
type SelectQuoteValue = Selector<QuoteValue>;
type SelectQuoteCode = Selector<QuoteCurrencyCode>;

Since the application core is not involved in reading data (we do not transform data with domain functions when reading), we can implement input ports for reading directly in the store service:

// infrastructure/store.composition

import type { SelectBaseValue, SelectQuoteCode, SelectQuoteValue } from '../../core/ports.input';

const useValueBase: SelectBaseValue = () => useStore().value.baseValue;
const useQuoteCode: SelectQuoteCode = () => useStore().value.quoteCode;
const useValueQuote: SelectQuoteValue = () => useStore().value.quoteValue;

Such a “fast track” bypassing the application core can be used in applications where there is little or no domain logic.

Personally, I don't see anything wrong with this implementation because the service is still connected to the rest of the application through abstractions, so the coupling between modules almost doesn't increase.

(Almost) Everything Together

The application is almost ready. We have created the domain model and worked out use cases, created the UI layer and the necessary components, created services for API requests and data storage. Now we need to put all this together into a working project, which is what we will do next time.

Next Time

Today we implemented all the infrastructure of the application and connected it to the application's output ports.

In the next post, we will compose the entire application from its parts, using hooks as a way of composition, and also discuss what other ways can be used for it.

Sources and References

Links to books, articles, and other materials I mentioned in this post.

Source code on GitHub

Patterns and Principles

Functional Programming

Dependency Management and Architecture

React-Specific Topics

Explicit Design, Part 3. Ports, Adapters, and UI

Alex Bespoyasov — Mon, 31 Jul 2023 10:37:46 +0000

Let's continue the series of posts and experiments about explicit software design.

Last time we finished designing the application core and created use case functions. In this post, we will write components for the user interface, discuss its interaction with the domain model, and look at the difference between different types of data that are displayed in the UI.

But first, disclaimer

This is not a recommendation on how to write or not write code. I am not aiming to “show the correct way of coding” because everything depends on the specific project and its goals.

My goal in this series is to try to apply the principles from various books in a (fairly over-engineered) frontend application to understand where the scope of their applicability ends, how useful they are, and whether they pay off. You can read more about my motivation in the introduction.

Take the code examples in this series sceptically, not as a direct development guide, but as a source of ideas that may be useful to you.

By the way, all the source code for this series is available on GitHub. Give these repo a star if you like the series!

Analyzing UI

The very first thing we will do when developing the UI is to look at what it will consist of and what features it should provide to users. Our application (a currency converter) will consist of one screen, on which the converter component itself will be located:

The converter will store some state—data that will affect the components' render. To understand how to work with this data, let's look at what components will be displayed on the screen, how information will “flow” through the application while working with it.

UI as Function of State

The first thing we will pay attention to is the component header and the text field below it. The field contains the current value of the base currency, and the header contains the value of the quote currency calculated at the current rate:

We can think of these two components as a “transformation” of data from the domain model into a set of components on the screen:

[Domain Model]:   =>   [UI Components]:
_________________________________________

BaseValue         =>   <BaseValueInput />
BaseValue
  & QuoteValue    =>   <CurrencyPair />
  & ExchangeRate

The idea of describing UI as a function of data is not new and lies at the core of various frameworks, libraries, and patterns. This approach helps to separate the data transformations from various side effects related to rendering components and reacting to user input.

One of the reasons for such separation is that data and its representation on the screen change for different reasons and at different pace and frequency. If the code is not separated, then changes in one part seep into another and vice versa. In that case, stopping and limiting the spread of such changes becomes difficult, which makes updating the code unreasonably expensive.

When data and presentation are separated, effects are somewhat “isolated” somewhere on the edge of the application. This makes the code more convenient for understanding, debugging, and testing.

However, not all data that affects UI rendering is exclusively the domain model, and we should also consider (and separate in the code) other types of state.

Types of State

In addition to the model, which describes the domain and is represented in our code by a set of types and functions, we can also identify other types of data that affect the render of components on the screen.

For example, if you click on the “Refresh Rates” button in a currency converter, the application will load data from the API server. The data loaded from there is part of the server state. We have almost no control over it, and the UI task is to synchronize with it in order to show up-to-date information from there.

Actually, instead of “server state,” I would use the term “remote state” because the source of the data can be not only a server, but also local storage, file system, or anything else.

In addition to that, after the button is pressed, while the data is not yet loaded from the server, the button will be disabled, and the converter will show a loading indicator to provide feedback to the user. The flag responsible for the loading indicator can be considered as part of the UI state.

As a rule, UI state is data that describes the UI directly. For example, it includes things like “Is the button disabled?”, “How is the currency list sorted?”, “Which screen is currently open?” and responds to user actions even if the model does not change.

By the way, sometimes non-permanent states (such as “Loading,” “HasError,” “Retrying,” etc.) are placed in a separate category called “meta state”, and everything related to routing is placed in the “URL state.” This can be useful if the application is complex and different data is involved in different processes. In our application, there is no special need for this, so we will not describe everything in such detail.

Data Flow

In complex interfaces, components may depend on several types of state at once. For example, if the quote currency selector needs to be sorted, this component will be a function of both the model and UI state simultaneously:

[Domain Model]:   =>  [UI State]:    =>  [UI Component]:
___________________________________________________________

CurrentQuoteCode  =>  SortDirection  =>  <CurrencySelector
& CurrencyList                            selected={QuoteCurrencyCode}
                                          options={CurrencyList}
                                          sort={SortDirection} />

In code, we will strive to emphasize these dependencies and separate different types of state. We won't always physically separate them (on the file level), but at least we'll try to do it conceptually—in the types and values of variables passed to components.

Different types of state change for different reasons and at different frequencies. We will often put volatile code closer to the “edges of the application” than more stable code. This way, we will try to eliminate the influence of frequent changes on the core of the application, limit the spread of changes across the codebase, show that the data in the model is primary, and indicate the direction in which data “flows” through the app.

Ports and Adapters

Earlier, we represented the application as a “box with levers and slots” through which it communicates with the outside world. User input and the information rendered on the screen can be considered such “communication”:

When a user clicks a button or changes the value in a text field, the UI sends a signal (a.k.a command or action) to the application core to initiate some use case. In our application, this signal will be a function that implements an input port.

// Input port to the app:
type RefreshRates = () => Promise<void>;

// Function that implements the `RefreshRates` type:
const refresh: RefreshRates = async () => {};

// When the button is clicked,
// the UI will invoke the `refresh` function,
// which implements the `RefreshRates` input port.

To handle a click event in React, we can write a component like this:

function RefreshRates() {
    return (
        <button type="button" onClick={refresh}>
            Refresh Rates
        </button>
    );
}

This component transforms a signal from the external world (click on a button) into a signal understandable by the application core (a function that implements the input port). In other words, we can call this component an adapter between the application and the UI.

Driving Adapters an UI

Components handle user input and display information on the screen. They “translate” signals from the application language to a language that is understandable to the user and browser API:

To make this a little more obvious, let's modify the component slightly so that it prevents default behavior when the button is clicked:

function RefreshRates() {
    const clickHandler = useCallback((e) => {
        // Interface of browser APIs:
        e.preventDefault();

        // Application core interface:
        // - function `refresh` implements the input port,
        // - the component relies on its type
        //   and expects the promised behavior.
        refresh();
    }, []);

    // User interface:
    // - the element looks like a button, so it can be clicked,
    // - it has a label that explains what will happen after clicking it.
    return (
        <button type="button" onClick={clickHandler}>
            Refresh Rates
        </button>
    );
}

The RefreshRates component effectively translates the user's intent into the language of the domain model:

UserIntent => ButtonClickEvent => RefreshRates

This conversion makes the component similar to an adapter because it becomes a function that makes two interfaces compatible with each other.

By the way, such adapters are usually called primary or driving adapters because they send signals to the application, indicating what needs to be done. In addition to them, there are also driven adapters, but we will talk more about them later.

“Adapters” can be not only components but also any function that can handle UI events:

window.addEventListener('focus', () => refresh());
window.onresize = debounce(refresh, 250);
setTimeout(() => refresh(), 15000);

// FocusEvent => RefreshRates
// ResizeEvent => Debounced => RefreshRates
// TimerFiredEvent => RefreshRates

The main value of these “adapters” is that they scope the responsibility of the UI code. It cannot directly interfere with the core functionality of the application because the only way to interact with it is by sending a signal through the input port.

Such separation helps to limit the spread of changes. Since all input ports are clearly defined, it doesn't matter to the core what will happen “on the other side.” The presentation on the screen can be changed however we want, but we will always be sure that communication with the core will follow predetermined rules:

Component Implementation

Let's now try to write UI components based on the application ports. We'll start with something simple and write a text field responsible for updating the value of the base currency.

`BaseValueInput`

First, let's create a component markup:

// ui/BaseValueInput

export function BaseValueInput() {
    return (
        <label>
            <span>Value in RPC (Republic Credits):</span>
            <input type="number" min={0} step={1} value={0} />
        </label>
    );
}

Now let's handle the user input and call the function that implements the UpdateBaseValue input port:

// ui/BaseValueInput

// For now, just a stub that implements
// the input port type:
const updateBaseValue: UpdateBaseValue = () => {};

export function BaseValueInput() {
    // “Adapter” component that translates
    // the signal from the field (the change event)
    // into a signal understandable by the application core
    // (call to the `updateBaseValue` port with the necessary parameters).

    const onChange = useCallback(
        (e: ChangeEvent<HTMLInputElement>) => updateBaseValue(e.currentTarget.valueAsNumber),
        []
    );

    return (
        <label>
            <span>Value in RPC (Republic Credits):</span>
            <input type="number" min={0} step={1} value={0} onChange={onChange} />
        </label>
    );
}

Since the component depends on the type of the port rather than the specific function, we can replace the stub with a function from the props. This will help simplify unit tests for the component:

type BaseValueInputProps = {
    updateBaseValue: UpdateBaseValue;
};

export function BaseValueInput({ updateBaseValue }: BaseValueInputProps) {
    return; /*...*/
}

By the way, it is not necessary to pass updateBaseValue as a prop. It is acceptable to simply reference the specific function, and in many cases, this will even be preferable to abstracting through props. But since we are trying to follow all the possible guidelines from various books, we will make the components completely “decoupled” from the application core. Yet, again, it's not necessary.

In the component tests, we can pass a mock in the props that will check that when entering text into the input field, we are indeed calling this function with the correct parameters:

describe('when entered a value in the field', () => {
    it('triggers the base value update handler', () => {
        const updateBaseValue = vi.fn();
        render(<BaseValueInput updateBaseValue={updateBaseValue} />);

        // Find the field, input the string "42" in it:
        const field = screen.getByLabelText(/Value in RPC/);
        act(() => fireEvent.change(field, { target: { value: '42' } }));
        //        ↑ Better to use `userEvent` though.

        // Check that the input port was called with the number 42:
        expect(updateBaseValue).toHaveBeenCalledWith(42);

        // (The task of the component is to extract the required data from the field
        //  in the form of a number and pass it to the input port function.)
    });
});

Note that in the test we are only checking the code that is before the port. Everything that happens after calling updateBaseValue is already not the responsibility of the component. Its job is to call a certain function with the right parameters, and then the application takes responsibility for executing it.

In an integration test, this would be wrong: we would need to test the whole use case and ensure that the user sees the correct updated result on the screen. We will also write integration tests later when we start working on application composition. For now, let's focus on unit tests.

Whether to write unit tests for components is a controversial topic. Some argue that components should be tested mainly with integration tests and we shouldn't to write unit tests for them at all. I won't give any recommendations or advice on this topic because I don't know if there is a “right” way that would work in all cases. I can only advise you to weigh the costs and benefits of both options.

Trivial Tests

Sometimes we may find that a component is doing a trivial task, such as just calling a function in response to a user action, without any additional actions. For example:

const SampleComponent = ({ someInputPort }) => {
    return (
        <button type="button" onClick={someInputPort}>
            Click!
        </button>
    );
};

The test of such a component will come down to checking that the passed function was called on click:

describe('when clicked', () => {
    it('triggers the input port function', () => {
        // ...
    });
});

Whether to write tests for such components depends on preferences and project policy. Here I agree with Mark Seemann, who writes in the book “Code that Fits in Your Head” that such tests are not particularly useful. If the complexity of the function is equal to 1, then tests for such functions can be skipped to avoid cluttering the code.

It's a different story if in the tests we are checking various conditions for rendering the component. If, depending on the props, the component renders different text or is in different states such as loading, error, etc., it may be useful to cover it with tests as well. (However, the complexity of such components will be higher than 1, so the general rule still applies 🙃)

`BaseValueInput`'s Value

In addition to reacting to user input, the base currency field should also display its value. Let's add a new input port that will provide this value:

// core/ports.input

type SelectBaseValue = () => BaseValue;

Now we can update the component dependencies, specifying this port as well:

// ui/BaseValueInput

type BaseValueInputProps = {
    updateBaseValue: UpdateBaseValue;
    selectBaseValue: SelectBaseValue;
};

The implementation of such a port can be any function, including a hook, so we can change the name in the dependencies to useBaseValue:

// ui/BaseValueInput

type BaseValueInputProps = {
    updateBaseValue: UpdateBaseValue;
    useBaseValue: SelectBaseValue;
};

After this, we can use this hook to get the necessary value and display it in the field:

export function BaseValueInput({ updateBaseValue, useBaseValue }: BaseValueInputProps) {
    // Get the value via the hook
    // that implements the input port:
    const value = useBaseValue();

    // ...

    return (
        <label>
            <span>Value in RPC (Republic Credits):</span>

            {/* Render the value in the text field: */}
            <input type="number" min={0} step={1} value={value} onChange={onChange} />
        </label>
    );
}

Usually, the value and the function to update it are put in the same hook to access them like this:

const [value, update] = useBaseValue();

This is a more canonical and conventional way of working with hooks in React. We didn't do this because in the future we will need more granular access to data and updating it, but in general we could have gathered input ports into such tuples.

By the way, to test the data selector useBaseValue, we will check the formatted value inside the field:

// ui/BaseValueInput.test

const updateBaseValue = vi.fn();
const useBaseValue = () => 42;
const dependencies = {
    updateBaseValue,
    useBaseValue
};

// ...

it('renders the value from the specified selector', () => {
    render(<BaseValueInput {...dependencies} />);
    const field = screen.getByLabelText<HTMLInputElement>(/Value in RPC/);
    expect(field.value).toEqual('42');
});

Such a test can also be considered trivial and not created separately, but checked altogether with an integration test.

However, if we still decide to write unit tests, it's important not to intrude into the
responsibility of other modules, but to test only what this component does.

Dependencies as Props

You may have noticed that we are currently passing the component dependencies as props:

type BaseValueInputProps = {
    updateBaseValue: UpdateBaseValue;
    useBaseValue: SelectBaseValue;
};

This approach is quite common, but it is kinda controversial and may raise questions. However, at this stage of development, we have several reasons for doing so:

We don't have ready infrastructure (API, store) from which to import the useBaseValue hook and use it directly. Therefore, we rely on the interface of this hook as a guarantee that this behavior will be provided by “someone, sometime later.”
The coupling between the UI and the core of the application is reduced due to the buffer zone between them, so designing the UI and business logic can be done in parallel and independently. This is not always necessary, but we follow this recommendation as part of our “by the book” coding approach.
The composition of the UI and the rest of the application becomes more explicit, as if specific implementations of dependencies are not passed, the application will not be built.

This does not mean that we will have to use these props in the future. In one of the upcoming posts, we will note the moment when we are ready to remove such “explicit composition” and import hooks directly into the components.

In the source code for clarity, I will leave the composition explicit in all examples so that the boundary between different parts of the application is better visible. Remember that the code is “deliberately clean” and writing it exactly like that is not necessary.

Presentational Components and Containers

In addition to the components that provide a connection to the application core, we can also distinguish components that are solely responsible for rendering data on the screen—the so-called presentational components. They do not contain any business logic, are unaware of the application and depend only on their props, and their scope is limited to the UI layer.

In our case, such a presentational component might be the Input component. It's a wrapper for the standard text field with some preset styles:

import type { InputHTMLAttributes } from 'react';
import styles from './Input.module.css';

type InputProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'className'>;

export function Input(props: InputProps) {
    return <input {...props} className={styles.input} />;
}

The task of this component is to correctly and nicely render a text field. It has no logic, does not use hooks, does not access any data or functionality, and all its behavior depends solely on its props.

We could use such a component in BaseValueInput like this:

import { Input } from '~/shared/ui/Input';

export function BaseValueInput(/*...*/) {
    const value = useBaseValue();
    const onChange = useCallback(/*...*/);

    return (
        <label>
            <span>Value in RPC (Republic Credits):</span>
            <Input type="number" min={0} step={1} value={value} onChange={onChange} />
        </label>
    );
}

Unlike the presentational Input component, the BaseValueInput component knows about the application and can send signals to it and read information from it. Some time ago, such components were called containers.

With hooks, the concept of containers has somewhat disappeared, although after the emergence of server components, people have started talking about them again. In any case, the term is quite old and seems useful for understanding the conceptual difference between different “kinds” of components.

Roughly speaking, the job of a presentational component is to look nice, while the job of a container is to provide a connection to the application. That's why BaseValueInput knows how to invoke “use cases” and how to adapt application data and signals to the presentational Input component:

Presentational components become reusable because they don't know anything about the project context and the domain, and can be used independently of the application functionality.

Asynchronous Workflows

Let's go back to the stock quotes update button. We remember that clicking on it triggers an asynchronous process:

// core/ports.input

type RefreshRates = () => Promise<void>;

We can pass a function that implements the RefreshRates input port as a click handler for the button:

// ui/RefreshRates

type RefreshRatesProps = {
    refreshRates: RefreshRates;
};

export function RefreshRates({ refreshRates }: RefreshRatesProps) {
    return (
        <Button type="button" onClick={refreshRates}>
            Refresh Rates
        </Button>
    );
}

...But that won't be enough. For asynchronous processes, we would like to show state indicators in the UI, so that users receive feedback from the interface. We can achieve this by combining the domain and UI states in the component “dependencies”, which will be responsible for the status of the operation.

Let's update the type RefreshRatesProps and indicate that the component depends not only on the input port of the application, but also on some other state:

type RefreshAsync = {
    // The component still gets the function
    // that implements the input port:
    execute: RefreshRates;

    // But also it gets some new data that is associated
    // with the state of that operation:
    status: { is: 'idle' } | { is: 'pending' };
};

type RefreshRatesDeps = {
    // And we assume that the component
    // gets everything from a hook:
    useRefreshRates: () => RefreshAsync;
};

In our case, the status field is a part of the UI state because it only affects the user interface. However, if the operation status somehow affected other business logic processes, we would probably have to include it in the model and describe various data states with regard to the status.

Inside the component, we can rely on the guarantees from useRefreshRates that when the status changes, the associated data will also change:

export function RefreshRates({ useRefreshRates }: RefreshRatesDeps) {
    const { execute, status } = useRefreshRates();
    const pending = status.is === 'pending';

    return (
        <Button type="button" onClick={execute} disabled={pending}>
            Refresh Rates
        </Button>
    );
}

We can loosely call such guarantees of status changes from useRefreshRates a form of a contract. We may not write pre- and post-condition checks, but we have them in mind while describing the RefreshAsync type.

Now the component can be tested by passing a stub as a hook dependency, which will return a specific UI state:

const execute = vi.fn();
const idle: Status = { is: 'idle' };
const pending: Status = { is: 'pending' };

describe('when in idle state', () => {
    it('renders an enabled button', () => {
        const useRefreshRates = () => ({ status: idle, execute });
        render(<RefreshRates useRefreshRates={useRefreshRates} />);

        const button = screen.getByRole<HTMLButtonElement>('button');

        expect(button.disabled).toEqual(false);
    });
});

describe('when in pending state', () => {
    it('renders a disabled button', () => {
        const useRefreshRates = () => ({ status: pending, execute });
        render(<RefreshRates useRefreshRates={useRefreshRates} />);

        const button = screen.getByRole<HTMLButtonElement>('button');

        expect(button.disabled).toEqual(true);
    });
});

describe('when the button is clicked', () => {
    it('triggers the refresh rates action', () => {
        const useRefreshRates = () => ({ status: idle, execute });
        render(<RefreshRates useRefreshRates={useRefreshRates} />);

        const button = screen.getByRole<HTMLButtonElement>('button');
        act(() => fireEvent.click(button));

        expect(execute).toHaveBeenCalledOnce();
    });
});

...And we will write the actual implementation of the useRefreshRates hook in one of the next posts 🙃

Next Time

In this post, we described the user interface and discussed its interaction with the application core. Next time, we will create the application infrastructure, write API requests, and set up a runtime data store for the application.

Sources and References

Links to books, articles, and other materials I mentioned in this post.

Source code for the current step on GitHub

UI as Function of State

Patterns and Principles

Testing UI

Explicit Design, Part 2. Application Core Design

Alex Bespoyasov — Mon, 24 Jul 2023 06:29:34 +0000

Let's continue the series of posts and experiments about explicit software design.

Last time, we discussed what a domain model is, its benefits, and how we can use functional programming, static typing, and DDD to simplify modeling. In this post, we will talk about how to design use cases and discuss how to integrate our application with the outside world without the need to rewrite a lot of code.

But first, disclaimer

This is not a recommendation on how to write or not write code. I am not aiming to “show the correct way of coding” because everything depends on the specific project and its goals.

My goal in this series is to try to apply the principles from various books in a (fairly over-engineered) frontend application to understand where the scope of their applicability ends, how useful they are, and whether they pay off. You can read more about my motivation in the introduction.

Take the code examples in this series sceptically, not as a direct development guide, but as a source of ideas that may be useful to you.

By the way, all the source code for this series is available on GitHub. Give these repo a star if you like the series!

Data and Use Cases

Our domain model contains data transformations that occur inside the converter but does not describe how the application should interact with the user. To describe such interaction, we will create use cases.

Simply put, use cases are descriptions of what should happen when a user interacts with the application. They show what data the application will receive, how and where from, what domain function it will execute afterwards, and how it will present the result of the work to the user on the screen or in the CLI.

We can create such a use case, for example, for updating quotes and get something like:

Use Case: “Refresh Exchange Rates”
When the user clicks a refresh button:

1. The app gets fresh exchange rates from the API.
2. Finds currently entered base currency value.
3. Recalculates the quote value based on these inputs.
4. Shows the updated values on the screen.

Note that while we describe the details of interaction with the API for obtaining exchange rates, we do not specify concrete functions for updating the UI. Right now, we are only outlining the sequence of actions, describing operations “at a high level.”

Levels of Abstraction

When I mention “design levels,” I like to refer to Mark Seemann's post on “Fractal Architecture”.

In this concept, Mark presents programs as a set of nested hexagons. Each hexagon contains a limited number of components, but they can be zoomed in to see details. Thus, we keep a limited amount of information at each level, not overloading our heads:

I also like to use this metaphor when designing an app. Each level of a use case is like a hexagon. At first, we see only a “general description” of the operations that the application will perform.

Later, when we move on to implementation, we will “zoom in” to lower levels and work out each operation separately in more detail and depth.

Use Case as Types

Carefully examining the described scenario, we can notice that some of its operations can already be represented as types of the domain model:

Use Case: “Refresh Exchange Rates”
When the user clicks a refresh button:

1. The app gets fresh [ExchangeRates] from the API.
2. Finds currently entered [BaseValue].
3. Recalculates the [QuoteValue] based on these inputs.
4. Shows the updated values on the screen.

If we take this further, we can represent the entire use case as a sequence of data transformations from the user input signal to displaying information on the screen:

ButtonClickEvent ->

  ExchangeRates ->
  [BaseValue, QuoteCode] ->
  [QuoteValue, ExchangeRate] ->

DataRenderedEvent

We will now try to express this sequence in the function code below.

Impureim Sandwich

In the use case above, you may notice that interactions with the outside world (ButtonClickEvent and DataRenderedEvent) are located at the beginning and end of the use case, while only domain data transformations are in the middle.

This code organization is called “Functional core in an imperative shell”, or “Impureim sandwich”. Its essence is to concentrate all “impure” code at the edges, and keep only data transformations built on pure functions inside:

The main benefit of the sandwich is that it removes the influence of unpredictable effects on the data we work with. However, in our use case, there are a few more benefits:

Since the “entry into the domain” is explicit, it is more convenient for us to validate the input data and check the invariants.
The entire use case logic is reproducible and easily testable because it only depends on the input data.
We don't need to pre-plan how to interact with the outside world, but we'll talk more about this a little later :–)

Designing the Use Case

When designing use cases, we can use the same approach we used when developing the model last time. First, we describe the functionality in types, and then we implement it as a function. Let's go through all the stages of the use case and turn them into types.

Clicking on the button initiates the use case, after which we need to get exchange rates from the server, read the current value of the base currency, and the code of the quote currency. We can express these two operations as follows:

// Get fresh exchange rates from the API or a runtime data storage:

type FetchRates = () => Promise<ExchangeRates>;
type ReadConverter = () => [BaseValue, QuoteCurrencyCode];

Then we pass the available data through the existing domain transformations:

// Transform data using the domain model:

type LookupRate = (rates: ExchangeRates, code: QuoteCode) => ExchangeRate;
type CalculateQuote = (base: BaseValue, rate: ExchangeRate) => QuoteValue;

Finally, we display the result on the screen:

// Update the data in the UI:

type UpdateConverter = (rates: ExchangeRates, quote: QuoteValue) => void;

Power of Abstraction

The described actions are easily held in our heads as a sequence because the type names are expressed in terms suitable for this level of abstraction. They do not delve too much into the details of each operation, but express its intent. Type names “package” all the complexity and details of each action, leaving only the most important information visible.

This approach helps us to dive into the code gradually, receiving information about the system in a controlled way, without overwhelming our working memory:

In addition, separating intention from implementation helps us to design use cases without thinking about the tools we will use. Instead, we roughly describe the functionality we want to obtain from the tools in the types.

This approach allows us to delay making big decisions about which libraries or third-party tools to use. The advantage is that we may not yet know all the actual requirements of the application, and it may be too early to choose tools. By abstracting away the tooling for now, we give ourselves a better chance to select the right tools in the future when we have a better understanding of how the application will work.

Delaying tooling decisions is not always necessary. It is quite possible that we already know that we will be using a particular lib (or the database we will use on the backend), and it is likely that this tool will not change. In that case, there is not much sense in “abstracting” this dependency.

Application Ports

The types that “abstract out” libraries and third-party services are the so-called application ports.

A port is a specification of how an application wants to communicate with the outside world, how it wants to adapt the world to its needs. Ports describe how and in what form the application is ready to receive data and what result it will provide to the outside world.

The ports through which the outside world addresses the application are called input ports. And those through which the application talks to the outside world are called output ports.

The first ones describe what needs to be done to “push” the application do some work, while the second ones describe how the app will “initiate the contact” itself and what additional functionality it may need.

For example, in the case of updating exchange rates, the output port to the application would be some button-click handler function:

// This type says: “When the user clicks the button,
// the application will start an asynchronous process.”

type RefreshRates = () => Promise<void>;

The output ports would be the types describing the server and data storage that would keep the previously loaded data:

// Network & API:
type FetchRates = () => Promise<ExchangeRates>;

// Runtime storage:
type ReadConverter = () => ConverterModel;
type UpdateConverter = (patch: Partial<ConverterModel>) => void;

We can think of these types as the “levers” and “slots” that the “application box” provides to the outside. All interaction with the outside world will go through them:

Clear application boundaries and rules for communicating with it abstracts the details of the infrastructure and UI. A “buffer zone” appears between the application and third-party modules, which helps limit the propagation of changes from the application to the outside world and vice versa.

We'll need adapters and anti-corruption layer to create such a “buffer zone,” but let's not get ahead of ourselves. We'll talk about all these concepts in detail in the next posts 🙃

Abstraction-Driven Implementation

Like last time, having described the functionality in types, we can proceed with the implementation of the use case as a function:

// core/refreshRates

export const refreshRates = () => {};

Calling this function is the entry point into the application core from the UI. This means that this function implements the input port. Let's make sure it implements the RefreshRates type:

// core/ports.input

export type RefreshRates = () => Promise<void>;

// core/refreshRates

export const refreshRates: RefreshRates = async () => {};

// The function must be asynchronous,
// because `RefreshRates` returns a promise.
// To ensure the function implements some type,
// we can explicitly specify its type with `:`.
// Then, if the types don't match,
// TypeScript will complain about it.

The contents of the refreshRates function will be a description of the entire use case:

// core/refreshRates

import type { RefreshRates } from '../ports.input';

import { calculateQuote } from '../domain/calculateQuote';
import { lookupRate } from '../domain/lookupRate';

export const refreshRates: RefreshRates = async () => {
    // 1. Fetch latest rates from the API:
    const rates = await fetchRates();

    // 2. Get the current model from runtime storage:
    const model = readConverter();

    // 3. Run all the domain data transformations:
    const rate = lookupRate(rates, model.quoteCode);
    const quote = calculateQuote(model.baseValue, rate);

    // 4. Update the runtime storage,
    //    consequently triggering the rerender.
    saveConverter({ rates, quoteValue: quote });

    // *. If we were working not with React but with a lib
    //    that doesn't automatically track rerenders,
    //    we could trigger the rerender from here manually.
};

Inside the use case, we rely on guarantees from the functions that implement the output ports: fetchRates, readConverter and saveConverter. Thanks to the types, we know what arguments each of them expects and what result we will get after the call:

// core/pots.output

type FetchRates = () => Promise<ExchangeRates>;
type ReadConverter = () => Converter;
type SaveConverter = (patch: Partial<Converter>) => void;

We can replace the implementations of these functions with stubs for the first time so that the compiler does not complain about missing variables:

const fetchRates: FetchRates = async () => {};
const readConverter: ReadConverter = () => {};
const saveConverter: SaveConverter = () => {};

Use Case Dependencies

The stub functions for the output ports help with the initial design, but that's where their usefulness ends. We can use type reliance more extensively.

Imagine instead of separate functions we have an object in which all these functions are gathered together:

// core/refreshRates

type AllOutputPorts = {
    fetchRates: FetchRates;
    readConverter: ReadConverter;
    saveConverter: SaveConverter;
};

const ports: AllOutputPorts = {}; /*...*/

We don't care exactly how the functions get into this object yet, so let's just assume that they somehow end up there. Then we can refer to this object and get all the functions we need from it in the use case code:

// core/refreshRates

export const refreshRates: RefreshRates = async () => {
    const { fetchRates, readConverter, saveConverter } = ports;

    // ...Use case code.
};

If we go a little further, we notice that we don't have to keep the dependency object inside the function. We can pass it as an argument to refreshRates:

// core/refreshRates

export const refreshRates: RefreshRates = async ({
    fetchRates,
    readConverter,
    saveConverter
}: AllOutputPorts) => {
    // ...
};

The ports are now in a closure of the refreshRates function, not in any particular object. This means that for refreshRates they are very real, but we don't need to create stubs for the ports anymore. All dependencies of the refreshRates function are taken directly from its arguments.

However, we broke the guarantees of the RefreshRates type. According to this type, the refreshRates function should not require arguments, and now it needs an object with dependencies. Let's fix this by adding a default value to the argument so it's no longer required. (And update the type name as well.)

// core/refreshRates

const stub = {} as Dependencies;

export const refreshRates: RefreshRates = async ({
    fetchRates,
    readConverter,
    saveConverter
}: Dependencies = stub) => {
    // ...
};

If you recognize in this Dependency Injection (DI), that's pretty much it. More precisely, its near-functional counterpart.

Generally speaking, there are several techniques for dependency management in the near-functional paradigm, and we haven't chosen the best one yet. We'll see how to use more elegant techniques in the future, but for now we'll go with that one.

By the way, in pure functional programming there is no concept of dependencies in principle, there all program operation is based on the Impureim Sandwich principle. On GitHub, I put a separate example of how the use case could be implemented “more functionally.”

Also, we'll mention real DI containers in some of the future posts but we won't use them or focus our attention on them too much because in FP-like world the dependency management is explicit. If you're interested in how to use such containers in more OOP-like way, I can recommend reading this post.

However, it doesn't mean that we can't combine “near-functional” style with DI containers. It's just a matter of taste and tools we use.

Testing Use Case

“Dependency Injection” gives us the opportunity to test a use case without waiting for its dependencies to be ready. This is liberating, because we can distribute work, for example, between different teams or switch between tasks depending on priorities.

Obviously, we cannot write integration tests without real dependencies, but we can write unit tests. For example, let's describe tests for the use case with exchange rates update. Let's start with planning the tests with .todo:

// core/refreshRates.test

describe('when called', () => {
    it.todo('should recalculate the quote value using the rates from the API');
    it.todo('should update the exchange rates data with the one from the API');
    it.todo('...');
});

We will try to use output-based to test the use case, that is, to simulate the input and monitor the output of the function. Sometimes we will also use state-based testing, although it is less resistant to change.

I recommend reading “Principles and methods of unit testing” by Vladimir Khorikov. In the book, you can read more about unit testing, its principles and difference between output-based and state-based tests.

To test the use case, we replace dependencies with stubs and mocks. We replace the functions that provide us some data with stubs that don't contain complex functionality. To check the result, we will use a spy—a function that will monitor how and with what arguments it will be called:

// core/refreshRates.test

// Simple stubs provide input data:
const fetchRates = async () => ({ ...rates });
const readConverter = () => ({ ...converter });

// Spy checks the output calls:
const saveConverter = vi.fn();

// All the dependencies for the use case:
const dependencies = {
    fetchRates,
    readConverter,
    saveConverter
};

Then we'll describe that as a result of the work the spy should be called with certain data:

// core/refreshRates.test

describe('when called', () => {
    it('should recalculate the quote value using the rates from the API', async () => {
        // As the result of the use case:
        await refreshRates(dependencies);

        // ...The spy must be called with this data:
        expect(saveConverter).toHaveBeenCalledWith({ quoteValue: 5, rates });
    });
});

Since dependency types can be implemented by anything, it's pretty easy to replace them with a stub or a mock. This way, we can test the use case function based on contracts.

I usually try to write my tests and functions so that my code contains as few mocks as possible and as many stubs as possible. This helps avoiding test-induced damage and also makes tests independent of the specific implementation of dependencies and the location of modules in the file system. But this is just my preference, your tastes in testing might differ 🙃

Default Dependencies and Composition

We mentioned above that passing dependencies as the last argument is not the best solution:

The argument with dependencies, even if optional, still violates the function interface. We would like the function type to be unambiguous and forbid any invalid call.
Dependencies get into a function in runtime, and since the argument is implicit, it's easy to miss and forget to pass it. We would like all the “function preparations” to happen beforehand, and if there are no dependencies, the code won't get built at all.

In a future post, we'll see how to achieve all of this by partially applying functions and “baking” dependencies.

Intention and Implementation

If we look at the imports in the use case file, we see that the application core uses only domain functions and types of input and output ports:

// core/refreshRates.ts

// From ports, import only types:
import type { RefreshRates } from '../ports.input';
import type { FetchRates, ReadConverter, SaveConverter } from '../ports.output';

// From domain, import functions:
import { calculateQuote } from '../domain/calculateQuote';
import { lookupRate } from '../domain/lookupRate';

The use case sort of abstracts away from specific implementations of the application ports, allowing them to be passed from the outside:

Intention:                      Composition:                   Implementation:

RefreshRates(                   RefreshRates(
  FetchRates,                     fetchRatesFn,         <-     const fetchRatesFn = async () => {...},
  ReadConverter,        ->        readConverterFn,      <-     const readConverterFn = () => {...},
  SaveConverter                   saveConverterFn       <-     const saveConverterFn = (data) => {...}
)                               )

Declares dependencies,          Configure work of the function
that can be configurable.       by passing specific dependencies.

So the it becomes unimportant for the application core how exactly the ports to the outside world are implemented, as long as their interface is respected. We sort of break down the work of the use case into intention and implementation.

We express intention in types and code that relies on them. And we express the implementation in code that substitutes specific dependencies—composition. By doing so, we separate code with functionality from service code that “glues” different modules together.

By the way, we also can forbid use cases to import port implementations, by using linter. I wouldn't do it by default, but it wouldn't be hard to set up such a rule if necessary.

Dependency Direction

The separation of functionality and composition helps the application core not to depend on third-party code: infrastructure, UI, networking. On the contrary, the application requires the outside world to “adjust” to its needs and depend on domain code and use cases:

This dependency direction, for example, makes it easier to replace tools in testing. In tests, we just replace the real service with a mock or stub:

// core/refreshRates.test

const saveConverter = vi.fn();
const dependencies = {
    // ...
    saveConverter
};

describe('when called', () => {
    it('should recalculate the quote value using the rates from the API', async () => {
        await refreshRates(dependencies);
        expect(saveConverter).toHaveBeenCalledWith(/*...*/);
    });
});

This is a rather subjective argument, because services can always be mocked at module level. (Although it is also worth considering that module-level mocks can be more difficult to update, and they bind us to the file structure. What to choose depends on the problem.)

Full independence from the tools is not always necessary and justified, and in general it sounds utopian and maximalist. Sometimes it is much more effective to be bound to some library or service, especially if we are not going to change it. But since we're experimenting and writing code “by the book”, we'll close our eyes to that for now.

Other Use Cases

In addition to updating exchange rates, we have two more use cases: updating the value of the base currency and changing the quote currency. Let's implement them as well, let's start with the first one.

First, let's declare the input port:

// core/ports.input

export type UpdateBaseValue = (value: string | number) => void;

The function will accept a string or a number, which we will try to normalize to a base currency value. We commit to doing the normalization ourselves to ensure consistency of the data, because right now only the domain knows how to detect a valid value. We also free the module that will run this use case from having to worry about the value being passed.

Then we design the use case itself:

// core/updateBaseValue

export const updateBaseValue: UpdateBaseValue = (rawValue) => {
    // 1. Impure section:
    // 1.1. Get current `quoteCode` and `rates`.
    //
    // 2. Pure section:
    // 2.1. Normalize the value received as an argument.
    // 2.2. Determine the current rate of the selected pair.
    // 2.3. Recalculate the quote currency value.
    //
    // 3. Impure section:
    // 3.1. Save updated value of base currency.
    // 3.2. Save the recalculated quote currency value.
};

The pure section we can already build from domain functions:

// core/updateBaseValue

export const updateBaseValue: UpdateBaseValue = (rawValue) => {
    // 1. Impure section:
    // 1.1. Get current `quoteCode` and `rates`.

    // 2.
    const baseValue = createBaseValue(rawValue);
    const currentRate = lookupRate(model.rates, model.quoteCode);
    const quoteValue = calculateQuote(baseValue, currentRate);

    // 3. Impure section:
    // 3.1. Save updated value of base currency.
    // 3.2. Save the recalculated quote currency value.
};

And in order to retrieve and store the data, we will connect to the output ports:

// core/updateBaseValue

// Declare required dependencies:
type Dependencies = {
    readConverter: ReadConverter;
    saveConverter: SaveConverter;
};

export const updateBaseValue: UpdateBaseValue = (
    rawValue,
    // Get the dependencies inside the function:
    { readConverter, saveConverter }: Dependencies
) => {
    // 1.
    const model = readConverter();

    // 2. ...

    // 3.
    saveConverter({ baseValue, quoteValue });
};

And like last time, to avoid breaking the UpdateBaseValue type, let's add a stub with the default value of the argument:

// core/updateBaseValue

const stub = {} as Dependencies;

export const updateBaseValue: UpdateBaseValue = (
    rawValue,
    { readConverter, saveConverter }: Dependencies = stub
) => {
    // ...
};

Now we can write tests for this function by composing the use case with stubs and mocks:

// core/updateBaseValue.test

const readConverter = () => ({ ...converter });
const saveConverter = vi.fn();
const dependencies = {
    readConverter,
    saveConverter
};

describe('when given a valid base value update', () => {
    it('recalculates the model according to the new value and current rates', () => {
        updateBaseValue(42, dependencies);
        expect(saveConverter).toHaveBeenCalledWith({
            baseValue: 42,
            quoteValue: 21
        });
    });
});

describe('when given an invalid base value update', () => {
    it('recalculates the quote using 0 as the base value', () => {
        updateBaseValue('invalid', dependencies);
        expect(saveConverter).toHaveBeenCalledWith({
            baseValue: 0,
            quoteValue: 0
        });
    });
});

Test-Driven Development

As in the case of the domain, we can use TDD as a design tool for use cases. Given that we rely on abstractions, we can describe our expectations without having to write real implementations of dependencies.

Again, my goal is not to “sell” TDD. This series is an experiment where we try different approaches and look at their applicability to understand the pros and cons of the techniques used. Whether to apply a particular tool, paradigm or methodology depends on the specific task at hand.

Let's write the last remaining case with a change of quote currency, using TDD. Let's plan out the desired behavior:

// core/changeQuoteCode.test

describe('when given a new quote code', () => {
    it.todo('changes the quote code in the model');
    it.todo('recalculates quote according to the new code and current rates');
});

Let's write a call to the first function and declare in which form we want to get the result:

// core/changeQuoteCode.test

const saveConverter = vi.fn();
const dependencies = {
    saveConverter
};

describe('when given a new quote code', () => {
    it('changes the quote code in the model', () => {
        // After the function call:
        changeQuoteCode('DRG', dependencies);

        // ...We expect to see the change of quote currency in the model.
        expect(saveConverter).toHaveBeenCalledOnce();
        expect(saveConverter.mock.lastCall?.at(-1).quoteCode).toBe('DRG');
    });
});

Then we create an empty implementation and check that the test fails for the expected reason:

AssertionError: expected "spy" to be called once
  20|   it("changes the quote code in the model", () => {
  21|     changeQuoteCode("DRG", dependencies);
  22|     expect(saveConverter).toHaveBeenCalledOnce();
    |                           ^
  23|     expect(saveConverter.mock.lastCall?.at(-1).quoteCode).toBe("DRG");
  24|   });

- Expected   "1"
+ Received   "0"

This time we won't get into details of TDD and its principles. But if you're interested in learning about it, I'll leave some links to materials about it.

Then we implement the function:

// core/changeQuoteCode

type Dependencies = {
    saveConverter: SaveConverter;
};

export const changeQuoteCode: ChangeQuoteCode = (quoteCode, { saveConverter }: Dependencies) => {
    saveConverter({ quoteCode });
};

Then we will write the second test. This time we need to mix in some state and data, so we create another stub in the dependencies:

// core/changeQuoteCode.test

const readConverter = () => ({ ...converter });
const saveConverter = vi.fn();
const dependencies = {
    readConverter,
    saveConverter
};

// ...

it('recalculates quote according to the new code and current rates', () => {
    changeQuoteCode('DRG', dependencies);
    expect(saveConverter).toHaveBeenCalledOnce();
    expect(saveConverter.mock.lastCall?.at(-1).quoteValue).toBe(2.5);
});

After that, we check that the test fails because there is no value, and create an implementation:

// core/changeQuoteCode

type Dependencies = {
    readConverter: ReadConverter;
    saveConverter: SaveConverter;
};

export const changeQuoteCode: ChangeQuoteCode = (
    quoteCode,
    { readConverter, saveConverter }: Dependencies
) => {
    const model = readConverter();

    const currentRate = lookupRate(model.rates, quoteCode);
    const quoteValue = calculateQuote(model.baseValue, currentRate);

    saveConverter({ quoteCode, quoteValue });
};

Finally, let's fix the broken ChangeQuoteCode input port interface and add a stub for dependencies:

const stub = {} as Dependencies;

export const changeQuoteCode: ChangeQuoteCode = (
    quoteCode,
    { readConverter, saveConverter }: Dependencies = stub
) => {
    // ...
};

Next Time

In this post, we designed use cases and discussed how to connect our app with the outside world without depending on third-party services.

Next time we'll talk about how to implement application ports, what the difference is between UI and infrastructure from an application core's perspective, and what to do if the outside world doesn't work the way the application wants it to.

Sources and References

Links to books, articles, and other materials I mentioned in this post.

Source code for the current step on GitHub

Books

Dependency Management

Testing, Mocks, and Stubs

Abstraction, Composition, and effects

Other Concepts

P.S. This post was originally published at bespoyasov.me. Subscribe to my blog to read posts like this earlier!

Explicit Design, Part 1. Domain Modelling

Alex Bespoyasov — Tue, 18 Jul 2023 15:22:20 +0000

Let's continue the series of posts and experiments about explicit software design.

In the previous post, we defined the principles that we will adhere to when developing the application, and the code problems we want to avoid. In this post, we will talk about what a domain model is, why it is useful, and how we can use functional programming, static typing, and DDD to simplify modeling.

We will consider how to incorporate domain constraints directly into the code and simplify its testing. We will design the data flows and transformations that are involved in application use cases, and discuss how to speak with product owners, designers, and other business people in the same language.

But first, disclaimer

This is not a recommendation on how to write or not write code. I am not aiming to “show the correct way of coding” because everything depends on the specific project and its goals.

My goal in this series is to try to apply the principles from various books in a (fairly over-engineered) frontend application to understand where the scope of their applicability ends, how useful they are, and whether they pay off. You can read more about my motivation in the introduction.

Take the code examples in this series sceptically, not as a direct development guide, but as a source of ideas that may be useful to you.

By the way, all the source code for this series is available on GitHub. Give these repo a star if you like the series!

Domain Model

To write an application, the first thing we need to do is to understand what it will do—that is, describe a set of use cases and tasks that the application will solve, as well as various rules and constraints of its domain. In the Domain-Driven Design methodology, such a set of knowledge is called a domain model or domain.

Next, we will try to design a converter and describe its model in terms of types and functions. You can find the final result and source code for all examples in this post on GitHub.

Benefits of Modelling

The main goal of a domain model is to help us deal with the complexity and chaos of the real world. The model is such a scoped “snapshot of reality” that we can put in our heads and express in code.

Because the model is always simpler than reality, it includes not all the details of the domain, but only those that we consider important. And the first step in designing is to understand what details we want to include in the model.

Researching the Domain

Scott Wlaschin, in the book “Domain Modeling Made Functional,” suggests thoroughly researching the domain as the first step in modeling. The book suggests interviewing people who are not involved in the code but understand the domain we want to describe. These people could be, for example, product owners, UX designers, or business clients.

The goal of the surveys is to discover and formalize as many rules and constraints as possible that govern the world we are modeling. For example, before developing a converter, we can ask:

Between which currencies will we perform the conversion?
What level of accuracy do we want to see in the calculation?
Where do we get quotes from? How often do they change?
Can the user change the calculation currencies?
How do we want to work with “negative values”?
...And so on.

Sometimes, in the surveys, we may come across “contradictions” or “inconsistencies.” This is a sign that we have not fully understood the details of the domain, and we should ask many clarifying questions. We should not be afraid to ask “stupid” questions because our view of the world may differ greatly from the product owner's or client's.

The more edge cases and “contradictions” we find through surveys, the more correct our understanding of the domain will be. And the more precise the understanding, the fewer mistakes we will make in modeling, and the fewer problems we will have in developing the application.

Details and Limitations

On the other hand, it's also not worth over-saturating the model with unnecessary or insignificant details. The simpler and the more compact the model, the easier it is to detect errors and inconsistencies with reality.

Our task is to extract as much information as necessary to start describing the domain rules. Over time, we will supplement and refine the model by working on its various parts.

Moreover, some details of the domain we will not include in the model at all. For example, in the converter, we will not include details on how currency quotes are set. It's important for us only where we get them from and in what form we will receive them. Such details are useful to know and consider but not necessarily to reflect in the code to avoid cluttering it.

Eric Evans' book “Domain-Driven Design” and Scott Wlaschin's “Domain Modelling Made Functional” are good resources on choosing which details to include in the model and which to omit.

Nuances of Modeling

It is worth noting that not every application necessarily requires a rich domain model. If we are building a simple CRUD app, there may not be complex business logic involved. The functionality of such an application would be limited to server requests and displaying received data on the screen, and it may not be necessary to distinguish a separate model.

Application Core

In many architectural styles, such as ports and adapters or clean architecture, the domain model is at the center of the application—in the so-called core. In addition to the domain, it contains code for use cases and specifications for how to “connect” these use cases with the real world (browser, third-party APIs and libraries).

We will use this metaphor and describe the converter's business logic as such an “application core.”

Assuming that we have already researched the domain and have answers to the questions from the above list, we can begin designing the model once we have an understanding of the domain.

Processes as Types

The domain model of the converter is not very large, and based on the answers to the questions above, we can roughly imagine how it will work.

We can imagine that when entering the value of one currency, it calculates the value of the second relative to known exchange rates. Ultimately, we will express these transformations as functions, but now it is too early to write functions. First, we will write a draft model in types and signatures.

The benefit of initial type-driven design is that types are easier and cheaper to modify than ready-made function code. At the same time, such a model still helps to understand the behavior of the system and even identify errors or missing data, to ask more clarifying questions. Each clarification will change the types of the model and capture more knowledge about the domain.

Then, when we see that the model in types is sufficiently elaborated, we will start implementing it in functions.

We will use such an approach with a separation into a “design level” and an “implementation level” quite often. For example, we will use it when composing features and the application as a whole, when designing use cases, and even when writing tests.

Let's try to model the processes through which data passes in the converter. The first such process is determining the exchange rate for the selected currency pair. We will need to obtain quotes for all currencies, as well as the codes for the base and quote currencies, and then retrieve their exchange rate from the quotes:

The second process is calculating the value of the quote currency based on the value of the base currency. For this, we need the exchange rate of the selected currency pair and the value of the base currency:

The third process is normalizing the values that we receive from the user. Our model will work not with any values, but only with a certain set. Values from such sets may have some constraints, for example, we can prohibit working with negative values of the base currency. We can also express such constraints in the model:

Data as Types

If we carefully examine the transformations we've made, we'll see that they are very similar to “function signatures.” And we can actually turn them into real functional types. For example, the definition of a currency pair exchange rate will become this type:

// domain/types.ts

type LookupRate = (rate: ExchangeRates, base: CurrencyCode, quote: CurrencyCode) => ExchangeRate;

Note that we have chosen domain-specific terms for the names of the function's arguments and result type, which we used on the diagrams.

The reason for that is we heard these terms from the product owner during our exploration of the domain. This way, we understood that these were the terms used by “business people” to describe the system. The language that contains these terms in DDD is called ubiquitous language, and we will use it in the code.

The purpose of ubiquitous language is to reduce losses when translating from the language of the business to the language of development. By using it, we “summarize” what we learned during our exploration directly as function signatures. This way, we reduce the probability of errors due to incorrect terms.

Since we do not yet have the types ExchangeRates, ExchangeRate, and CurrencyCode, TypeScript will complain. We will fix this by declaring type aliases for these types:

// domain/types.ts

type CurrencyCode = unknown;
type ExchangeRate = unknown;
type ExchangeRates = unknown;

For a first step, this is quite sufficient. Since our goal in the early stages is to validate the domain representation, aliases help express thoughts more formally, but still in a relatively free form that can be easily changed. (We can change the type name, add or remove an argument from the function signature, and we won't need to update a lot of code.)

We should note that at this stage we are not making any abstractions, but on the contrary, we are describing types as fully and explicitly as possible. The decision to generalize any data or functions will be made later, when we have enough information about how the project actually works—when the model becomes more accurate.

When we have more knowledge about the data structures we will be working with, we can return to aliases and refine the types. For example, when we have learned all the available currencies in the application, we can replace the CurrencyCode type with the actual one instead of unknown.

// domain/types.ts

// For example, we found out that there will be
// 5 currencies available in the application.
// Then we can describe them as a union type of string literals:

type CurrencyCode = 'RPC' | 'IMC' | 'WPU' | 'DRG' | 'ZKL';

As we further explore the domain, we may discover that an exchange rate is a ratio between two numerical values and does not have any units of measurement. Then, we can narrow down the type ExchangeRate by specifying that it is a decimal number:

// domain/types.ts

type ExchangeRate = Fractional;

// The Fractional type can be either a plain number
// or a special type that validates its values on creation.
// For now, we'll just express it as a number and come back later if needed:
type Fractional = number;

Aliases are not the most reliable way to introduce such constraints in TypeScript, but they are the most convenient for the design stage. We will talk about other ways to ensure types, such as branding, later, but for now, aliases will suffice.

Next, we can define the exchange rates themselves. Let's say that for each base currency, rates describe a pair of currencies and their exchange rates. Then we can express quotes as an object, where the keys are quote currency codes and the values are their exchange rates:

// domain/types.ts

// Set of exchange rates between the current base currency
// and all of the quote currency options:

type ExchangeRates = Record<CurrencyCode, ExchangeRate>;

Each type refinement captures more information about the domain in the signatures. This provides several benefits:

We can already search for errors in the model or places where we lack information about the domain. When we formalize an idea in some way, we have to hold less information in our heads, which improves our attention, and we can more easily notice inconsistencies in the model.
Code density increases because we express some information about the domain through types, and therefore we can add more details in the implementation.
Fixing the model at this stage is very cheap because there is still no implementation, and we can “fine-tune” our understanding of the domain by simply changing the names of types and data structures.

Domain Constraints as Types

The purpose of the model is to describe how the domain works, and an important part of such a description is its constraints. Suppose we have learned that in our converter, the base currency will always be the same—Republican Credit (RPC).

The current model does not take into account this constraint, for example, the LookupRate function accepts any currency as the base one:

// domain/types.ts

type LookupRate = (
    rate: ExchangeRates,

    // Can use any of 5 available currencies:
    base: CurrencyCode,
    quote: CurrencyCode
) => ExchangeRate;

On one hand, this is a “generalization” for the future if we suddenly allow choosing the base currency for calculation. But on the other hand, we now lose an important difference between the base and quote currencies.

The missing difference expresses constraints on the number of possible values for each of the currencies. According to it, the base currency can only have one value, while the quote currency can be any of 5.

The difference in possible values tells us that we actually have 2 separate types. We can express this difference by dividing the CurrencyCode type into two separate ones:

// domain/types.ts

type BaseCurrencyCode = 'RPC';
type QuoteCurrencyCode = 'RPC' | 'IMC' | 'WPU' | 'DRG' | 'ZKL';

Now, the constraint and difference in the behavior of different currencies are visible directly in the types of their possible values. The potential for misunderstandings and hidden details decreases, and the model itself becomes more precise. This is especially important when other developers study the project in the future, for example, during onboarding.

Ideally, we should also mention the reason why we have only one base currency. If we can express the reason in types or code (for example, using variable names or types), it's better to do it right there. Otherwise, we can specify this reason in the project documentation.

After refining the model, we can see that the LookupRate type can be simplified by removing the base currency code from the arguments, as it never changes:

// domain/types.ts

type LookupRate = (rate: ExchangeRates, quote: QuoteCurrencyCode) => ExchangeRate;

Constraints in types can help “forbid” certain invalid states in the model. It is as if we take away the possibility of writing incorrect (from a domain perspective) code in the future because the type system will not allow it to compile.

Of course, this is more useful and reliable in more mature languages than TypeScript, but for expressiveness, I still recommend using this approach in TS.

Other Processes

Similarly, by exploring the domain and interviewing the product owner and other project participants, we can describe the other processes. For example, calculating the value of a quote currency relative to the base currency at a known rate will look like this:

// domain/types.ts

export type CalculateQuote = (base: BaseValue, rate: ExchangeRate) => QuoteValue;

Similarly, validating user input and converting it to the base currency value can be expressed as follows:

// domain/types.ts

export type ToBaseValue = (raw: ValueCandidate) => BaseValue;
type ValueCandidate = number | string;

...And so on until we have a more or less complete description of the domain.

Model Verification

Let's say we've gathered some number of data structures and their transformations and expressed them in types. Next, we'd like to evaluate how complete the model is and identify what further refinements may be necessary.

At this stage, it's important to identify unknown unknowns to assess whether we've included enough details in the model.

One way to validate the completeness is to compose various use cases using the types and data structures we have. For example, to convert one currency to another, we need to:

Get currency codes and base value from the real world.
Determine the current rate of the selected pair.
Calculate the value of the quote currency based on the current rate.

If we express this algorithm in signatures and types, we will get something like:

// 1. Get data from the real world:
type GetInputData = () => ExchangeRates & QuoteCurrencyCode & BaseValue;

// 2. Determine the rate:
type LookupRate = (r: ExchangeRates, q: QuoteCurrencyCode) => ExchangeRate;

// 3. Calculate the value:
type CalculateQuote = (b: BaseValue, r: ExchangeRate) => QuoteValue;

For now, we don't have any functions to communicate with the real world, so we can't model the first step, but we have successfully expressed the remaining steps of the process in types.

Currently, we assume that the input data is provided to us by some function GetInputData, which communicates with the outside world. In general, we could describe its type more precisely to take into account the data source, but for brevity, I decided to leave it out of the series. However, if you are interested in how this can be done, I recommend reading Scott Wlaschin's “Domain Modeling Made Functional.”

In the same way, we can verify other use cases. If we have enough created types and no additional questions arose during the process, we can start implementing the model in functions.

Functional Implementation of the Model

When we have expressed part of the domain in types and checked the model for consistency, we can proceed with the implementation. Note that implementation is not the “next step” but part of the design. This means that if we have questions about how the domain works during the implementation, we should stop and ask the product owner questions to clarify the model.

Design and development is an iterative process. It's okay to go back a step or two sometimes to improve the model and add newly discovered information. In the future, we'll stop paying attention to this, but let's stipulate that it's normal to make model refinements now and then even during later steps.

We will take advantage of the fact that TypeScript is multi-paradigm and write a model implementation in near-functional style. The code will not be purely functional, but we will try to gain the most out of the basic concepts of FP: pure functions, partial application, functional composition, and closures.

This approach on the one hand will not be overly complicated (we won't even mention monads 🙃), and on the other hand we will get high testability, debuggability, make the model explicit and composable.

Pure Functions

One of the basic concepts of the functional approach is pure functions. Pure functions are functions that do not produce side-effects and always return the same result given the same arguments.

One useful property of such functions is that they force us to keep the data and its transformations separate. The data and the code change with different rate and mixing them makes the system non-resilient to changes. When they are separated, however, it becomes easier to update the code; the transformations themselves become explicit, and the stages that the data goes through become visible.

By the way, the separation of data and actions is one of the basic concepts not only in FP, but in DDD, too.

To understand the power of pure functions, let's look at an example. Below, the result of the createBaseValue function depends only on its argument, and we can be sure that if we pass the same value we will get the same result:

export const createBaseValue: ToBaseValue = (raw) => {
    const candidate = Number(raw);
    return Number.isNaN(candidate) ? 0 : Math.abs(candidate);
};

// Strictly speaking, the result is also affected
// by the `isNaN` and `abs` functions,
// but for simplicity, we assume that they are also pure.

Being sure we get a certain result helps abstract away the less important details and focus on higher-level processes. In our case, the createBaseValue function sort of encapsulates the details of how to convert a raw value to a domain type.

This gives us the ability to build more complex processes using these functions as components of such processes:

const rawValue = '42';
const baseValue = createBaseValue(rawValue);
const quoteValue = calculateQuoteValue(currentRate, baseValue);

// Data goes through several stages:
// RawValue -> BaseValue -> QuoteValue
// "42"     -> 42        -> 1.46

// We can think of this sequence
// as a single stand-alone process.

And since we are sure that with the same arguments we will get the same result, we can replace the part of the process by the result of the function calls that make up the process:

// Replace first 2 steps with a value:
const baseValue = 42;
const quoteValue = calculateQuoteValue(currentRate, baseValue);

// We get the same result, because the `createBaseValue` function is pure
// and we can replace its call with the result.

This property is called referential transparency, and it helps to focus on the parts of the process that interest us by abstracting out the details of the previous parts:

So referential transparency and pure functions make the domain model easy for verifying, testing, and visualizing data flows.

Data Consistency

We can use referential transparency and the convenience of pure functions to formalize invariants of the model—rules and properties of data that must always be met.

For example, the function createBaseValue guarantees that the output value will always be a number greater than or equal to 0. This output value property is an invariant.

The function tells us that values of type BaseValue can only be numbers within a certain range ([0, Infinity)), and all values “from the outside world” have to go through this “filter” before they get into the domain model. Invariants help keep the data inside the model internally consistent.

The desire for consistency, by the way, also forces us to look for errors in the model early in the design process, when it's still relatively cheap to make changes to the code.

Since the value normalization rule is contained entirely inside the createBaseValue function, the rest of the model code doesn't have to worry about the validity of the BaseValue type—that's taken care of by the factory function createBaseValue. Such a contract between modules helps separate the obligations and limit future code changes.

The rest of the code knows that if the value type is BaseValue, then the value came out of the createBaseValue function and is by definition valid. Other functions can use that value, relying on that fact and not checking the value again. As a result, the validation rules are collected in one place and not scattered throughout the model code.

Contracts between modules are the basis of low coupling. We'll talk about coupling and cohesion in detail in the future posts.

Of course in TS, we can bypass such restrictions and assign the BaseValue type on any value. Then the contract will be broken and no guarantees can be given to other functions. There are various ways to deal with this, but for the sake of brevity we will consider the case where values of type BaseValue appear only from the factory.

Encapsulation

Another example of a contract and declaring rules would be the lookupRate function. This function contains a rule for searching a rate between a pair of selected currencies:

export const lookupRate: LookupRate = (rates, against) => rates[against];

This function frees the others from the need to know where the rate value of the selected currency pair comes from. The other functions can rely on a guarantee (contract) that the result of calling lookupRate will always be a correct and valid exchange rate.

The lookupRate function guarantees that the exchange rate will be valid even if the ExchangeRates structure changes. It will take care to correctly get the right data out of ExchangeRates and provide it as a result.

This behavior, when the module guarantees the validity of its data and best knows how to provide it, is called encapsulation. It allows us to limit the propagation of code changes throughout the code base.

For example, if we change the ExchangeRates type, the code updates will stop at the boundaries of the lookupRate function:

type ExchangeRates = Record<CurrencyCode, ExchangeRate>;
type UpdatedExchangeRate = List<[CurrencyCode, ExchangeRate]>;

// Before changes we extracted data this way:
const lookupRate = (rates, against) => rates[against];

// After—slightly differently:
const lookupRate = (rates, against) => rates.find(([code, rate]) => code === against).at(1);

// But all the code that relied on the `lookupRate` call
// is unchanged because the change effect
// is scoped by the `lookupRate` function:
const currentRate = lookupRate(exchangeRates, 'IMC');

This way the rest of the code can be sure that as long as it correctly calls the lookupRate function and passes it all the necessary arguments (it does its part of the contract), as a result it will get a valid exchange rate for the current currency pair (the lookupRate function will do its part of the contract).

Intrinsic Testability

We mentioned earlier that pure functions help make the model easy to test. This comes from the assumption that pure functions are intrinsically testable—they don't require complex test infrastructure, their tests don't take long to set up, and they only need input data and the expected result to run.

For example, to test createBaseValue we can write this test:

describe('when given a number-like value', () => {
    const expected = 42;
    const cases = [42, -42, '42'];

    it.each(cases)('returns the domain base value', (value) => {
        const result = createBaseValue(value);
        expect(result).toEqual(expected);
    });
});

This test is easy to understand, easy to write, and it fits perfectly into the AAA (Arrange, Act, Assert) paradigm:

describe('when given a number-like value', () => {
    // Arrange:
    const expected = 42;
    const cases = [42, -42, '42'];

    it.each(cases)('returns the domain base value', (value) => {
        // Act:
        const result = createBaseValue(value);

        // Assert:
        expect(result).toEqual(expected);
    });
});

All this makes testing pure functions straightforward. We don't need to think about what and how we're going to test, because pure functions have only one place we can test—the returned result.

Simple tests are easy to support and more resistant to changes because a simple test infrastructure has fewer points of failure. It's less likely to need fixing after library updates, we less likely will need to rewrite the tests themselves because it's harder to “break” input data than, for example, mocks.

For unit testing, pure functions are also great because simple tests don't require a lot of resources. Since we don't need to create providers, renderers, wrappers, mocks, etc., pure function tests will be on average faster.

Finally, pure functions are convenient to test not only for happy path, but also for failure cases. For example, for createBaseValue we can write such a set of non-happy-path tests:

describe('when given a non-number value', () => {
    const cases = ['string', '42n', NaN, [], null, undefined, {}];

    it.each(cases)('returns 0 base value', (value) => {
        const result = createBaseValue(value);
        expect(result).toEqual(0);
    });
});

Test-Driven Development

Referential transparency, intrinsic testability, contracts on the behavior, and types for data and processes in the domain allow us to use another tool in modeling—Test-Driven Development, TDD.

TDD is a methodology where we first write tests for the function we are going to implement, and only then the function itself. The idea behind TDD is to take small steps and develop the code in short iterations, developing it from the simplest implementation to the most complex version.

I won't describe the approach in detail in this post, but if you're interested in reading about TDD in detail, I recommend checking out my post about TDD and my Testing React Applications talk. I also recommend reading book by Vladimir Khorikov about unit testing.

I understand that not all developers like to work with TDD, and that's fine; I'm not going to “sell” this methodology to anyone. My goal in this post is to show how to use TDD as a design tool so that you have more information to decide whether to use it.

For this purpose, let's try to write a function that implements the CalculateQuote type by TDD. We can start by describing the boundaries of the functionality we are going to implement with .todo():

// Describe what functionality we need in the end:

describe('when given a base value and the current rate', () => {
    it.todo('returns the correct quote value');
    it.todo('should have a precision of two decimal places');
});

At this point, we may have additional questions about how the model works. For example, how to handle edge cases or what data we are ready and not ready to accept.

In fact, the new questions are a good thing, because by formalizing through .todo a scope of functionality, we refine the model. Each question about system behavior adds more real-world knowledge to the code, making the model more accurate. At the same time, we don't have the code of the function itself yet, which means it's cheap to make changes to the model.

When we have decided how the calculateQuote function should behave, we can write the first test. Let's describe the behavior of the function with the correct input data:

type TestCase = {
    base: BaseValue;
    rate: ExchangeRate;
    expected: QuoteValue;
};

// ...

it.each<TestCase>([{ base: 10, rate: 1, expected: 10 }])(
    'returns the correct quote value',
    ({ base, rate, expected }) => {
        const result = calculateQuote(base, rate);
        expect(result).toEqual(expected);
    }
);

Next, we need to make sure that the test fails. This is important because only a failing test really checks something, and we want to make sure that our tests are not useless.

Then we have to check the reason why the test is failing. Right now, the test is failing because the calculateQuote function is undefined. That's not what we expect in a test. So let's add a function and make sure the test crashes for the reason we want:

const calculateQuote: CalculateQuote = (base, rate) => 42;

Then we'll get:

19|   ])("returns the correct quote value", ({ base, rate, expected }) => {
20|     const result = calculateQuote(base, rate);
21|     expect(result).toEqual(expected);
  |                    ^
22|   });
23|

- Expected   "10"
+ Received   "42"

Now that we have seen that the reason for the failure matches our expectations, we can proceed with the real implementation. Checking the failure reason is important because we want to make sure that tests validate our expectations of the model (rules, invariants, and data transformations). When we make the test fail for the reason we want, we make sure that the test validates the correct expectation.

Generally speaking, according to TDD the first test and its implementation should be as simple as possible so that the development cycle is short—no more than 5 minutes. In this post I decided to cut corners a bit and skip this aspect for the sake of brevity. But again, I'll leave additional material on this topic at the end.

Next we can write the actual implementation:

const calculateQuote: CalculateQuote = (base, rate) => base * rate;

When the first test passes, we can take time to refactor the code or tests and, for example, add other test cases to capture a little more behavior:

it.each<TestCase>([
    { base: 10, rate: 1, expected: 10 },
    { base: 10, rate: 2, expected: 20 },
    { base: 10, rate: 4.2, expected: 42 }
]); // ...

After that we make sure that all the written tests pass. This is also an advantage of TDD, because each step of development is secured by already written tests. (It's clear that the quality of this “insurance” depends on the quality of written tests, but that's a slightly different question).

Next, we can describe the tests for the second case, to make sure that the function rounds fractions to 2 decimal places:

it.each<TestCase>([
    { base: 10, rate: 1.12, expected: 11.2 },
    { base: 10, rate: 0.72, expected: 7.2 }
])('should have a precision of two decimal places', ({ base, rate, expected }) =>
    expect(calculateQuote(base, rate)).toEqual(expected)
);

We make sure that the tests fall because of rounding. After that we write the implementation:

const calculateQuote: CalculateQuote = (base, rate) => Number((base * rate).toFixed(2));

...And we check that all the tests pass. In the same way we can describe non-happy-path cases for this function and design other aspects of its behavior.

Function Composition

As we mentioned earlier, a useful property of the functional approach in modeling the domain is that it encourages us to separate data from its transformations.

We can see this difference just by looking at our model types:

// Data:
type BaseCurrencyCode = 'RPC';
type QuoteCurrencyCode = 'RPC' | 'IMC' | 'WPU' | 'DRG' | 'ZKL';
type ExchangeRates = Record<QuoteCurrencyCode, ExchangeRate>;

// Data Transformations:
type LookupRate = (r: ExchangeRates, q: QuoteCurrencyCode) => ExchangeRate;
type CalculateQuote = (b: BaseValue, r: ExchangeRate) => QuoteValue;

This separation helps us to make explicit all the stages through which the data pass. When all actions are visible and their results are predictable, the model contains fewer hidden details that can affect the final state of the data.

Domain processes become sequential sets of actions, and we can visualize their results (or even “play in our heads”) and predict what the data will look like at the end:

const rawValue = '42';
const baseValue = createBaseValue(rawValue);
const quoteValue = calculateQuoteValue(currentRate, baseValue);

// RawValue -> BaseValue -> QuoteValue

It is easy to compose such processes into more complex functions:

function workflow(rawValue, exchangeRates) {
    const baseValue = createBaseValue(rawValue);
    const currentRate = lookupRate(exchangeRates);
    const quoteValue = calculateQuoteValue(currentRate, baseValue);
    return quoteValue;
}

...But the whole transformation remains understandable and testable, because all its steps are explicit.

In this approach, we don't change the state around the function, but instead return an updated data, so the final result cannot be influenced from the outside. This way we eliminate the influence of side-effects on the result.

In the future, we will use functional composition to assemble use cases and extract the similar (or generalized) actions into separate functions.

At this stage, however, it's too early to make any generalizations. First we should look at how the data actually behaves: what data changes at the same, how often it happens, and for what reasons. Once we discover behavior patterns, we can conclude if we need to generalize anything.

Next Time

In this post we designed the domain model of the application and laid the groundwork for future use cases.

Next time we'll design and implement these use cases, describe specifications for how the outside world should communicate with the application, and talk about dependencies inside and outside the application.

Sources and References

Links to books, articles, and other materials I mentioned in this post.

Source code for the current step on GitHub

Books

Domain Modelling

Architecture, Contracts, and Patterns

TypeScript & Static Types

Functional Programming

Testing

Methodologies & Processes

P.S. This post was originally published at bespoyasov.me. Subscribe to my blog to read posts like this earlier!

Explicit Software Design Series

Alex Bespoyasov — Tue, 18 Jul 2023 15:22:00 +0000

Sometimes, I read books about software design and development. Usually, they are about “enterprise software” and rarely discuss their applicability in web development. However after reading them, I'm always interested in whether the techniques from these books can be applied to my daily tasks, whether they are profitable and justified.

This series of posts is an experiment where I want to test it. I will try to design and write an application taking into account the recommendations and rules that I have read about in various resources over the past years.

Some of these principles I have already applied in production, some—only in pet projects, and some of them—not at all. I'm interested in gathering everything in one application and seeing how different buzzwords from the programming world interact with each other.

Let's clarify from the start:

This is not a recommendation on how to write or not write code.

I am not aiming to “show the correct way of coding” because everything depends on the specific project and its goals. My goal is to try to apply the principles from smart books in a frontend application to understand where the scope of their applicability ends, how useful they are, and whether they pay off.

Take the code examples in this series not as a direct development guide, but as food for thought and a source of ideas that may be useful to you.

Constraints and Limitations

We will be writing code “by the book” following the rules from different sources. This means that some solutions will be intentionally “too clean” even if it doesn't make sense from a pragmatic standpoint. Although I will mark such places in the text, try not to forget that this series is an experiment and the code might feel unnatural.

When using different techniques, I will refer to specific authors and their works. Sometimes I will provide comments with my evaluation, but for the most part, I will try to refrain from making judgments about whether something should be used or not.

On the contrary, we will try to mix in as many ideas as possible to test them. Most likely, as a result, we will write code that will not look like “standard” React application code, but in it, we will try to find connections and parallels with modern development patterns.

About the series

In this series, we will be building a fictional currency converter application. Each post will focus on a specific topic, and the plan and content will be as follows:

Introduction, assumptions, and limitations
Modeling the domain
Designing use cases
Describing the UI as an “adapter” to the application
Creating infrastructure to support use cases
Composing the application using hooks
Composing the application without hooks
Dealing with cross-cutting concerns
Extending functionality with a new feature
Decoupling features of the application
Overview and preliminary conclusions

In addition, I have an idea to write a few related posts on similar topics:

Applicability of everything described with frameworks (for example, Next.js)
Improving type safety with type branding (for example, for DDD)
Code splitting, routing, and performance (for example, using Suspense and use)
Functional error handling (for example, with Result<TOk, TErr>)
Applicability with other UI libraries (for example, Solid or Svelte)

...But for now, I'm not sure if these topics will be interesting and I don't know how much time they will take. If you're interested in reading about these topics as well, ping me in the comments! 👋

Sample Application

As an example, we will write a converter for currencies from the “Star Wars” universe:

The converter will convert Republican credits (RPC) to Imperial credits (IMC) and some other currencies from the lore of the universe. We will come up with the “exchange rates” ourselves and take them from a simple JSON server. We will probably save fresh exchange rates to local storage, and closer to the end of the experiment, we will expand the application with a new feature.

But the App is So Small!

The principles we will be discussing are indeed not necessary for a prototype or a small application. However, I chose a small application for two reasons:

The smaller the application, the easier it is to focus on the technical aspects and development convenience.
I am lazy and didn't want to write a large application in vain, but didn't have any ideas for a useful open-source application.

Perhaps the benefits would be more visible in a larger application, but I decided that a simple converter would be sufficient for the experiment. If you have any ideas on how to improve this, please, open an issue or PR on GitHub. Let's discuss it! 👋

Source Code on GitHub

We will develop the application step by step. The results of each stage of work can be found on GitHub. Each post will refer to a separate folder in the project repository, where you can see how everything is organized and play with the code.

Application Functionality

In the posts, we will assume that we have can talk directly to the product owner and we know what functionality we want to see at the end of the development. We will consider the following use cases:

Entering an RPC value that automatically converts the value to a quote currency.
Choosing an alternative quote currency with automatic conversion of its value relative to RPC.
Updating quotes based on data from the server and saving this data locally on the device.
Simple user action analytics, but probably not in the beginning of the development.
In the future, we also plan to add another feature that isn't known for now.

Problems We Want to Avoid

In the books that we will be referring to, besides the rules and recommendations, there are also counterexamples. They describe the problems that arise if the rules are not followed. We will try to avoid all of these problems and see if we can do this by following the rules from the books.

The problems we aim to avoid are:

Technical Details Over Features

The project structure should tell about its tasks and independently show what the application contains, namely features and use cases. Technical aspects of the project should not overshadow the goals and essence of the application.

Ideally, the project should help to:

Simplify onboarding by guiding new developers and allowing them to dive into the code gradually.
Speed up the search for code that is responsible for a specific part of the application.
Add and remove functionality without the need to change the entire application.
Keep in mind only the amount of information needed to solve a specific task at a given moment.
Speak the same language with product owners and lose less in translation from the language of business to the language of development.

High Coupling and “Ripple Effect” of Changes

Parts of the project should be able to evolve independently, and development of different features should be realistically divided among different people or teams. Parts of the application should be removable without the fear of breaking others.

The spread of changes throughout the codebase should be limited to the specific function, module, or feature where the changes were required initially. Unrelated code should not be changed.

If requirements are driven by the business, they should take priority. For example, if a feature does not bring profits and only consumes resources, it should be easy to completely remove it to avoid maintaining it. Features should be easy to scale or even extract as separate independent services or applications.

Unclear Dependency Direction

The interaction between parts of the project should be clear and understandable. Data flow should be controlled, data transformations and stages of these transformations should be explicit.

Making changes to the code should not be scary. We should understand which parts of the code will be affected by a specific change. Low-level code should not affect the design of user scenarios or the development of the project as a whole.

Leaking Abstractions and Unclear Responsibilities

The code and dependencies involved in each specific task must be explicit. Code that is not needed in the task should not be used and run.

Third-party tools and auxiliary libraries must have a clear scope and boundaries. The amount of code related to them and their influence on the project must be limited and fit in the heads of developers.

The amount of implicit input data for a function or module should be minimal. The amount and size of data, resources, and dependencies that are involved should be trackable and measurable so that we can control their growth and consumption. Sudden and disproportionate “spikes” in these resources should be easily visible.

Urge to Make Decisions

A project should not require us to make “big decisions” until we have studied the domain, constraints, and business priorities.

We want to understand what tools we should integrate into the project. It should be clear which tools fit our task, what the risks of using them are, and what degree of integration will be justified. Tooling should not dictate the principles of work and create unreasonable restrictions for business tasks.

Early on, we want to avoid unnecessary generalizations. Principles and rules should be worked out evolutionarily, in a competitive environment, based on the benefits they bring.

Notice that we're not talking about “forgetting about tools”. We're talking about buying more time to learn about the project and its limitations.
Requirements in scaling, concurrent development, or infrastructure complexity are hard to predict in advance, but even harder to change post-facto.
So we want to gather as much real-world data as possible before making big decisions.

Brittle Tests

Tests should catch regressions and not hinder development. It is desirable to avoid “brittle tests,” “test friction,” and “test-induced damage.” Tests should be resilient to refactoring and extending functionality.

There should be no code that is unclear how to test. Each part of the project should solve a clearly defined task, and the result should be easy and obvious to test.

Business Logic Mixed with Infrastructure Code

Infrastructure code (“glue” that holds everything together) should not intertwine with business logic (which contains ideas that bring money).

Business Logic Mixed with Cross-Cutting Concerns

Adjacent tasks like analytics, internationalization, performance profiling should also not affect business logic code unless justified by use cases.

Development Principles

All of the problems listed above can be reformulated as principles that we will adhere to during design and development:

The main part of the application should be the business logic.
The project structure should reflect the essence of the application.
The influence of infrastructure, UI, and adjacent tasks should be minimal.
Code should be easy and clear how to test.
Modules should be as independent as possible.
The code should not force making serious decisions at early stages.

We will discuss each of these principles in the next posts and test them in practice.

Next Time

Today we described the constraints, assumptions, goals, and principles that we will use going forward. In the next post, we will begin designing the application using these principles and write a domain model for the currency converter.

We'll see how functional programming, static typing, and DDD help us with the design stage. We'll consider how to incorporate domain constraints directly into the code and how to simplify testing of the domain model. We'll design the data flows and transformations that participate in the application use cases and discuss how to speak with product owners in a common language.

Sources and References

Project on GitHub (will be updated as we go)
Repository with my blog
Blog posts with book summaries
Currencies from the lore of “Star Wars” 🙃

P.S. This post was originally published at bespoyasov.me. Subscribe to my blog to read posts like this earlier!

My Experience with Svelte and SvelteKit

Alex Bespoyasov — Tue, 29 Nov 2022 12:20:01 +0000

Recently, I launched a web version of my book “Refactor Like a Superhero”.

To build it, I used SvelteKit. In this post, I want to share my experience with Svelte and SvelteKit, and explain why I liked this technology so much.

Why Svelte

When I thought about building a web version of the book, I knew I would need to choose a tech stack. I wanted something simple, lightweight, and fast.

Before, I already had projects written in React with Next and some written in vanilla technologies, and I wanted something simpler.

For this project, I felt like React with Next was going to be an overhead: too heavy, too much stuff I would not use, and too strong a commitment to follow every major version bump.

On the other hand, vanilla technologies require infrastructure: some builder with Gulp, for example, that I would need to set up manually.

Fortunately, I wanted to try Svelte for some time and heard many good reviews about it, so I decided to use it for this project.

“It Just Works”

I can describe the main expression from SvelteKit in one phrase: “Wow, it just works.”

For the whole time I have been building the app, I felt like any problem I came up with was already solved, and I just needed to look at the docs for the solution.

For instance...

Styles

Let's start with styles because those are one of my main pains with React ecosystem.

In React, there is no obvious or standard way to use styles. There are many options like CSS-in-JS (with or without runtime), CSS modules, style attribute, global CSS, etc.

In Svelte, on the other hand, you've got a built-in way to handle style—the style tag.

For example, here's the logo component from the book's source code:

<a href="/" class="logo" aria-label="Logo">
  <span aria-hidden="true">🧑‍💻 🦸</span>
</a>

<style>
  .logo {
    font-size: 3rem;
    line-height: 1;
    text-decoration: none;
  }
</style>

No need for additional infrastructure setup, “it just works.”

The styles are scoped by default, so I don't need to worry about isolation—safe defaults for the win. There's a way to escape the scoping if you want to, of course, but by default, the main issue with styling is solved beforehand.

Prerendering and SSG

The second thing is easy prerendering and SSG. To turn prerendering on, in most cases, you'll need one line of code.

Not all pages are suitable for it, but in my case, I had the whole site prerendered out of the box with no sweat.

By default, the prerendering starts with the root path of your site “/.” In my case, I needed to start not from the root but from 2 inner paths: “/en” and “/ru.”

I expected to waste hours trying to fix this, but SvelteKit's docs already had the solution. There's entries setting for the prerendering that solves that problem.

It felt like SvelteKit foresaw the problems I could face and carefully solved them beforehand. “Just works.”

For SSG, by the way, there's the static adapter. I haven't tried it yet but got plans to do so.

...And, well, I have a hunch that I'll have the same feeling of “just works” again.

Size and Speed

With Svelte, my whole application page (including routing, event handling, localization, prerendering, etc) is less than React alone 😅

(You could also totally remove JavaScript from the final build in some cases. I want to try it too.)

At the same time, SvelteKit is really fast. It uses Vite under the hood, and it's just ridiculously fast. I didn't have to “wait until it recompiles” to see the results of my changes like I need with Next, for instance.

I've got another project similar in complexity but written in React and Next. And I've got to say SvelteKit is much faster 😅

Platform Features

I really like how SvelteKit didn't try to invent the wheel with route transitions. We can use good-ol <a> tag to navigate between pages. No framework-specific stuff, just HTML, “just works.”

The same goes for the “form actions”, which are basically seamless API controllers. It isn't a unique feature, many frameworks have similar stuff, but I like how SvelteKit emphasizes the web platform features like standard request and response interfaces.

Amount of Code

The next thing is reactivity. I'm not really a fan of two-way data binding because I had a hard time debugging some stuff back in the day. But now I slowly change my mind.

It just takes less code to implement a feature with Svelte than with React. Just compare the amount of code needed to create a simple login form.

With React:

import { useState } from "react";

export const LoginForm = () => {
  const [email, setEmail] = useState("");
  const [password, setPassword] = useState("");

  return (
    <form>
      <input
        type="email"
        name="email"
        value={email}
        onChange={(e) => setEmail(e.currentTarget.value)}
      />

      <input
        type="password"
        name="password"
        value={password}
        onChange={(e) => setPassword(e.currentTarget.value)}
      />

      <button>Submit</button>
    </form>
  );
};

...And with Svelte:

<script>
  let email = ""
  let password = ""
</script>

<form>
  <input 
    type="email" 
    name="email" 
    bind:value={email} 
  />

  <input 
    type="password" 
    name="password" 
    bind:value={password} 
  />

  <button>Submit</button>
</form>

Much more concise, compact, and declarative.

Accessibility

Speaking about safe defaults, Svelte has the accessibility linting built-in.

There are some obvious rules like “don't forget alt for images,” but also more nuanced ones like role and DOM structure checks.

Conclusion

So far, I really enjoy building the app with Svelte and SvelteKit. The process is much simpler and takes less time.

I'm not completely sure yet if Svelte can be used for large apps but for medium-sized apps and simple, mostly-static ones, it definitely is a good choice.

But What About Drawbacks?

Svelte has something I can rant about, too 😃

But I left those for another post and another time. Subscribe, and stay tuned!

DEV Community: Alex Bespoyasov

Explicit Software Design. Preliminary Conclusions

Created Application Analysis

Features Slices Seem Beneficial

Trade-Offs Everywhere

“Almost, but not Quite”

Constant Battle with Entropy

Excessive Purism Costs Money

When It Might Be Useful

Experiments with Code

Legacy Code Exploration

Long-Living Side Projects

Framework Supports the Idea

When It's Harmful

Project Doesn't Need It

Prototypes and Simple Applications

Resources Already Allocated

Approach Contradicts Accepted Rules

Benefits Smaller Than Costs

Real-Life Examples

Future Posts?

Sources and References

From My Blog and Projects

Other Resources

Explicit Design, Part 9. Decoupling Features with Events

Vertical Slices Reviewed

Coupling via Adapters

Message Bus

Decoupling Features

Subscription to Events

But isn't it... Redux? 🤨

Events and DDD

Next Time

Sources and References

Architecture and Micro Frontends

Messaging and Messaging Patterns

DDD and “Dogmatism”

Other Topics

Explicit Design, Part 8. Adding New Feature

Domain Model

Implementing Use Case

Services and Output Ports

UI and Input Port

Cross-Cutting Concerns

Using New Feature

Vertical Slices

Feature Communication

Direct Communication Example

Coupling via Ports

Adapter to Feature? 🤨

Adapter Registration

Next Time

Sources and References

Isolation, Coupling, and Cohesion

Architecture and Patterns

Vertical Slices

Data States and Transformations

Explicit Design, Part 7. App Composition without Hooks

Problems with Hooks

High Infectiousness and Multiple Limitations

Vendor Lock-In

Implicit Dependencies and Leaking Abstractions

Complicated Mental Model

Disclaimer

Composition without Hooks

Store Service

Composition of Use Cases

Composition of Components

Composition of Tests

Exchange Rates Refresh

Other Tools

Sources and References

React Hooks and Components

State and Effect Management

Abstractions and Decomposition

Infrastructure Tools

Other Topics

Explicit Design, Part 6. Cross-Cutting Concerns and Extendable Infrastructure

Types of Code and Density

Logging and Analytics