DEV Community: Thomas Toledo-Pierre

Hexagonal Architecture in Angular - A Practical, Minimal Use Case

Thomas Toledo-Pierre — Fri, 20 Feb 2026 10:05:20 +0000

In today's article, we are gonna learn a bit more about hexagonal architecture with Angular. This article is for people who are curious about hexagonal architecture and already know about Angular.

Throught this article, we'll build a small use case. The repository with the final code can be found here

The structural Drift of Growing Angular Applications

Angular applications rarely collapse overnight. They drift.

At the beginning, the structure is clean: a component, a service, an HTTP call. The responsibilities feel obvious. Over time, features accumulate. Deadlines compress. The code adapts locally to solve immediate problems. Gradually, architecture dissolves into convenience.

Business Logic Leaking into Components and Services

Components start by handling view concerns: rendering, user interaction, state binding. Soon, validation rules appear in the component. Then conditional business flows. Then domain invariants expressed as if statements directly inside submit() methods. Services follow the same trajectory. What begins as a thin HTTP wrapper becomes a hybrid object:

Performs API calls
Transforms DTOs
Applies business rules
Makes decisions
Mutates UI-facing state

The result is not a clear separation between domain and infrastructure. It is an accidental aggregation of responsibilities. Logic is scattered. No single place expresses the business model coherently.

Tight Coupling Between UI, HTTP, and Domain Logic

When a component imports HttpClient, or a service mixes domain decisions with transport details, coupling becomes structural. Three layers collapse into one:

UI layer (Angular components)
Infrastructure layer (HTTP, storage)
Domain rules (business invariants)

This creates implicit dependencies:
Changing the API contract forces changes inside business logic.
Changing a validation rule requires editing a component.
Replacing HTTP with another transport requires refactoring core logic.

The system becomes brittle because boundaries are absent.

Difficult Unit Testing: TestBed Everywhere

Architecture reveals itself in testing friction. If validating a simple business rule requires:

Angular TestBed
HttpClient testing module
Dependency injection scaffolding
Asynchronous zone handling

then business logic is framework-bound.

Tests become slow and heavy because they boot part of Angular to verify domain behavior. The signal is clear: the framework is entangled with the core. Pure domain logic should be testable with:

Plain TypeScript
No Angular imports
No dependency injection container
No HTTP mocking infrastructure

When this is not possible, the architecture is already compromised.

Hard-to-Replace Infrastructure

The final symptom appears during change. An API evolves. A backend endpoint moves. A storage mechanism changes. A feature must support offline mode. In a tightly coupled Angular application:

API response shapes are referenced directly in components.
HTTP error handling is mixed with domain decisions.
Infrastructure details are assumed by core logic.

Replacing infrastructure becomes invasive. What should be localized changes propagate across the codebase.
The core problem is not Angular itself. It is the absence of architectural boundaries.

What is hexagonal architecure?

Hexagonal architecture, also known as Ports and Adapters, is a structural pattern designed to protect the core of an application from external volatility.

It is not tied to Angular.
It is not tied to frontend or backend.
It is a way to enforce architectural boundaries.

The core idea is simple: the business logic must not depend on technical details.

Also Called Ports and Adapters

The term hexagonal is visual. The shape emphasizes that the system can have multiple entry and exit points. The functional meaning is clearer in the alternative name:

Ports define what the core needs.
Adapters implement those needs using specific technologies.

Ports are interfaces and Adapters are concrete implementations. The Ports allow to interact with the domain and the intention, and the Adapters express how to interact with it. They implement the intention. For instance, if you have an app for managing tickets, and you have an hexagonal architecture, then you might have a Port called CreateTicketPort, another one called GetTicketPort, etc. This would work in a CRUD-heavy application, and this is why you could also have a more global Port called TicketPort.
We can even split queries and commands. A practical rule in Angular I like to follow is to start with a more global Port, that I will then split when it starts accumulating many queries or methods.
In this article let's say we have a Port for each CRUD operation. We could have:

export interface CreateTicketPort {
  create(ticket: Ticket): Promise<void>;
}

export interface GetTicketPort {
  getById(id: string): Promise<Ticket | null>;
}

export interface UpdateTicketPort {
  update(ticket: Ticket): Promise<void>;
}

export interface DeleteTicketPort {
  delete(id: string): Promise<void>;
}

Those Ports express the intention, i.e what we can do with the Domain. You can see they are still plain TypeScript. There is no sign of Angular, here. Adapters, on the other hand, can be of any implementation, in any framework/library.
In this article, we collapse CRUD ports into a single repository port for simplicity. In larger systems, you may prefer use-case-specific ports or a CQRS split.

Domain at the Center

At the center lies the domain:

Entities => have identity and lifecycle
Value objects => have no identity and are usually immutable
Business rules
Invariants => conditions that must always hold true for an entity to be valid.

For instance :

// This is an entity
// Two tickets with the same content
// will differ if they have a different id
interface Ticket {
  id: string;
  trackingId: string;
  email: Email;
  subject: string;
  description: string;
  createdAt: Date;
}

// Email is a value object
// It has immutable behaviours. It does not hold any identity in our domain
type EmailValidationError = 'EMPTY' | 'INVALID_FORMAT';

class Email {
  private constructor(private readonly value: string) {}

  static create(raw: string): Email {
    const { ok, value, error } = this.tryCreate(raw);
    if (!ok) {
      throw new Error(`Invalid email: ${error}`);
    }
    return value!;
  }

  static tryCreate(raw: string): { ok: boolean; value?: Email; error?: EmailValidationError } {
    if (!raw || raw.trim().length === 0) return { ok: false, error: 'EMPTY' };

    const normalized = raw.trim().toLowerCase();
    const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
    if (!EMAIL_REGEX.test(normalized)) return { ok: false, error: 'INVALID_FORMAT' };

    return { ok: true, value: new Email(normalized) };
  }

  getValue(): string {
    return this.value;
  }
}

The domain expresses the language of the business. It contains no framework imports, no HTTP calls, no UI references. It must be stable.

Application Layer Orchestrates Use Cases

We just saw the domain and what it was, theoretically - we will get to a concrete example further in this article. Around the domain sits the application layer. This layer defines:

Use cases
command/response models
Coordination between domain and ports

It orchestrates workflows but does not implement infrastructure details.

For instance:
It may require a repository.
It may require the current time.
It may require an ID generator.

=> It expresses those requirements as ports.

We said before that ports were interfaces, and that the core would depend on them. You can see it like that:

The core contains the domain and the application layer. The domain depends on nothing and can be pure TypeScript. The application layer exposes use cases (the core’s API) and defines ports (interfaces) for anything it needs from the outside world. Ports express contracts without committing to a technology. Adapters implement those ports and are the only place tied to technical constraints (Angular services, HttpClient, browser APIs, etc.). This lets you keep the core framework-agnostic while plugging different UI adapters (Angular, React) or infrastructure adapters around it.

Infrastructure Implements External Concerns

Infrastructure lives outside the core. It handles:

HTTP communication
Database persistence
Local storage
System clock
UUID generation

These are technical concerns. They are expected to change. The Infrastructure layer implements the ports defined by the application layer.
It is replaceable by design.

UI Is Just an Adapter

In Angular, components belong to the outer layer.
They:

Collect user input
Invoke use cases
Render results

They do not contain business rules.
Angular becomes an input/output mechanism, not the foundation of the architecture.

The Dependency Rule

The rule that enforces the structure is strict: dependencies point inward. Infrastructure depends on application and domain. Application depends on domain. Domain depends on nothing external. The domain knows nothing about:

Angular
HttpClient
Databases
REST
Browser APIs

It only knows business concepts.

This inversion is the essential property of hexagonal architecture: the framework becomes a detail. The business remains the core.

The Use Case: Create a Support Ticket

To make hexagonal architecture concrete, we need a use case that is small, realistic, and still exposes real domain constraints. "Create a support ticket" fits: it has input validation, a rate-limit business rule, persistence, and a clear outcome.

Scenario

A user opens a "Contact Support" form and submits three fields:

Subject: a short summary of the issue
Description: the detailed message
Email: the address support will respond to

They click Create Ticket, and the system returns a ticket identifier that can be displayed immediately (or used for follow-up tracking).

Business Rules

This use case enforces three rules that are common in real products:

Subject must not be empty
A ticket without a subject is not actionable and becomes noise in the support queue.
Description must be at least 20 characters
Prevents low-signal messages ("help", "bug", "it doesn’t work") that force unnecessary back-and-forth.
Maximum 3 tickets per hour per email
Rate limiting as a business rule. This avoids spam, prevents accidental loops, and protects the support system from abuse. This will be handled by the backend.
A ticket has a status: open, in progress, closed
This allows for tracking the ticket.

These rules are deliberately simple, but they illustrate the key point: the core is making decisions that should not depend on Angular, HTTP, or any storage detail.

Goal of the Use Case

The use case has a clean, deterministic contract:

Validate input (subject, description, email)
Create a Ticket domain object (with ID and timestamp)
Persist it through a port (repository abstraction)
Return the generated Ticket to the caller

This is where hexagonal architecture becomes visible: the use case defines what it needs (ports) and orchestrates the workflow, while the outside world (Angular UI, HTTP API, database) is pushed to adapters.

Project Structure

A clean hexagonal implementation in Angular is not about complexity. It is about separating responsibilities with precision.
A minimal structure for our "Create Ticket" feature can look like this:

src/
  app/
    domain/
      ports/
      entities/
      value-objects/
    application/
      use-cases/
    infrastructure/
      adapters/
    ui/

Each folder represents a distinct architectural role. The structure is intentional: it encodes dependency direction.

Setting up your project

We start by setting up a new Angular project:

# install angular CLI if you do not have it
npm install -g @angular/cli

# then create your app
ng new ticketing-app

And now, we can focus on each layer.

Domain => Business Concepts and Rules

The domain is the core.

It contains:

Entities (Ticket)
Value Objects (Email)
Business rules (validation, invariants)
Pure domain logic

Characteristics:

No Angular imports
No HttpClient
No Date generation logic tied to system APIs
No persistence awareness

The domain models the business reality. It must be framework-agnostic and stable.

So let's do it!
Create a directory in your Angular app. Under src/app, create a domain directory and, in domain, create the following sub-directories:

entities
value-objects
ports

`entities`

There goes the Ticket.ts file:

import { Email } from "../value-objects/Email";
export interface Ticket {
  id: string;
  trackingId: string;
  title: string;
  description: string;
  status: 'open' | 'in_progress' | 'closed';
  email: Email;
  createdAt: Date;
  updatedAt?: Date;
}

// We also add a convenient type for ticket creation
export type NewTicket = Omit<Ticket, 'id' | 'trackingId' | 'status' | 'createdAt' | 'updatedAt'>;

`value-objects`

In this directory, we add one files:

Email.ts

export type EmailValidationError = 'EMPTY' | 'INVALID_FORMAT';

export class Email {
  private constructor(private readonly value: string) {}

  static create(raw: string): Email {
    const { ok, value, error } = this.tryCreate(raw);
    if (!ok) {
      throw new Error(`Invalid email: ${error}`);
    }
    return value!;
  }

  static tryCreate(raw: string): { ok: boolean; value?: Email; error?: EmailValidationError } {
    if (!raw || raw.trim().length === 0) return { ok: false, error: 'EMPTY' };

    const normalized = raw.trim().toLowerCase();
    const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
    if (!EMAIL_REGEX.test(normalized)) return { ok: false, error: 'INVALID_FORMAT' };

    return { ok: true, value: new Email(normalized) };
  }

  getValue(): string {
    return this.value;
  }
}

Writing ports

Let's start by going under the src/app/domain/ports folder and, inside of it, create the following file:

TicketRepositoryPort => to create a ticket

`TicketRepositoryPort`

export interface TicketRepositoryPort {
  create(ticket: NewTicket): Promise<Ticket>;
}

You may notice that the port returns a Promise instead of an Observable: this is intentional.

A port belongs to the core of the application. The core must remain framework-agnostic. Observable is part of RxJS, which is tied to Angular’s ecosystem. If we expose Observable in the port, we introduce a framework dependency into the core.

Promise, on the other hand, is part of the JavaScript standard. It represents a single asynchronous result, which matches the nature of a use case like createTicket: execute once, wait for completion, return.

The adapter is free to use HttpClient and Observable internally. It can convert the stream to a Promise before returning to the core.
This keeps RxJS in the infrastructure layer and preserves the boundary.

An Observable becomes appropriate when the domain itself models a stream of events, not a single operation.

Examples:

Subscribing to real-time ticket updates (WebSocket, gRPC)
Listening to status changes over time
Receiving a continuous feed of notifications
Streaming live metrics or logs

In those cases, the reactive nature is part of the business requirement. The stream is not an infrastructure detail; it is a domain concept.

Use Promise for one-shot operations.
Use Observable when the behavior is inherently continuous or event-driven.

We have our Domain. For now, it's sufficient.

Application => Use Cases

The application layer orchestrates behavior.

It contains:

Use cases (CreateTicketUseCase)
Command/Result models

Responsibilities:

Coordinate domain objects
Enforce workflow
Express what the system needs from the outside world

It does not:

Implement HTTP
Access databases
Manipulate Angular state

The application layer defines contracts. It depends only on the domain.

So let's get to it!

Writing use cases

`CreateTicketUseCase`

We now have:

A Domain with entities and value objects (Ticket, Email) and a Port (TicketRepositoryPort)
Soon enough, we will have an Adapter that implements the port

What is missing is the orchestration layer: the use case.

The use case is the heart of the application layer.
It coordinates domain objects and ports. It contains workflow logic.
It does not depend on Angular. It does not know about HTTP.

Under src/app/application/use-cases, create a new file:

CreateTicketUseCase.ts

import { TicketRepositoryPort } from "../ports/TicketRepositoryPort";
import { NewTicket, Ticket } from "../../domain/entities/Ticket";
import { Email } from "../../domain/value-objects/Email";

export interface CreateTicketCommand {
    title: string;
    description: string;
    email: string;
}

export class CreateTicketUseCase {

  constructor(
      private readonly ticketRepository: TicketRepositoryPort
  ) { }

  async execute(command: CreateTicketCommand): Promise<Ticket> {
    // 1. Validate and construct Value Objects
    if (!command.title || command.title.trim().length === 0) {
        throw new Error("Title cannot be empty.");
    }

    if (command.description.trim().length < 20) {
        throw new Error("Description must be at least 20 characters.");
    }

    const { ok, value: email } = Email.tryCreate(command.email);

    if (!ok) {
        throw new Error("Invalid email address.");
    }

    // 2. Build the domain input
    const newTicket: NewTicket = {
        title: command.title.trim(),
        description: command.description.trim(),
        email: email!,
    };

    // 3. Persist through the port
    const createdTicket = await this.ticketRepository.create(newTicket);

    // 4. Return the result
    return createdTicket;
  }
}

Let’s analyze what is happening here.

The use case receives a command (plain data, coming from UI).
It performs validation.
It constructs domain objects (Email).
It calls the repository through the port.
It returns the resulting domain Ticket.

There is:

No Angular import
No HttpClient
No Observable
No framework-specific code

This class can be tested with plain TypeScript.

Why This Matters

The component will later inject and call this use case.

But the use case itself:

Does not know that Angular exists.
Does not know how persistence is implemented.
Does not know whether the repository uses HTTP, IndexedDB, or something else.

It only depends on the contract (TicketRepositoryPort).

This is the moment where hexagonal architecture becomes concrete: the application layer orchestrates the domain and communicates with the outside world only through ports.

That is the core boundary.

Infrastructure => Technical Implementations

Now that we have our Ports and Use Cases, we can implement the Adapters in the infrastructure layer.
The infrastructure layer implements the ports declared in the application layer.

It contains adapters such as:

HttpTicketRepositoryAdapter

Its responsibilities:

Translate domain objects to DTOs
Perform HTTP calls
Access storage
Integrate external APIs

This is the only layer that depends on frameworks or technical details. It depends inward on the application layer.

Under src/app, create the infrastructure/adapters directory. Inside of it, create the following file:

HttpTicketRepositoryAdapter.ts

`HttpTicketRepositoryAdapter.ts`

Here is a first implementation, but do not take it yet, because it is flawed.

import { inject, Injectable } from "@angular/core";
import { TicketRepositoryPort } from "../../application/ports/TicketRepositoryPort";
import { NewTicket, Ticket } from "../../domain/entities/Ticket";
import { HttpClient } from "@angular/common/http";
import { firstValueFrom } from "rxjs";

@Injectable()
export class HttpTicketRepositoryAdapter implements TicketRepositoryPort {
    private readonly httpClient: HttpClient = inject(HttpClient);
    async create(ticket: NewTicket): Promise<Ticket> {
        await firstValueFrom(this.httpClient.post<void>("/api/tickets", ticket));
    }
}

So what do we see here?
Our Adapter properly implements the Port, and returns a Promise. In order to do so, it makes a proper use of firstValueFrom, the RxJs operator. Also, it uses httpClient; therefore, we are here using Angular DI mechanism. We could have made another implementation. For instance:

import { TicketRepositoryPort } from "../../application/ports/TicketRepositoryPort";
import { Ticket } from "../../domain/entities/Ticket";

export class HttpTicketRepositoryAdapter implements TicketRepositoryPort {
    async create(ticket: Ticket): Promise<Ticket> {
        await fetch("/api/tickets", {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify(ticket),
        });
    }
}

This means we do not necessarily have to use an Angular service, although it would be kind of a waste not to. Anyway, back to our Angular service: there are some things to fix in this first implementation!
The main problem is: we send the domain entity directly over HTTP! The Domain should not leak into the transport layer. The Adapter should translate the Entity to DTO. So where should we store the DTO? And whose role it is to do the mapping between the Entity and the DTO?

Where to store the DTO
The DTO can be stored inside a dto directory. We could have the following structure:

infrastructure/
  adapters/
    dtos/
      create-ticket-request.dto.ts
      ticket-response-dto.ts
    http-ticket-repository.adapter.ts

As for the mapping, we could use a dedicated mapper for that:

infrastructure/
  adapters/
    dtos/
      create-ticket-request.dto.ts
      ticket-response-dto.ts
    mappers/
      http-ticket.mapper.ts
    http-ticket-repository.adapter.ts

And while we're at it, it would be nice for this Adapter and its mapper and DTO to have their own global directory. This could come in handy if one day, we have another adapter:

infrastructure/
  adapters/
    http/
      dtos/
        create-ticket-request.dto.ts
        ticket-response-dto.ts
      mappers/
        http-ticket.mapper.ts
      http-ticket-repository.adapter.ts

Here, we have a proper structure. We can now implement the DTO and the mapper:

// create-ticket-request.dto.ts
export type CreateTicketRequestDto = {
  email: string;
  subject: string;
  description: string;
  status: string;
};

// ticket-response-dto.ts
export type TicketResponseDto = {
  id: string;
  trackingId: string;
  title: string;
  description: string;
  status: 'open' | 'in_progress' | 'closed';
  email: string;
  createdAt: string;
  updatedAt?: string;
};

and the mapper

import { NewTicket, Ticket } from "../../../../domain/entities/Ticket";
import { Email } from "../../../../domain/value-objects/Email";
import { CreateTicketRequestDto } from "../dtos/create-ticket-request.dto";
import { TicketResponseDto } from "../dtos/ticket-response.dto";

export function toCreateTicketRequestDto(ticket: NewTicket): CreateTicketRequestDto {
  return {
    email: ticket.email.getValue(),
    subject: ticket.title,
    description: ticket.description,
  };
}

export function toDomainTicket(dto: TicketResponseDto): Ticket {
  return {
    id: dto.id,
    trackingId: dto.trackingId,
    title: dto.title,
    description: dto.description,
    status: dto.status,
    email: Email.create(dto.email),
    createdAt: new Date(dto.createdAt),
    updatedAt: dto.updatedAt ? new Date(dto.updatedAt) : undefined,
  };
}

And, in our Adapter:

import { inject, Injectable } from "@angular/core";
import { TicketRepositoryPort } from "../../../application/ports/TicketRepositoryPort";
import { NewTicket, Ticket } from "../../../domain/entities/Ticket";
import { HttpClient } from "@angular/common/http";
import { firstValueFrom } from "rxjs";
import { toCreateTicketRequestDto, toDomainTicket } from "./mappers/http-ticket.mapper";
import { TicketResponseDto } from "./dtos/ticket-response.dto";

@Injectable()
export class HttpTicketRepositoryAdapter implements TicketRepositoryPort {
    private readonly httpClient: HttpClient = inject(HttpClient);
    async create(ticket: NewTicket): Promise<Ticket> {
        const payload = toCreateTicketRequestDto(ticket);
        const result = await firstValueFrom(this.httpClient.post<TicketResponseDto>("/api/tickets", payload));
        return toDomainTicket(result);
    }
}

Creating a DTO + mapper achieves:

The HTTP contract is explicit and versionable.
You control what crosses the boundary (no accidental fields/methods).
Domain refactors don’t silently break the API contract.
Transport concerns (date formatting, naming, optional fields) stay in infrastructure.

So the pattern is:
Port takes Ticket (core language)
Adapter maps Ticket => CreateTicketRequestDto (boundary adaptation)
Adapter posts the DTO (transport contract).

And that's pretty much it.

Now that we have implemented our application layer, let's do the UI.

UI => Angular Components (Input Adapter)

The UI layer is another adapter.

It contains:

Angular components
Forms
Presentation logic

Responsibilities:

Collect user input
Invoke use cases
Render responses
Manage view state

It must not contain business rules. It delegates decision-making to the application layer.

The component we are about to code will be fairly simple: just a form with a submit button to send the ticket. No special design, we will keep it simple and stupid.
With angular CLI, start by generating a new component into a new directory src/app/ui/tickets

ng g c /ui/tickets/create-ticket

In this component, we are going to use the use case CreateTicketUseCase we created earlier, as well as the Port. The problem is: this use case is a Plain-Old TypeScript Object, or "POTO", which is a totally made up acronym but I like it so I'm going to keep it. Since it is a POTO, we cannot just inject it like any Angular service. In order to do so, we need an injection token for the Port and the Use Case so Angular knows what dependencies to inject and where to inject them.

Create a new directory called src/app/di and inside of it, create a tickets-providers.ts file:

import { InjectionToken, Provider } from "@angular/core";
import { TicketRepositoryPort } from "../application/ports/TicketRepositoryPort";
import { CreateTicketUseCase } from "../application/use-cases/CreateTicketUseCase";
import { HttpTicketRepositoryAdapter } from "../infrastructure/adapters/http/HttpTicketRepositoryAdapter";

export const TICKET_REPOSITORY = new InjectionToken<TicketRepositoryPort>("TICKET_REPOSITORY");

export const TICKETS_PROVIDERS: Provider[] = [
  // adapter (Angular service)
  HttpTicketRepositoryAdapter,

  // port -> adapter binding
  { provide: TICKET_REPOSITORY, useExisting: HttpTicketRepositoryAdapter },

  // use case (constructed with the port)
  {
    provide: CreateTicketUseCase,
    deps: [TICKET_REPOSITORY],
    useFactory: (repo: TicketRepositoryPort) => new CreateTicketUseCase(repo),
  },
];

Then, in app.config.ts, register those providers:

import { ApplicationConfig } from "@angular/core";
import { provideHttpClient } from "@angular/common/http";
import { TICKETS_PROVIDERS } from "./app/di/tickets.providers";

export const appConfig: ApplicationConfig = {
  providers: [
    // other providers ...
    provideHttpClient(), ...TICKETS_PROVIDERS],
};

By doing so, we basically tell Angular how to inject our POTOs in our components. And now, we can implement our Angular component and inject our Use Case in it. Here is a first implementation. It does not matter if it is not perfect: the idea of this article is for you to better understand hexagonal architecture's principles, rather than Angular best practices. In an ideal world, we would have a dedicated file for those validators, and maybe we could use Signals for the form as well. For now, I'll stick to the good old Reactive Form. I will as well provide custom validators.

import { CommonModule } from '@angular/common';
import { Component, computed, inject, OnInit, signal } from '@angular/core';
import { FormBuilder, ReactiveFormsModule, Validators } from '@angular/forms';
import { CreateTicketUseCase } from '../../../application/use-cases/CreateTicketUseCase';
import { trimmedMaxLength, trimmedMinLength, trimmedRequired, trimmedEmail } from '../../validators/trimmed.validators';

@Component({
  selector: 'app-create-ticket',
  standalone: true,
  imports: [CommonModule, ReactiveFormsModule],
  templateUrl: './create-ticket.html',
  styleUrl: './create-ticket.scss',
})
export class CreateTicket implements OnInit {
  private readonly createTicketUseCase = inject(CreateTicketUseCase);
  private readonly fb = inject(FormBuilder);

  readonly isSubmitting = signal(false);
  readonly submitError = signal<string | null>(null);

  readonly form = this.fb.nonNullable.group({
    title: ['', [trimmedRequired(), trimmedMaxLength(120)]],
    description: ['', [trimmedRequired(), trimmedMinLength(20), trimmedMaxLength(5000)]],
    email: ['', [trimmedRequired(), trimmedEmail()]],
  });

  readonly titleError = computed(() => {
    const c = this.form.controls.title;
    if (!c.touched) return null;
    if (c.errors?.['required']) return 'Title is required.';
    if (c.errors?.['maxlength']) return 'Title must be ≤ 120 characters.';
    return null;
  });

  readonly descriptionError = computed(() => {
    const c = this.form.controls.description;
    if (!c.touched) return null;
    if (c.errors?.['required']) return 'Description is required.';
    if (c.errors?.['minlength']) return 'Description must be at least 20 characters.';
    if (c.errors?.['maxlength']) return 'Description must be ≤ 5000 characters.';
    return null;
  });

  readonly emailError = computed(() => {
    const c = this.form.controls.email;
    if (!c.touched) return null;
    if (c.errors?.['required']) return 'Email is required.';
    if (c.errors?.['email']) return 'Invalid email format.';
    return null;
  });

  readonly canSubmit = signal(false);

  ngOnInit(): void {
    this.form.statusChanges.subscribe(() => {
      this.canSubmit.set(this.form.valid && !this.isSubmitting());
    });
  }

  async submit(): Promise<void> {
    if (this.isSubmitting() || this.form.invalid) {
      this.form.markAllAsTouched();
      return;
    }

    this.isSubmitting.set(true);
    this.submitError.set(null);

    const { title, description, email } = this.form.getRawValue();

    try {
      await this.createTicketUseCase.execute({
        title: title.trim(),
        description: description.trim(),
        email: email.trim(),
      });

      this.form.reset();
    } catch (e) {
      this.submitError.set(e instanceof Error ? e.message : 'Unable to create ticket.');
    } finally {
      this.isSubmitting.set(false);
    }
  }
}

And in the template:

<!-- create-ticket.html -->
<form [formGroup]="form" (ngSubmit)="submit()" novalidate class="create-ticket-form">
  <h2>Create Support Ticket</h2>

  <div class="form-group">
    <label for="title">Title</label>
    <input id="title" type="text" formControlName="title" placeholder="Short summary of your issue" />
    @if (titleError(); as err) {
      <small class="error">{{ err }}</small>
    }
  </div>

  <div class="form-group">
    <label for="description">Description</label>
    <textarea
      id="description"
      rows="6"
      formControlName="description"
      placeholder="Describe your issue (minimum 20 characters)"
    ></textarea>
    @if (descriptionError(); as err) {
      <small class="error">{{ err }}</small>
    }
  </div>

  <div class="form-group">
    <label for="email">Email</label>
    <input id="email" type="email" autocomplete="email" formControlName="email" placeholder="you@example.com" />
    @if (emailError(); as err) {
      <small class="error">{{ err }}</small>
    }
  </div>

  @if (submitError(); as err) {
    <div class="error">{{ err }}</div>
  }

  <button type="submit" [disabled]="!canSubmit()">
    @if (isSubmitting()) { Creating… } @else { Create Ticket }
  </button>
</form>

For the custom validators, create a directory under src/app/ui/validators and add trimmed.validators.ts:

import { AbstractControl, ValidationErrors, ValidatorFn, Validators } from '@angular/forms';

export function trimmedRequired(): ValidatorFn {
  return (control: AbstractControl<string>): ValidationErrors | null => {
    const value = control.value ?? '';
    return value.trim().length === 0 ? { required: true } : null;
  };
}

export function trimmedMinLength(min: number): ValidatorFn {
  return (control: AbstractControl<string>): ValidationErrors | null => {
    const value = control.value ?? '';
    return value.trim().length < min
      ? { minlength: { requiredLength: min, actualLength: value.trim().length } }
      : null;
  };
}

export function trimmedMaxLength(max: number): ValidatorFn {
  return (control: AbstractControl<string>): ValidationErrors | null => {
    const value = control.value ?? '';
    return value.trim().length > max
      ? { maxlength: { requiredLength: max, actualLength: value.trim().length } }
      : null;
  };
}

export const trimmedEmail = (): ValidatorFn => {
  return (control: AbstractControl): ValidationErrors | null => {
    const v = (control.value ?? '').toString().trim();
    if (!v) return null;
    return Validators.email({ value: v } as any);
  };
};

And now, it is time to test! Before launching our server, make sure you:

remove everything in app.html except <router-outlet/>
have the following routes in app.routes.ts:

import { Routes } from '@angular/router';

export const routes: Routes = [
    {
        path: '',
        redirectTo: 'tickets/create',
        pathMatch: 'full',
    },
    {
        path: 'tickets/create',
        loadComponent: () => import('./ui/tickets/create-ticket/create-ticket').then(m => m.CreateTicket),
    }
];

Launch the server:

ng serve

Go to http://localhost:4200 and try to submit a ticket. It should fail, but only because we do not have any backend implemented. The error should be a 404 error on /api/tickets. So far, it does not matter, as it is out of the scope of this article.

Testing the architecture

A high-quality app cannot exist without any tests. And hexagonal architecture allows us to better test our app, thanks to concern separation.

Core Testing

We need, of course, to test our core (Ports + UseCase). This part does not necessitate Angular. The goal is to manage to test everything without any TestBed nor httpClient.

The methodology is pretty simple:

create fake ports
inject those fakes in use cases
test behaviour

In order to test, we are going to use Vitest and do some configuration.

Installing and configuring Vitest

Install Vitest:

npm install -D vitest @vitest/ui jsdom @types/node && npm install -D vite-tsconfig-paths

and in your tsconfig.spec.json, make sure you have the following section:

"compilerOptions": {
  "outDir": "./out-tsc/spec",
  "types": [
    "vitest/globals",
    "node"
  ]
},
"include": [
  "src/**/*.d.ts",
  "src/**/*.spec.ts",
  "src/**/*.test.ts"
]

You can also remove the app.spec.ts file: we won't need it anymore.

Implementing our fakes

In order to ensure our app will behave the same, no matter the implementations of the Adapters, we need to have a FakeAdapter for each Adapter we implement. Create a src/app/testing/fakes directory in which you will put all of your fakes.

Testing the `HttpTicketRepositoryAdapter`

This Adapters depends on httpClient, so it is completely OK to have our test tied to Angular.

Create the src/app/infrastructure/adapters/http/__tests__ directory and add the HttpTicketRepositoryAdapter.spec.ts file:

import { TestBed } from '@angular/core/testing';
import { provideHttpClient } from '@angular/common/http';
import { HttpTestingController, provideHttpClientTesting } from '@angular/common/http/testing';
import { HttpTicketRepositoryAdapter } from '../HttpTicketRepositoryAdapter';
import { NewTicket } from '../../../../domain/entities/Ticket';
import { Email } from '../../../../domain/value-objects/Email';
import { TicketResponseDto } from '../dtos/ticket-response.dto';

describe('HttpTicketRepositoryAdapter', () => {
  let adapter: HttpTicketRepositoryAdapter;
  let httpMock: HttpTestingController;

  beforeEach(() => {
    TestBed.configureTestingModule({
      providers: [
        provideHttpClient(),
        provideHttpClientTesting(),
        HttpTicketRepositoryAdapter,
      ],
    });

    adapter = TestBed.inject(HttpTicketRepositoryAdapter);
    httpMock = TestBed.inject(HttpTestingController);
  });

  afterEach(() => {
    httpMock.verify();
  });

  it('should POST mapped DTO and return mapped domain Ticket', async () => {
    const newTicket: NewTicket = {
      title: 'Payment issue',
      description: 'This description is definitely long enough.',
      email: Email.create('User@Example.com'),
    };

    const promise = adapter.create(newTicket);

    const req = httpMock.expectOne('/api/tickets');
    expect(req.request.method).toBe('POST');

    expect(req.request.body).toEqual({
      email: 'user@example.com',
      subject: 'Payment issue',
      description: 'This description is definitely long enough.',
    });

    const response: TicketResponseDto = {
      id: 'T-99',
      trackingId: 'TRK-99',
      title: 'Payment issue',
      description: 'This description is definitely long enough.',
      status: 'open',
      email: 'user@example.com',
      createdAt: '2026-02-01T10:00:00.000Z',
      updatedAt: '2026-02-01T10:05:00.000Z',
    };

    req.flush(response);

    const created = await promise;

    expect(created.id).toBe('T-99');
    expect(created.trackingId).toBe('TRK-99');
    expect(created.email.getValue()).toBe('user@example.com');
    expect(created.createdAt.toISOString()).toBe('2026-02-01T10:00:00.000Z');
    expect(created.updatedAt!.toISOString()).toBe('2026-02-01T10:05:00.000Z');
  });

  it('should surface HTTP errors as rejections', async () => {
    const newTicket: NewTicket = {
      title: 'Payment issue',
      description: 'This description is definitely long enough.',
      email: Email.create('user@example.com'),
    };

    const promise = adapter.create(newTicket);

    const req = httpMock.expectOne('/api/tickets');
    req.flush({ message: 'Boom' }, { status: 500, statusText: 'Server Error' });

    await expect(promise).rejects.toThrow();
  });
});

Testing the `http-ticket.mapper.ts`

The mapper does not depend on Angular. Therefore, we will simply use Vitest and write our test in a framework-agnostic way. Write it in a file called http-ticket-mapper.test.ts under the src/app/infrastructure/adapters/http/mappers/__tests__ directory.

import { toCreateTicketRequestDto, toDomainTicket } from './ http-ticket.mapper';
import { Email } from '../../../../domain/value-objects/Email';
import type { NewTicket } from '../../../../domain/entities/Ticket';
import type { TicketResponseDto } from '../dtos/ticket-response.dto';

describe('http-ticket.mapper', () => {
  it('toCreateTicketRequestDto should map NewTicket to CreateTicketRequestDto', () => {
    const ticket: NewTicket = {
      title: 'Title',
      description: 'This description is definitely long enough.',
      email: Email.create('Test@Example.com'),
    };

    const dto = toCreateTicketRequestDto(ticket);

    expect(dto).toEqual({
      email: 'test@example.com',
      subject: 'Title',
      description: 'This description is definitely long enough.',
    });
  });

  it('toDomainTicket should map TicketResponseDto to Ticket domain object', () => {
    const dto: TicketResponseDto = {
      id: 'T-42',
      trackingId: 'TRK-42',
      title: 'Hello',
      description: 'This description is definitely long enough.',
      status: 'open',
      email: 'User@Example.com',
      createdAt: '2026-02-01T10:00:00.000Z',
      updatedAt: '2026-02-01T11:00:00.000Z',
    };

    const ticket = toDomainTicket(dto);

    expect(ticket.id).toBe('T-42');
    expect(ticket.trackingId).toBe('TRK-42');
    expect(ticket.status).toBe('open');
    expect(ticket.email.getValue()).toBe('user@example.com');
    expect(ticket.createdAt.toISOString()).toBe('2026-02-01T10:00:00.000Z');
    expect(ticket.updatedAt!.toISOString()).toBe('2026-02-01T11:00:00.000Z');
  });

  it('toDomainTicket should keep updatedAt undefined when not present', () => {
    const dto: TicketResponseDto = {
      id: 'T-1',
      trackingId: 'TRK-1',
      title: 'Hello',
      description: 'This description is definitely long enough.',
      status: 'open',
      email: 'user@example.com',
      createdAt: '2026-02-01T10:00:00.000Z',
    };

    const ticket = toDomainTicket(dto);
    expect(ticket.updatedAt).toBeUndefined();
  });
});

Testing the `CreateTicketUseCase`

This one is pretty interesting. As you now know, the Use Cases are agnostic to Angular. We do not want any framework interference in it, nor in their tests. Earlier, I said we will need to implement a Fake Adapter. The role of the Fake Adapter is to make sure the Use Case works no matter the technical implementation behind the adapters it uses. We need to make sure the business logic works.

Implementing `FakeTicketRepositoryAdapter`

Let's create a src/app/testing/fakes directory, under which we create a FakeTicketRepositoryAdapter.ts file. This class will implement the TicketRepositoryPort interface and is pretty basic:

import { TicketRepositoryPort } from "../../application/ports/TicketRepositoryPort";
import { NewTicket, Ticket } from "../../domain/entities/Ticket";

export class FakeTicketRepositoryAdapter implements TicketRepositoryPort {
  private store: Ticket[] = [];
  private idSequence = 1;
  private trackingSequence = 1;

  constructor(private readonly fixedNow = new Date('2026-01-01T00:00:00.000Z')) {}

  async create(ticket: NewTicket): Promise<Ticket> {
    const created: Ticket = {
      id: `T-${this.idSequence++}`,
      trackingId: `TRACK-${this.trackingSequence++}`,
      title: ticket.title,
      description: ticket.description,
      email: ticket.email,
      status: 'open',
      createdAt: this.fixedNow,
      updatedAt: this.fixedNow,
    };

    this.store.push(created);
    return created;
  }

  getAll(): Ticket[] {
    return [...this.store];
  }

  clear(): void {
    this.store = [];
    this.idSequence = 1;
    this.trackingSequence = 1;
  }
}

Now, we need to use this Fake Adapter in our future test.

Implementing our test

The test is pretty basic as well. You can write in in src/app/application/use-cases/__tests__/CreateTicketUseCase.test.ts:

import { describe, it, expect, beforeEach } from 'vitest';
import { CreateTicketUseCase } from '../CreateTicketUseCase';
import { FakeTicketRepositoryAdapter } from '../../../testing/fakes/FakeTicketRepositoryAdapter';

describe('CreateTicketUseCase', () => {
  let repo: FakeTicketRepositoryAdapter;
  let useCase: CreateTicketUseCase;

  beforeEach(() => {
    repo = new FakeTicketRepositoryAdapter(); // we use our fake repository
    repo.clear();
    useCase = new CreateTicketUseCase(repo);
  });

  it('persists a trimmed + normalized NewTicket via the repository', async () => {
    const created = await useCase.execute({
      title: '  Payment issue  ',
      description: '  This description is definitely long enough.  ',
      email: 'TEST@EXAMPLE.COM',
    });

    // assertions about behavior controlled by the use case
    const stored = repo.getAll();
    expect(stored).toHaveLength(1);

    expect(stored[0].title).toBe('Payment issue');
    expect(stored[0].description).toBe('This description is definitely long enough.');
    expect(stored[0].email.getValue()).toBe('test@example.com');

    // result is whatever the repository returns (don't assert repo internals)
    expect(created.title).toBe('Payment issue');
    expect(created.description).toBe('This description is definitely long enough.');
    expect(created.email.getValue()).toBe('test@example.com');
  });

  it('does not persist when title is empty after trim', async () => {
    await expect(
      useCase.execute({
        title: '   ',
        description: 'This description is definitely long enough.',
        email: 'a@b.com',
      })
    ).rejects.toThrow(/title/i);

    expect(repo.getAll()).toHaveLength(0);
  });

  it('does not persist when description is too short after trim', async () => {
    await expect(
      useCase.execute({
        title: 'Bug',
        description: '                    short                    ',
        email: 'a@b.com',
      })
    ).rejects.toThrow(/20/i);

    expect(repo.getAll()).toHaveLength(0);
  });

  it('does not persist when email is invalid', async () => {
    await expect(
      useCase.execute({
        title: 'Bug',
        description: 'This description is definitely long enough.',
        email: 'not-an-email',
      })
    ).rejects.toThrow(/email/i);

    expect(repo.getAll()).toHaveLength(0);
  });
});

You can now launch your tests with:

npm run test

You might notice the create-ticket.spec.ts are failing

Testing the UI

The last thing we need to test now is our CreateTicket component. Now, we already have a base with create-ticket.spec.ts. But this base does not provide the proper dependencies, so we need to specify them (explanations in comments):

import { ComponentFixture, TestBed } from '@angular/core/testing';
import { CreateTicket } from './create-ticket';
import { CreateTicketUseCase } from '../../../application/use-cases/CreateTicketUseCase';
import type { TicketRepositoryPort } from '../../../application/ports/TicketRepositoryPort';
import { FakeTicketRepositoryAdapter } from '../../../testing/fakes/FakeTicketRepositoryAdapter';
import { TICKET_REPOSITORY } from '../../../di/tickets-providers';

function setFormValues(
  component: CreateTicket,
  overrides?: Partial<{ title: string; description: string; email: string }>
) {
  component.form.setValue({
    title: overrides?.title ?? 'Payment issue',
    description: overrides?.description ?? 'This description is definitely long enough.',
    email: overrides?.email ?? 'user@example.com',
  });
}

function getFieldErrorText(fixture: ComponentFixture<CreateTicket>, fieldId: 'title' | 'description' | 'email') {
  const root: HTMLElement = fixture.nativeElement;
  const container = root.querySelector(`#${fieldId}`)?.closest('.form-group');
  if (!container) return null;
  const el = container.querySelector('small.error');
  return el?.textContent?.trim() ?? null;
}

function getGlobalErrorTexts(fixture: ComponentFixture<CreateTicket>) {
  const root: HTMLElement = fixture.nativeElement;
  const errors = Array.from(root.querySelectorAll('div.error')).map((e) => e.textContent?.trim() ?? '');
  // field errors are <small.error>, global errors are <div.error>
  return errors.filter(Boolean);
}

describe('CreateTicket (template + component)', () => {
  let fixture: ComponentFixture<CreateTicket>;
  let component: CreateTicket;

  beforeEach(async () => {
    await TestBed.configureTestingModule({
      imports: [CreateTicket],
      providers: [
        // Here, I use the FakeTicketRepositoryAdapter as I did for the Use Case tests
        FakeTicketRepositoryAdapter,
        // I also provide the class for injecting the port, as it is needed by the Use Case
        { provide: TICKET_REPOSITORY, useExisting: FakeTicketRepositoryAdapter },
        // And I provide the Use Case by using a factory function and specifying the injection token
        // used by this function
        {
          provide: CreateTicketUseCase,
          useFactory: (repo: TicketRepositoryPort) => new CreateTicketUseCase(repo),
          deps: [TICKET_REPOSITORY],
        },
      ],
    })
    .compileComponents();

    fixture = TestBed.createComponent(CreateTicket);
    component = fixture.componentInstance;
    await fixture.whenStable();
  });

  // The rest is basic testing
  it('renders the form skeleton', () => {
    const root: HTMLElement = fixture.nativeElement;

    expect(root.querySelector('form.create-ticket-form')).not.toBeNull();
    expect(root.querySelector('h2')?.textContent ?? '').toContain('Create Support Ticket');

    expect(root.querySelector('#title')).not.toBeNull();
    expect(root.querySelector('#description')).not.toBeNull();
    expect(root.querySelector('#email')).not.toBeNull();

    const button = root.querySelector('button[type="submit"]') as HTMLButtonElement | null;
    expect(button).not.toBeNull();
  });

  it('does not render field errors until touched', () => {
    component.form.controls.title.setValue('');
    component.form.controls.description.setValue('');
    component.form.controls.email.setValue('');
    fixture.detectChanges();

    expect(getFieldErrorText(fixture, 'title')).toBeNull();
    expect(getFieldErrorText(fixture, 'description')).toBeNull();
    expect(getFieldErrorText(fixture, 'email')).toBeNull();
  });

  it('disables submit button when form invalid', () => {
    const root: HTMLElement = fixture.nativeElement;
    const button = root.querySelector('button[type="submit"]') as HTMLButtonElement;

    expect(button.disabled).toBe(true);
  });

  it('enables submit button when form becomes valid', async () => {
    setFormValues(component);
    component.form.markAllAsTouched();

    fixture.detectChanges();
    await fixture.whenStable();
    fixture.detectChanges();

    const root: HTMLElement = fixture.nativeElement;
    const button = root.querySelector('button[type="submit"]') as HTMLButtonElement;

    expect(component.form.valid).toBe(true);
    expect(button.disabled).toBe(false);
  });

  it('submits, calls use case with trimmed values, resets the form, and keeps no global error', async () => {
    const uc = TestBed.inject(CreateTicketUseCase);
    const executeSpy = vi.spyOn(uc, 'execute');

    setFormValues(component, {
      title: '  Payment issue  ',
      description: '  This description is definitely long enough.  ',
      email: '  USER@EXAMPLE.COM  ',
    });
    component.form.markAllAsTouched();
    fixture.detectChanges();
    await fixture.whenStable();
    await component.submit();
    fixture.detectChanges();

    expect(executeSpy).toHaveBeenCalledTimes(1);
    expect(executeSpy.mock.calls[0][0]).toEqual({
      title: 'Payment issue',
      description: 'This description is definitely long enough.',
      email: 'USER@EXAMPLE.COM',
    });


    expect(component.form.controls.title.value).toBe('');
    expect(component.form.controls.description.value).toBe('');
    expect(component.form.controls.email.value).toBe('');

    expect(getGlobalErrorTexts(fixture)).toEqual([]);
  });

  it('renders global submit error when use case throws', async () => {
    const uc = TestBed.inject(CreateTicketUseCase);
    vi.spyOn(uc, 'execute').mockRejectedValue(new Error('Boom'));

    setFormValues(component);
    component.form.markAllAsTouched();
    fixture.detectChanges();
    await fixture.whenStable();

    await component.submit();
    fixture.detectChanges();

    expect(component.submitError()).toBe('Boom');

    const globalErrors = getGlobalErrorTexts(fixture);
    expect(globalErrors).toContain('Boom');
  });
});

And this is it!
Through this simple example, we just saw the basics of hexagonal architecture in Angular!

Below is the continuation you can append to your article after section 10.
It is consistent with the tone and structure of your current draft .

What We Gained

At this point, the architecture is no longer theoretical. We have a working Angular feature built around a strict separation of concerns.

Let’s examine what this structure actually gives us in practice.

Clear Separation of Concerns

Each layer has a single responsibility:

Domain expresses business rules.
Application orchestrates use cases.
Infrastructure handles technical integration.
UI collects input and renders output.

No layer bleeds into another. If a business rule changes, it lives in the domain or use case. If the API changes, only the HTTP adapter is affected.

This reduces cognitive load. When reading a file, you know what type of logic belongs there.

Framework Independence

The core of the application:

Does not import Angular.
Does not depend on RxJS.
Does not rely on HttpClient.
Does not depend on browser APIs.

This means:

It can be tested with plain TypeScript.
It could be reused in another frontend framework.
It could even be reused in a Node.js backend.

Angular becomes a detail, not the foundation.

Replaceable Infrastructure

If tomorrow:

You switch from REST to GraphQL.
You add offline support.
You cache tickets in IndexedDB.
You migrate to a different backend contract.

You only touch the adapter layer.

The domain and use cases remain untouched.

This drastically reduces change cost.

High Testability

We achieved three levels of testing:

Core tests (no Angular, no TestBed)

Pure TypeScript.
Fake adapters.
Fast execution.

Infrastructure tests

Angular TestBed.
HttpTestingController.
Contract validation.

UI tests

Component rendering.
Form behavior.
Use case wiring.

The architecture enforces this testability.

If you need Angular to test business rules, the architecture is already broken.

Scalability for Teams

In a growing team:

Domain experts can focus on business rules.
Frontend engineers can work on UI.
Backend/API contracts are isolated in adapters.
Refactors become localized.

Boundaries reduce friction between contributors.

Hexagonal architecture is not about patterns.
It is about coordination under complexity.

Common Mistakes in Angular Hexagonal Implementations

Hexagonal architecture is simple in principle. It becomes distorted when misunderstood.

Here are common mistakes.

Putting Business Logic in Angular Services

Angular services are often mistaken for "the domain."

They are not.

A service that:

Calls HttpClient
Applies validation
Makes business decisions
Mutates state

is mixing layers.

Business rules must live in the domain or use case.
Services are infrastructure or orchestration tools, not the core model.

Letting Adapters Leak into the Domain

If you see:

DTO types imported in domain entities
HttpClient referenced inside a use case
Observable exposed in ports

you have violated the boundary.

Ports must stay framework-neutral.
Adapters translate between core language and transport language.

The domain should not know what JSON looks like.

Injecting HttpClient Directly into Components

This is the most common Angular anti-pattern.

When a component directly calls HttpClient:

UI layer collapses into infrastructure.
Business rules end up in submit() handlers.
Tests become heavy.

The component should call a use case.
Nothing else.

Overengineering Too Early

Hexagonal architecture is about structure, not abstraction for its own sake.

Do not:

Create dozens of ports for trivial features.
Introduce artificial layers for simple apps.
Add complexity without business justification.

Start simple:

One repository port.
One use case.
One adapter.

Split only when the system demands it.

When to Use (and When Not To)

Hexagonal architecture is powerful, but not universal.

Use It When

Your Angular app has real business logic.
Validation rules evolve over time.
Multiple data sources may appear.
You expect long-term maintenance.
Multiple developers collaborate.

It shines when complexity grows.

Avoid It When

The project is a temporary prototype.
The app is a pure CRUD demo.
The domain logic is trivial.
The codebase will be discarded shortly.

Architecture has a cost.

Apply it where complexity justifies it.

Conclusion

Angular is not your architecture.

It is a UI framework.

If Angular disappears tomorrow, your business logic should survive.

Hexagonal architecture enforces that survival.

It keeps:

The domain stable.
The application layer explicit.
Infrastructure replaceable.
The UI thin.

What we built in this article is minimal.
But the structure scales.

When complexity grows, boundaries protect you.

That is the real value of hexagonal architecture.

How I created an Observable library - part 1

Thomas Toledo-Pierre — Wed, 15 Feb 2023 15:38:20 +0000

TL;DR

I created a small library called FleuveJS. This post shares how I've come to create it and how it has evolved. Also, I am looking for your feedback on it :-)

Two years ago, I was working on an Angular project (I always work on Angular projects). For those of you who do not know: Angular comes with RxJs, an awesome library to manipulate Observables.

I have always found this library pretty remarkable: the diversity of operators and the structures you can manipulate (Observables, Subjects, BehaviorSubjects) allow developers to write reactive and powerful code. And as I was working on my Angular project, I started to wonder: how hard would it be to write an RxJs-like library? I was really curious about the challenges they would face and how they would overcome it.

Also, I was wondering: would it be possible to have an infinite source of data with Observables?

And so, I started my project.

What should be the MVP?

My first question was: what should be the minimum my library should be able to do?

I knew I wanted to manipulate Observables. What can we do with an Observable ?

To me, an Observable should allow the following operations:

subscribe
next
pipe

I never used the forEach method so I skipped it. The next method was because I wanted to have something mutable.

There it was. My first version should propose to developers a simple structure with three methods: subscribe, next and pipe.

The technical stack

I wanted to keep it as simple as possible: I only used TypeScript to develop this library, webpack for the bundling and Jest for testing.

The first implementation

TDD all the way!

I also wanted to try TDD, so I started by writing a test.

The first ones were the following

As an Observable, it:
- should create a new Observable with no emitting value;
- should create a new Observable with an emitting value;
subscribe method, it:
- should throw an error if the wrong argument is passed;
- should add a subscriber to the list of subscribers;
- should not execute the subscriber if there is no emitting value;
- should execute the subscriber if there is at least one emitting value;
pipe method, it:
- should return a new Observable with no value if the initial Observable is empty;
- should return a new Observable with the original Observable's value;

Since I had no operators yet, I did not see any other tests I could implement.

Of course, the tests were failing, so now it was time to implement the Observable class.

The `Observable` class

First of all, the Observable class should have a generic parameter.

class  Observable<T = never>

Then, it should have an inner sequence, which would be an array of items of type T.

private _innerSequence!: T[];

So far, this simple class:


class  Observable<T = never> {
    private _innerSequence!: T[];
    constructor(...initialSequence: T[]) {
        this._innerSequence = initialSequence;
    }
}

allows to create an observable with some values in it. The problem is: we still cannot pipe it, nor subscribe to it.

The `Subscriptions` and the `Subscribers`

How can a Subscriber be represented?
If we take a look at RxJs, we can see that a Subscriber should have three methods: one to handle the emitted values, one to handle the errors, and one to handle when an Observable is completed (i.e: the sequence last element has been emitted).

A simple interface is enough, with an interface for each method as well:

interface  Subscriber<T = any> {
    next?: OnNext<T>, error?: OnError, complete?: OnComplete
}
interface  OnNext<T> { (t: T): void; }
interface  OnError { (err: Error): void }
interface  OnComplete { (): void };

Also, everytime someone subscribes to an Observable, they should receive a Subscription in order to manage if they want to unsubscribe or not. Hence the following class:

class  Subscription {
    constructor(private  _unsubscribeCallback?: UnsubscribeCallback) {}
    unsubscribe(): void {
    this._unsubscribeCallback && this._unsubscribeCallback();
    }
}

Hold on a minute! What is this UnsubscribeCallback and why is it optional?

Let's see how our Observable class should behave when someone subscribes to it.
Everytime there is a subscribing, we should:

check if the subscriber is actually a Subscriber (is either of type OnNext<T> or Subscriber<T>), else throw an error;
if there is no subscriber passed as an argument, we should read the inner sequence without executing anything;
if there is an actual subscriber, add it to the list of subscribers of the Observable and execute its methods according to the inner sequence;
finally, we should return a new Subscription.

And when this Subscription has its unsubscribe method called, we should finally remove the corresponding Subscriber of the Observable list of subscribers. A simple way to do it is by passing to the Subscription constructor a callback that will simply filter out the corresponding Subscriber, like so:

() => (this._subscribers = this._subscribers.filter((s) =>  s !== subscriber))

This callback will then be executed when the unsubscribe method is called.
Now, why is it optional?

There is a case where we do not need any callback to be executed: it is when one subscribes to an Observable without providing any Subscriber. In this particular case, we won't add anything to our list of subscribers.

`pipe` and the operators

At this step of my project, I need to implement operators so my Observables can be transformed.
An operator, such as map, filter, tap or even switchMap, is nothing but a function taking a callback as an input, and returning a result as an input. The result can be anything: a number, a string, a boolean, void, or even another Observable.

The callback can have a generalized representation we can call OperatorFunction. There are operators that will take an argument of type T, and output a result of type U, such as U can be anything, including T. And there are operators that will take an argument of type T, but won't necessarily output anything.

Given this information, we have a type OperatorFunction<T, U = never> = (source: T) => U.

Now, there is a tricky case (there are many but this one was very challenging for me): the switchMap operator.
This operator takes a value of type T, and returns an Observable of type U. The question is: how can I use the pipe method with any operators I want, with each operator not having to care if the previous returns a new Observable or not?

In short, the following code should work:

const obs$ = of(12, 13, 14)
    .pipe(
    map((x) => x + 1), //will output 13, 14, 15 
    switchMap((x) => of(x - 3)), //will output Observable(10), Observable(11), Observable(12)
    filter((x) => x > 10) //will output false, true, true
    );

But how can the filter operator receive the values wrapped in the Observables returned by the switchMap operator, and not the actual Observables?

To answer that, I chose to specify the result of every operator as an OperationResult. An OperationResult should bear a value (the result), as well as an error if the operation threw one, and a flag.

What are flags for?
I saw four cases:

the result comes from an operator such as switchMap and mus actually be unwrapped;
the previous operator was a predicate that wasn't matched and the rest of the operation pipeline must stop for the whole inner sequence;
the previous operator was a predicate that wasn't matched and the rest of the operation pipeline will be skipped to the next inner sequence item;
the previous operator threw an error.

It gives us the following enum:

enum OperationResultFlag {
    UnwrapSwitch = 'UnwrapSwitch',
    MustStop = 'MustStop',
    FilterNotMatched = 'FilterNotMatched',
    OperationError = 'OperationError',
}

As for the OperationResult, it's a class, implemented as follow:

class  OperationResult<T> {
    constructor(private  _value: T, private  _flag?: OperationResultFlag, private  _error?: Error) {}

get  value() {return  this._value;}

get  flag() {return  this._flag;}

get  error() {return  this._error;}

isUnwrapSwitch(): boolean {
    return  this._flag === OperationResultFlag.UnwrapSwitch;
}
isMustStop(): boolean {
    return  this._flag === OperationResultFlag.MustStop;
}
isFilterNotMatched(): boolean {
    return  this._flag === OperationResultFlag.FilterNotMatched;
}
isOperationError(): boolean {
    return  this._flag === OperationResultFlag.OperationError
}

Now that we have a class for our operation results, we can actually combine multiple operators. In our Observable class, we will internally check after each operation if the result is flagged, and according to it what we need to do.

Follow for the next part

In the next part, I will explain how I came up with more specific Observable implementations such as MutableObservable or ObservableFork.

These implementations implied a lot of change and thinking in my code, and are still evolving.

Anyway, I hope you liked this article, do not hesitate to leave your feedback!

A Simple Observable Class

Thomas Toledo-Pierre — Sun, 13 Dec 2020 23:01:39 +0000

Today, the RxJs library is rather known amongst frontend developers. It is a powerful library, which I enjoy using!

But lately, I wanted to give to some of my students a taste of that library, by making them implement a rather simple Observable class.

What our `Observable` class should do

subscribe: obviously, we'd like our Observable to allow the users to subscribe to its value(s). This method should take in argument a function to execute everytime the value changes. This method will return a Subscription object;
next: our Observable will rather be a Subject, as we're going to implement a next method. This next method will allow us to simply update the Observable inner value(s);
pipe: we would like our Observable to allow multiple treatments to be done to its value(s), but without directly modifying it. This method should return a new Observable;
unsubscribe: this method will actually belong to the Subscription class.

The specs are pretty simple, let's get down to it.

A first implementation

For a start, here is our Observable class declaration

class Observable {
}

Wonderful. Now, our class will contain an inner value. This value will be private. Which means we can do it according to two ways: we either use the #myPrivateField notation -but it is still at stage 3, hopefully stage 4 in 2021-, or declare everything in the constructor.

For a change, I will use the first way.

class Observable {
  #value;
  constructor(value) {
   this.#value = value;
  }
}

So now, we basically have a class with an inner value we cannot access.
We most certainly can move on to the next part of this article.

The `subscribe` method

We want to register a function that will be executed everytime our Observable's value will change.
In order to do that, we will need a simple array -let's call it subscriptions and make it a private field- and a method that push the function into the array. This method should also execute the function as soon as it is subscribed, passing the value to it.

class Observable {
  #value;
  #subscriptions = [];
  constructor(value) {
   this.#value = value;    
  }

  subscribe(f) {
   this.#subscriptions.push(f);
   f(this.#value);
  }
}

The `next` method

This method should allow the user to update the inner value of the Observable. It should also trigger all of the subscriptions.

class Observable {
  #value;
  #subscriptions = [];
  constructor(value) {
   this.#value = value;    
  }

  subscribe(f) {
   this.#subscriptions.push(f);
   f(this.#value);
  }

  next(value) {
   this.#value = value;
   this.#subscriptions.forEach((f) => f(this.#value));
  }
}

The `pipe` method

A pipe should take in parameters an undefined number of functions to execute, and should execute them by passing to the next the result of the previous one.

An implementation, using the Array.prototype.reduce method, could be this:

function pipe(...fList) {
  return (...args) => {
    return fList.slice(1)
          .reduce((f, val) => f(val), fList[0](...args));
  }
}

This implementation actually returns a new pipe.
In our case, it will be a little different, as we already have an initial value, and we do not want to return a new pipe. Also, our pipe method should return a new Observable, containing a new value.

class Observable {
  #value;
  #subscriptions = [];
  constructor(value) {
   this.#value = value;    
  }

  subscribe(f) {
   this.#subscriptions.push(f);
   f(this.#value);
  }

  next(value) {
   this.#value = value;
   this.#subscriptions.forEach((f) => f(this.#value));
  }

  pipe(...fList) {
   const obs = new Observable();
   const res = fList.slice(1)
         .reduce((val, f) => f(val), fList[0](this.#value));
   obs.next(res);
   return obs;
  }
}

The `unsubscribe` method

As I previously said, the unsubscribe method will belong to a Subscription class.

This class should allow to unregister a function previously registered with the Observable.prototype.subscribe method.

It will need no argument, and will return nothing. If the subscription is already unsubscribed, then it will silently do nothing.

It should work as follow:

const obs = new Observable(12);
// will print 12
const sub = obs.subscribe((val) => console.log(val)); 

// the subscription will print "toto"
obs.next('toto');
sub.unsubscribe();
obs.next('something'); // nothing will happen

The Subscription class should have a function passed as a constructor argument. This function would be its unsubscribe method, and it would be created during the subscribe procedure.

Here is how I am going to do it:

First of all, I am going to change a little bit the way we store our functions in the #subscriptions array of the Observable class: I am going to use a Map.
This Map will pair an ID with a function.

Next, I am going to implement a class Subscription that will only take an unsubscribe function as a constructor parameter. If nothing is supplied, it will simply set a default function that does nothing.

Finally, in the subscribe method of Observable, I will refactor a bit the code and return a new Subscription.

class Observable {
  #value;
  #subscriptions = new Map();
  constructor(value) {
   this.#value = value;    
  }

  subscribe(f) {
   const id = this.#subscriptions.size;
   this.#subscriptions.set(id, f);
   f(this.#value);
   return new Subscription(() => this.#subscriptions.delete(id));
  }

  next(value) {
   this.#value = value;
   this.#subscriptions.forEach((f) => f(this.#value));
  }

  pipe(...fList) {
   const obs = new Observable();
   const res = fList.slice(1).reduce((val, f) => f(val), fList[0](this.#value));
   obs.next(res);
   return obs;
  }
}

class Subscription {
  constructor(unsubscribe = () => void 0) {
   this.unsubscribe = unsubscribe;
  }
}

And voilà!
We now have a very minimalist Observable class with a Subscription mechanism, allowing us to defer treatments.

Be careful using this implementation, as we did not cover the whole range of possible scenarios. For instance, the following code would not work:

const obs = new Observable([
   {name: 'john', age: 28}, 
   {name: 'bastien', age: 24}, 
   {name: 'julia', age: 40}
]);

const sub1 = obs.subscribe(
   ([john, bastien, julia]) => {
      console.log(john, bastien, julia);
   }
);

obs.next(12);

If you have not figured out why this code would throw an exception, try it in your browser console.

We will cover this, and much more, in the upcoming posts. In the meantine, do not hesitate to react in the comments and / or to give me your thoughts about it :)

Bye!

Debounce and Throttle

Thomas Toledo-Pierre — Wed, 05 Aug 2020 20:54:19 +0000

The problem

Recently, a student of mine was facing a performance challenge: he had a treatment to trigger when the user would resize the browser window.

What he first did was something like this:

function treatment() {
  if (window.innerWidth >= 1000) {
    // do some stuff
  }
}

window.onresize = treatment;

He then noticed the treatment function was being executed for every tiny resizing the user would make, causing slow performances. According to this, he wanted to find a better solution: he actually wanted to trigger the treatment only for a given screen size.

So, he put some if conditions.
It was a good step: the treatment would only be executed when the screen size would meet the condition.
But it was not enough: what if, there was a way to reduce drastically the number of executions, and still have the treatment done properly?

Debounce and Throttle

Debounce and Throttle are two operators you can find in some libraries. You can, also, implement them by yourself.
They anwser to a need for performance, by reducing the trigger count of a function.

Throttle allows you to execute a function only if a certain amount of time has passed since the last execution.
Let's say we have a throttled function:

function displayName(name) {
  console.log(`Name is ${name}`);
}

// We want the execution to be done at least 1s after the last execution
const throttled = throttle((name) => displayName(name), 1000);
throttled('Thomas'); // will execute displayName and display 'Thomas'
setTimeout(() => throttled('Bastien'), 1500); // will execute displayName and display 'Bastien'
throttled('Antoine'); // will not execute displayName

That might solve our problem... or not!
This will prevent intempestive executions: but while it does, it might also prevent crucial executions. If the user resize the window within the time interval, meet the condition and stop resizing before a new interval begins, the treatment will never be triggered.

We cannot risk it.

This is where debounce comes in handy.
Debounce will execute the function, only it will reset the interval everytime the event is dispatched and, once the user has finished to do whatever s.he wanted to do, the function will finally be executed.

This guarantee us the function will be executed soon or later. The downside, however, is you cannot expect graphic treatments to be executed properly with this operator, as there is literally a timeout before the treatment can be done.

Let's take the previous example and change throttle for debounce:

function displayName(name) {
  console.log(`Name is ${name}`);
}

// We want the execution to be done at least 1s after the last execution
const debounced = debounce((name) => displayName(name), 1000);

debounced('Thomas'); // (1) SHOULD execute displayName and display 'Thomas' AFTER 1s
setTimeout(() => debounced('Bastien'), 1500); // (2) will trigger after 1.5s, execute displayName and display 'Bastien'
debounced('Antoine'); // (3) will cancel (1) and set a new timeout.

As we can see, debounce allows the displayName function to be properly executed.
And so, in our case, we might want something like that:

function treatment() {
  if (window.innerWidth >= 1000) {
    // do some stuff
  }
}

window.onresize = debounce(() => treatment(), 100);

Operators implementation

I found the implementation in the excellent book Discover Functional JavaScript by Cristian Salcescu.

Throttle

function throttle(fn, interval) {
  let lastTime;
  return (...args) => {
    if(!lastTime || ((Date.now() - lastTime) >= interval)) {
      fn(...args);
      lastTime = Date.now();
    }
  }
}

Debounce

function debounce(fn, wait) {
  let timer;
  return (...args) => {
    clearTimeout(timer);
    timer = setTimeout(() => fn(...args), wait);
  }
}

Starting with AlpineJS

Thomas Toledo-Pierre — Fri, 03 Jan 2020 22:39:19 +0000

Note: The sources can be found on my Github.

Today, a lot of JavaScript frameworks, libraries and tools are rising, and it is often hard to know which one to choose.

I personally like to work with Angular, but React gained more popularity, alongside with Vue. Some, like KnockoutJS, are almost forgotten nowadays, while others like Reason (more a language than a framework) and SvelteJS are gaining in popularity.

So, while I was going to start and learn React (it would be about time), I could not help but try a new challenger, which came out about a month ago.

Please welcome AlpineJS!

AlpineJS is meant to be a much lighter library than Vue or React, while having a syntax entirely borrowed from Vue (to quote the author).

Why AlpineJS?

You are right: why would you bother learning, AGAIN, a new tool while there are so many others, with such huge communities around them?

Well here are a few pros:

you get to follow the evolution of a library from the beginning, and, why not, contribute;
I have got a hunch AlpineJS will surely gain some popularity during 2020;
while React and Vue are acclaimed by a lot of developers, AlpineJS present a much lighter way of doing front-end Web, much more closer to the basics than today's framework (and I do love the basics).

Cons:

it is new, so not everything is perfect about it;
you might struggle a bit before figuring how it actually works;
I told you I got a hunch about this framework's future popularity, but you cannot be certain of that.

How does it work?

Let us write our first component! We are going to write a really simple and minimalist TodoList. This first article WILL NOT provide a full solution, as AlpineJS is still in development as I am writing these lines.
Updates will follow.

Setting up the env

So, first, let us install AlpineJS.

npm i alpinejs

We are going to use the node package AlpineJS in this example, but you can also use the CDN.
As said in the documentation, we need to add some polyfills for IE11.

So, create a directory called src. We will create all of our app files in it from now on. Then, create an index.html with the following code:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <title>TODO LIST - ALPINEJS</title>
    <link rel="stylesheet" href="./css/tasks.css">
    <script src="https://polyfill.io/v3/polyfill.min.js?features=MutationObserver%2CArray.from%2CArray.prototype.forEach%2CMap%2CSet%2CArray.prototype.includes%2CString.prototype.includes%2CPromise%2CNodeList.prototype.forEach%2CObject.values%2CReflect%2CReflect.set"></script>
    <script src="https://cdn.jsdelivr.net/npm/proxy-polyfill@0.3.0/proxy.min.js"></script>
</head>
<body>
    <section id="add-task-container">
        <form>
            <input type="text">
            <button type="submit">Add task</button>
        </form>
    </section>
    <section id="list-tasks-container">
    </section> 
</body>
</html>

Ok so we have our index.html, which is good. Now, we need to import the AlpineJS module.
As we installed it as a node module, a way to import it is to create an app.js file in a directory named cjs-modules and to use the CommonJS norm as following:

'use strict'
let Alpine = require('alpinejs');

// DO NOT WRITE Alpine.start(); or every event will fire twice

But now, our app.js file is a node module and cannot be used in front-end scripts and HTML pages, can it?
Well fortunately for us, there is a node package called gulp-bro (gulp-browserify is now blacklisted by NPM). This package allows us to use Browserify, a powerfull tool for using node modules in our front-end apps.

So in your terminal:

npm install -D gulp gulp-bro

Why are we using gulp? It is purely an arbitrary choice I made. You could use grunt, webpack, or anything else. We are also going to use a package called browser-sync. BrowserSync allows you to live-refresh your browser when you modify your code.

npm install -D browser-sync

So now, back into our index.html file.
Just add the following:

<script src="./app.js"></script>

Before testing anything, we still need to set our dev environment. We are going to create a gulp job in a gulpfile.js located at the root of your project.

Write the following:

// src and dest are for moving files
// watch is for Gulp to trigger tasks anytime the watched files are modified
// task is to register a task in Gulp
const { src, dest, watch, task } = require('gulp');

// bro is for browserify
const bro = require('gulp-bro');

// browserSync
const browserSync = require('browser-sync').create();

// our build function
function _build() {
    // take every commonJS module, browserify them and put them into ./dist
    src('./src/cjs-modules/*.js')
        .pipe(bro())
        .pipe(dest('./dist'));

    // take every JS script, and put them into ./dist
    src('./src/scripts/**/*.js')
        .pipe(dest('./dist'));

    // take every HTML and CSS and put them into ./dist
    src(['./src/**/*.html', './src/**/*.css'])
        .pipe(dest('./dist'));
}

// our watch function
function _watch() {
    watch(['src/*/*.js', 'src/**/*.html'], _build);
    watch(['src/*/*.js', 'src/**/*.html']).on('change', browserSync.reload);
}

// our serve function
function _serve() {
    _build();
    browserSync.init({
        server: "./dist"
    });

    _watch();
}

// registering a 'serve' task so we can trigger the building and serving with
// gulp serve
task('serve', _serve);

Ok so, here we are. This should be your minimum setting before testing anything. But we're not entirely done. In your package.json file, add the following script:

"start": "gulp serve"

That way, you can launch the build and the app by typing either npm start or gulp serve.

First launch

Launch the app with npm start or gulp serve. If everything is good, you should see a page with an input, a button, and no error in your browser console.

Data binding

AlpineJS does not use any Virtual DOM. This is quite the challenge, but it allows us to develop faster apps.

So, first, how does AlpineJS work with data binding?

According to the documentation, you have a few directives you can use. One of them is x-data. This directive allows you to declare the variables you are going to use in you page / component.

Here, we are going to use two variables:

task, which will first only contain a label;
tasks, which will be an array for all the tasks we will create;

So, on the <body> or a <section> container, write:

<body x-data="{tasks: [], task: {label: ''}}">

We will use those variables later.

Now, we would like to bind some data to our form. As in Angular, AlpineJS provides a directive called x-model, which we can use as double binding. Here, we are going to bind task (declared with x-data) to our input. Update your HTML as follow:

<input type="text" x-model="task.label">

Now, everything we type in the input will be affected to the label property of our task variable.

That's great and all, but there is still a problem (amongst others): when we click on "submit", the page is reloaded. This is because of the default behavior of a form and a submit button.
Lucky for us! AlpineJS provides an x-on directive in order to play with events!

One of its features is x-on:[event name].prevent, which does the same as event.preventDefault().
So, on your <form> tag, add the following:

<form x-on:submit.prevent>

That way, the page should not reload anymore when hitting the submit button.

Adding the tasks

As AlpineJS is not complete yet, we will have to do a bit of a work in order to achieve what we want to do.

First of all, we want to bind a behavior to a click event, for when we submit the form. So:

<button type="submit" x-on:click="tasks = addTask(task, tasks);">Add task</button>

Now, we need to implement the addTask method.

Create a directory called scripts, and inside, create a script called functions.js. We are going to keep it simple and store every function in that file for now.

In this file, create a function called addTask. This function will take two arguments: the task to add, and the list to which add the task.

function addTask(task, tasks) {
    // if we do something like [...tasks, task], then we will
    // still have a reference over the task object, which is bound with
    // x-model, making our list to have multiple references to this object
    // And we do not want that.
    return [...tasks, {...task}]
}

Do not forget to link it to your HTML:

<script src="./functions.js"></script>

Before going further: why don't we simply use tasks.push(task)? Well, for now, if we do that, the bound variable in our HTML will not be updated, and we will not be able to display its content. So, we need to return an updated copy of it, and then re-affect it, so our HTML is updated.

Displaying the tasks

Unfortunately, AlpineJS does not provide yet a x-for feature (as explained here). There is a PR regarding an x-html directive right here.

We can still display our data by doing this:

<section id="list-tasks-container" x-text="JSON.stringify(tasks)">
</section>

Normally, everytime you push the "submit" button, the data will be refreshed and displayed.

Contributing

AlpineJS is on the rise, but still needs your help and support. Feel free to contribute to this very promising framework, to test and try it.

This article will be updated from time to time as AlpineJS evolves.

Please feel free to tell me if anything was unclear in my instructions, or if you did another way. I am also interested about your thoughts about what should be the best practices when developing with AlpineJS.

Thanks for reading!

The cost of CSS selectors

Thomas Toledo-Pierre — Sun, 15 Dec 2019 01:29:33 +0000

When writing CSS, you are likely to find yourself having to write some selectors. For instance, let us say you have the following HTML structure:

<section class="info">
   <div id="avatar"></div>
   <ul>
      <li>John Doe</li>
      <li>42 y.o</li>
   </ul>
</section>
<section class="feed">
   <div class="post">
      <p>....</p>
   </div>
   <div class="post">
      <p>....</p>
   </div>
   <div class="post">
      <p>....</p>
   </div>
</section>

If you were to add some CSS to your elements, how would you write your selectors?

Go full selectors

If, like me, you are a bit of a maniac, you might have a tendency to use a lot of selectors.
Naively, you would write something like that:

section.info { /* css rules */ }

section.info > #avatar { /* css rules */ }

section.info > ul { /* css rules */ }

section.info > ul > li { /* css rules */ }

section.info > ul > li:nth-of-type(1) { /* css rules */ }

section.feed { /* css rules */ }

section.feed > div.post { /* css rules */ }

Pros

we know where every rule is applied;
no or little risk of side-effects;
more specific;
every selector allows me to use those classes on other elements and apply different CSS rules.

Cons

a lot of work for the browser;
poor performances;
some selectors are useless (like section.info > #avatar);
if I decide, for instance, to change my sections for divs, then my CSS will not work until I change it too.

Performance is important

Now, we sure do want to have a clean and readable code. But we also want to have a fast website! So, what could we do?

First of all, we could change that awful selector section.info > #avatar by #avatar. In fact: an ID is always unique on a page. So, unless your stylesheet might be used on other pages where your avatar has a different style and is located elsewhere (i.e: has another selector), there is absolutely no need to specify a full selector when #avatar is enough.

Secondly, let us remove the section.info and use, instead, .info. The same goes for section.feed and div.post. We can obviously just use .feed and .post.

So, we would have the following CSS:

.info { /* css rules */ }

#avatar { /* css rules */ }

.info > ul { /* css rules */ }

.info > ul > li { /* css rules */ }

.info > ul > li:nth-of-type(1) { /* css rules */ }

.feed { /* css rules */ }

.feed > .post { /* css rules */ }

It is shorter, and still readable. Plus, it is more performant, because the browser will not have to look for every section, then every section which have the class "info" or "feed": it will just go straight to the elements having the classe "info" or "feed" and basicaly apply the style on them.

But now, why is this code more performant than the previous one?

CSS Specificity

CSS Specifity is a concept we all need to understand when we write CSS.
In CSS, it is possible to point the same element with two or more different CSS rules.

For instance, if we have the following HTML structure:

<section id="container">
 <!-- some html code inside -->
</section>

As we only have one section, we could either use section {} or #container {}. In this case, it will render the same thing. But there is one option that is more performant than the other.
In fact, selecting an element by its ID is far more specific, thus performant, than selecting an element with an element selector.

Specifics values

In CSS, there are specifics values regarding the type of selectors we use:

inline style has a specific value of 1000 (that's why it can be used on performance purposes);
id selector has a specific value of 100;
class, pseudo-class and attribute selectors have a specific value of 10;
element and pseudo-element selectors have a specific value of 1;
the universal selector * has a specific value of 0;
the !important keyword gives a 1000 specific value to your CSS rules.

Knowing this, we can now understand how a browser does work when it come to choose between to selectors: it will simply, and always, use the selector with the strongest specific value. In our previous example, section {} had a specific value of 1, whereas #container {} had a specific value of 100, thus will be choosen by the browser.

I just explained how the browser were choosing between two selectors, based on the concept of specificities and specifics values.
But how having more specific selectors ensure we have better performances? And what happens when we combine selectors?

Selectors combination

Consider the previous code

<section class="info">
   <div id="avatar"></div>
   <ul>
      <li>John Doe</li>
      <li>42 y.o</li>
   </ul>
</section>
<section class="feed">
   <div class="post">
      <p>....</p>
   </div>
   <div class="post">
      <p>....</p>
   </div>
   <div class="post">
      <p>....</p>
   </div>
</section>

and the following CSS:

.info { /* css rules */ }

#avatar { /* css rules */ }

.info > ul { /* css rules */ }

.info > ul > li { /* css rules */ }

.info > ul > li:nth-of-type(1) { /* css rules */ }

.feed { /* css rules */ }

.feed > .post { /* css rules */ }

What are the specifics values for each selectors ?

.info { /* css rules */ }: 10;
#avatar { /* css rules */ }: 100;
.info > ul { /* css rules */ }: 10 + 1 => 11;
.info > ul > li { /* css rules */ }: 10 + 1 + 1 => 12;
.info > ul > li:nth-of-type(1) { /* css rules */ }: 13;
.feed: 10
.feed > .post: 20;

As you can see, the selectors with element selectors are the weakest, while the ID selector is the one with a higher specific value.

Performance FTW (?)

In our case, we first had more specific selectors and then less specific selectors, and yet the second version of the CSS code was more performant. Why is that?
Well, in the first version, the browser had to lookup every section tag, then find those with a specific class on it, etc, etc. Although it was more specific, it would also bring slower performances, because of the element selector.
Beside, it was useless in this case.

By removing it, we give the browser the only useful amount of information it needs.

But wait! If specifics values are greater with IDs, and if IDs are unique in a page, why don't we simply use IDs? Or better, why don't we just use inline style?

Semantic over performance

A code that brings a lot of performance is nothing if nobody can understand it. In my opinion, you need to always make the readability of your code your priority. Your code is not finished once you wrote it.
Your code will live after you, and someone will take care of it: if we cannot read it, then it will likely go to the trash.

A code with a good semantic is of better quality than a code with bad semantic. A good compromise that we use a lot is classes: classes do have a less specific value than IDs, but they bring semantic information and have greater specific value than elements.

So, unless you are working for Amazon or Google, performance might not be your #1 priority: you might first want to focus on writing proper selectors, and, of course proper CSS rules.

Why I use semantic HTML

Thomas Toledo-Pierre — Mon, 18 Nov 2019 22:30:12 +0000

Wether you are a beginner, or an expert in development, there is one thing you are likely to forget when it comes to coding HTML documents, and that thing is semantic HTML.

Until a few years back, I did not know much about that. To me, HTML was all about div and span, maybe some classes and ids, a bit of CSS, and that was it.
But one day, I wanted to have a new job in a new company. During the interview, the recruiters asked me to explain, starting from a mock-up, how I would organize an HTML document in order to obtain the same result as shown in the said mock-up.

Divs and spans are not enough

Of course, as a young developer, with not much knowledge, and because I never learnt much more, I started to use a lot of divs. Then, they asked me what CSS rules I would apply to which elements, and how. That part was a bit harder, as I was not really at ease with CSS.
And finally, they tested me on JavaScript (that part was my favorite).

I though I did good.
I did not. But why is that? Was I too junior for them? Was I lacking any skills?

Well, yes and no. Of course, I was a junior, but apparently I did good in JavaScript and CSS. So, if I did good, that meant I was not lacking any skills, was I? Wrong again!
Because there was one thing I did, regarding the HTML part of the test. A tiny, little, thing: I only used divs and spans.

Of course, divs are important! They are containers, that can be used to apply massive amount of CSS on many elements, and can be easily manipulated by JavaScript! They are so cool, so easy to use! What is a div? A div is just a div. A simple box, where you put anything you want inside.
They are perfect. I love divs.

And it is the same for spans. I also love spans. They do not have any dimension: they do not require any space on a page, unlike divs, so they can be used to wrap some texts and then apply CSS rules and/or JavaScript treatments to them.

I love spans.

But divs and spans have a problem, and a big one: they are not semantic. They do not bring any information regarding the meaning of your content. Would you have three divs containing two divs each, or one big div containing five divs, and that would be the same: no meaning, just boxes.

And that is why I failed my test: I did not use anything else to organize my page, so it meant I did not know how to use properly HTML.

Divs and spans are meaningless

As I said, divs and spans do not bring any semantic to your page. It means that, by using only those kind of containers, you are drowning your content into a nest of meaningless code.

It also means that your content, if it is not for the layout, can do without any of your divs.

Semantic HTML to the rescue

HTML5 comes with a lot of semantic tags: section, article, header, nav, time, are some of them.

Their primary use is to bring meaning to our HTML pages. It also allows us to organize more clearly our documents.

Let us take an example:

Which one of those two snippets tells you the most about how your page is organized and what part is supposed to be?

Example 1

<!DOCTYPE html>
<html>
  <head>
    <title>Some page</title>
    <meta charset="utf-8">
    <meta name="author" content="Thomas Toledo">
    <noscript>JavaScript not supported!</noscript>
  </head>
  <body>
    <div>
      <a href="#">link 1</a>
      <a href="#">link 2</a>
      <a href="#">link 3</a>
    </div>
    <div>
      <div>
        <p>Some text</p>
      </div>
      <div>
        <p>Some content</p>
        <ul>
          <li>list item 1</li>
          <li>list item 2</li>
          <li>list item 3</li>
        </ul>
      </div>
      <div>
        <div>
          <figure>
            <img src="...">
            <figcaption>some legend</figcaption>
          </figure>
          <p>Some text</p>
        </div>
        <p>
          Some text
        </p>
      </div>
      <div>
        <table>
          <thead>
            <tr>
              <th>header 1</th>
              <th>header 2</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td>data 1</td>
              <td>data 2</td>
            </tr>
          </tbody>
        </table>
      </div>
      <div>
        Some text
      </div>
    </div>
  </body>
</html>

Example 2

<!DOCTYPE html>
<html>
  <head>
    <title>Some page</title>
    <meta charset="utf-8">
    <meta name="author" content="Thomas Toledo">
    <noscript>JavaScript not supported!</noscript>
  </head>
  <body>
    <nav>
      <a href="#">link 1</a>
      <a href="#">link 2</a>
      <a href="#">link 3</a>
    </nav>
    <article>
      <header>
        <p>Some text</p>
      </header>
      <section>
        <p>Some content</p>
        <ul>
          <li>list item 1</li>
          <li>list item 2</li>
          <li>list item 3</li>
        </ul>
      </section>
      <section>
        <div>
          <figure>
            <img src="...">
            <figcaption>some legend</figcaption>
          </figure>
          <p>Some text</p>
        </div>
        <p>
          Some text
        </p>
      </section>
      <section>
        <table>
          <thead>
            <tr>
              <th>header 1</th>
              <th>header 2</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td>data 1</td>
              <td>data 2</td>
            </tr>
          </tbody>
        </table>
      </section>
      <footer>
        Some text
      </footer>
    </article>
  </body>
</html>

In the first snippet of code, you could easily spot a global div, which would have had one purpose: containing everything. But then? Nothing tells me I am going to have a header, three sections and a footer. I could as well have a global div, organized in three sections. Something like this:

<!DOCTYPE html>
<html>
  <head>
    <title>Some page</title>
    <meta charset="utf-8">
    <meta name="author" content="Thomas Toledo">
    <noscript>JavaScript not supported!</noscript>
  </head>
  <body>
    <nav>
      <a href="#">link 1</a>
      <a href="#">link 2</a>
      <a href="#">link 3</a>
    </nav>
    <div>
      <div>
        <p>Some text</p>
      </div>
      <section>
        <p>Some content</p>
        <ul>
          <li>list item 1</li>
          <li>list item 2</li>
          <li>list item 3</li>
        </ul>
      </section>
      <section>
        <div>
          <figure>
            <img src="...">
            <figcaption>some legend</figcaption>
          </figure>
          <p>Some text</p>
        </div>
        <p>
          Some text
        </p>
      </section>
      <section>
        <table>
          <thead>
            <tr>
              <th>header 1</th>
              <th>header 2</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td>data 1</td>
              <td>data 2</td>
            </tr>
          </tbody>
        </table>
      </section>
      <div>
        Some text
      </div>
    </div>
  </body>
</html>

And that would still be okay.
The only difference would be the meaning of my HTML code: in the first case, there is no meaning. I don't know what is what - there are only divs.
In the second case, it's obviously an article.
In the third case, it's simply a container with three sections, each independant from the others.

Yet, the structure remains the same: only the semantic changes.

But is it still ok to use divs and spans?

The answer is yes.
If div (and span) were not OK to use anymore, we would not find them anywhere.
But, the thing is: we find them everywhere. Why is that?

I see a few reasons:

it is easier to use divs without having to think about how your page is going to be semantically organized;
nowadays, we have a lot of layout needs, and divs are perfect for layout divs;
developers seem not to know enough about semantic HTML;
they are still usefull when you do not have any specific semantic for an element: in that case, just use div and, eventually, put some classes on it with semantic names;

I still use divs in my code (and more than I would admit), but I try to keep them only for layout purposes.
Moreover, semantic tags can also be styled with CSS.

So, given the fact they bring more semantic to the page and help you have a clearer view of its organization, I go with semantic tags. It does not cost anything, and have a real impact both on code quality and SEO.

If you are interested in semantic HTML, you can start with the MDN page about it, and then start to use it, step by step, in your code!

DEV Community: Thomas Toledo-Pierre

Hexagonal Architecture in Angular - A Practical, Minimal Use Case

The structural Drift of Growing Angular Applications

Business Logic Leaking into Components and Services

Tight Coupling Between UI, HTTP, and Domain Logic

Difficult Unit Testing: TestBed Everywhere

Hard-to-Replace Infrastructure

What is hexagonal architecure?

Also Called Ports and Adapters

Domain at the Center

Application Layer Orchestrates Use Cases

Infrastructure Implements External Concerns

UI Is Just an Adapter

The Dependency Rule

The Use Case: Create a Support Ticket

Scenario

Business Rules

Goal of the Use Case

Project Structure

Setting up your project

Domain => Business Concepts and Rules

entities

value-objects

Writing ports

TicketRepositoryPort

Application => Use Cases

Writing use cases

CreateTicketUseCase

Why This Matters

Infrastructure => Technical Implementations

HttpTicketRepositoryAdapter.ts

UI => Angular Components (Input Adapter)

Testing the architecture

Core Testing

Installing and configuring Vitest

Implementing our fakes

Testing the HttpTicketRepositoryAdapter

Testing the http-ticket.mapper.ts

Testing the CreateTicketUseCase

Implementing FakeTicketRepositoryAdapter

Implementing our test

Testing the UI

What We Gained

Clear Separation of Concerns

Framework Independence

Replaceable Infrastructure

High Testability

Scalability for Teams

Common Mistakes in Angular Hexagonal Implementations

Putting Business Logic in Angular Services

Letting Adapters Leak into the Domain

Injecting HttpClient Directly into Components

Overengineering Too Early

When to Use (and When Not To)

Use It When

Avoid It When

Conclusion

How I created an Observable library - part 1

TL;DR

What should be the MVP?

The technical stack

The first implementation

TDD all the way!

The Observable class

The Subscriptions and the Subscribers

pipe and the operators

Follow for the next part

A Simple Observable Class

What our Observable class should do

A first implementation

The subscribe method

The next method

The pipe method

The unsubscribe method

Debounce and Throttle

The problem

Debounce and Throttle

Operators implementation

Throttle

Debounce

`entities`

`value-objects`

`TicketRepositoryPort`

`CreateTicketUseCase`

`HttpTicketRepositoryAdapter.ts`

Testing the `HttpTicketRepositoryAdapter`

Testing the `http-ticket.mapper.ts`

Testing the `CreateTicketUseCase`

Implementing `FakeTicketRepositoryAdapter`

The `Observable` class

The `Subscriptions` and the `Subscribers`

`pipe` and the operators

What our `Observable` class should do

The `subscribe` method

The `next` method

The `pipe` method

The `unsubscribe` method