Bloc is a very widely used state manager in the Flutter community, but during my career I've seen many developers using it in a wrong way and the documentation is not very clear about how to use it effectively and how to architect a good application using Bloc.

In this article I'll try to explain my way of using Bloc to manage state in a Flutter application.

What is Bloc?

Bloc (Business Logic Component) is a state management pattern that separates your app's business logic from the UI. It works by receiving events as input and emitting states as output, so the UI only listens to state changes and rebuilds accordingly. This keeps the code predictable, easy to test, and easy to maintain.

Bloc vs Cubit

The Bloc library contains not only the Bloc class and all its related helpers, but also the Cubit class.

Cubit is a simpler, lighter alternative to Bloc. It's essentially Bloc without events: instead of emitting states in response to events, a Cubit exposes methods that you call directly, and those methods emit new states. Both Bloc and Cubit are part of the same bloc package and share the same underlying stream-based architecture.

Main difference: Bloc uses events as input; Cubit uses method calls. That makes Cubit simpler and less boilerplate-heavy, while Bloc gives you a more traceable, event-based history that's useful for debugging and logging. Here's what that looks like in code.

Bloc — events as input:

// Events
sealed class CounterEvent {}
class IncrementPressed extends CounterEvent {}
class DecrementPressed extends CounterEvent {}

// Bloc: maps events → states
class CounterBloc extends Bloc<CounterEvent, int> {
  CounterBloc() : super(0) {
    on<IncrementPressed>((event, emit) => emit(state + 1));
    on<DecrementPressed>((event, emit) => emit(state - 1));
  }
}

// Usage
context.read<CounterBloc>().add(IncrementPressed());

Cubit — methods as input:

// Cubit: methods emit directly
class CounterCubit extends Cubit<int> {
  CounterCubit() : super(0);
  void increment() => emit(state + 1);
  void decrement() => emit(state - 1);
}

// Usage
context.read<CounterCubit>().increment();

• When to use Cubit: Prefer Cubit for straightforward flows where you don't need event-level visibility (e.g. simple forms, local UI state).
• When to use Bloc: Use Bloc when you need event traceability, complex flows with many event types, or when debugging and logging events is important (e.g. analytics, undo/redo, or large features with many interactions).

Freezed and Equatable

Now that we have a basic understanding of what Bloc is, let's talk about the libraries that will help with the definition of our states and events.

• Freezed is a library that allows you to easily create immutable objects in Dart. It's a powerful tool that helps you manage states in your application.

• Equatable is a library that allows you to easily compare objects in Dart. It's a powerful tool that helps you manage state in your application.

Why use Freezed or Equatable?

Bloc compares states with == to decide whether to notify listeners. If you use plain classes, two instances with the same data are treated as different (reference equality), so Bloc may emit "new" states that are logically unchanged and cause unnecessary rebuilds.

Equatable fixes this by letting you compare objects by their fields. When two states have the same values, they're considered equal—Bloc won't emit again, and your UI won't rebuild needlessly. It also reduces boilerplate for == and hashCode.

Freezed goes further: it generates immutable classes, copyWith, and often value equality as well. It excels at modeling states and events as union types (e.g. Loading | Success(data) | Error), so you get exhaustive pattern matching and clear, type-safe state definitions. Let's see the difference in code.

Without Equatable — reference equality causes extra emissions:

class UserState {
  final String name;
  UserState(this.name);
}
// UserState('Alice') != UserState('Alice')  → Bloc emits, UI rebuilds

With Equatable — value equality prevents unnecessary rebuilds:

class UserState extends Equatable {
  final String name;
  UserState(this.name);
  @override
  List<Object?> get props => [name];
}
// UserState('Alice') == UserState('Alice')  → no emit, no rebuild

With Freezed — union types, immutability, and copyWith in one:

@freezed
class UserState with _$UserState {
  const factory UserState.initial() = _Initial;
  const factory UserState.loading() = _Loading;
  const factory UserState.loaded(User user) = _Loaded;
  const factory UserState.error(String message) = _Error;
}

Together, they keep your states and events immutable, comparable by value, and easy to maintain, which aligns perfectly with Bloc's design and helps avoid bugs and performance issues.

Why Immutability Matters for States and Events

Immutability means that once an object is created, it cannot be changed. To represent a new state, you create a new object instead of modifying the existing one. This might seem like extra work, but it has profound benefits for state management.

• Predictability and traceability. Each state is a snapshot in time. When something goes wrong, you can look at the state that was emitted and know exactly what the app was representing no hidden mutations after the fact. Bloc's event → state flow becomes a clear, auditable log: given these events, you get these states. With mutable objects, state can change from anywhere, at any time, making it nearly impossible to reason about what the UI was showing when a bug occurred.

• No shared mutable state bugs. When you pass a mutable object around, any widget, callback, or async operation can mutate it. Multiple parts of the codebase might read the "same" state while another part changes it, leading to race conditions, inconsistent UI, and bugs that only appear under certain timing. With immutability, once a state is emitted, it's frozen. Nobody can alter it. The only way to get a new state is for the Bloc to emit one—so there's a single, clear source of truth.

• Safe async and concurrent code. In async flows, mutable state can change between when you read it and when you use it. By the time a Future completes, the object you captured might have been modified. Immutable states eliminate this: the state you received is the state you have, forever. No one can change it from under you, which makes async logic much easier to reason about and debug.

• Easier testing. Immutable states and events are trivial to test. Create a state, pass it to a widget or validator, and it never changes. No test order dependencies, no setup/teardown for shared mutable globals, no flakiness from hidden state. You can assert on exact values and be confident nothing else modified them.

• One-way data flow. Bloc is built on the idea that state flows in one direction: Bloc emits, UI reacts. Immutability enforces this. The UI cannot accidentally mutate state; it can only dispatch events. The Bloc is the only place that produces new states. That constraint makes the architecture simple to understand and prevents entire classes of bugs (e.g. a widget "fixing" state locally and breaking other parts of the app).

• Events should be immutable too. Events represent "what happened" at a point in time. If an event could be mutated after being dispatched, the Bloc might process a different payload than what was originally sent, or the same event object could be reused and modified across multiple dispatches, leading to unpredictable behavior. Immutable events ensure each dispatch is a well-defined, unchangeable record of user intent or system input. Here's a visual contrast.

Mutable — dangerous, anyone can change it:

class BadState {
  List<User> users = [];  // mutable
}
// Some widget: state.users.add(newUser);  ← hidden mutation, hard to trace

Immutable — create new state instead:

class GoodState {
  final List<User> users;
  GoodState(this.users);
}
// New state: GoodState([...state.users, newUser])  ← explicit, traceable

With Freezed copyWith — ergonomic updates without mutating:

state.copyWith(users: [...state.users, newUser]);

In short, immutability turns state and events into stable, predictable values that flow through your app in a clear, auditable way. It's not just a style choice—it's what makes Bloc's architecture reliable and maintainable at scale.

Sealed classes and Pattern Matching

Before Dart 3, modeling a finite set of states or events (e.g. Loading | Success | Error) required abstract classes with multiple implementations. The compiler couldn't know all possible subtypes, so you had to remember to handle every case manually—forgetting one often led to runtime errors or silent bugs. Dart 3 introduced sealed classes and pattern matching, which solve this at the language level.

• What is a sealed class? A sealed class is a superclass whose direct subtypes are known and restricted by the compiler. You declare all possible variants in the same library (or with sealed), and no one can add new subtypes elsewhere. For Bloc, that means your state can be Loading, Success, or Error—and the compiler knows that's the complete list.

• How Freezed uses them. Freezed generates sealed unions for you. When you define @freezed states like Loading, Success(data), and Error(message), Freezed produces a sealed class hierarchy. Each variant is a distinct subtype, and together they form a closed, exhaustively known set.

• What is pattern matching? Pattern matching lets you branch on the shape of a value—its type and fields—in a single expression. In Dart, you use switch (or switch expressions) with pattern matching: the compiler checks that you've handled every possible case. If you add a new state variant later and forget to handle it, you get a compile error instead of a runtime crash.

• The real benefit. Sealed classes + pattern matching give you exhaustiveness checking. When you switch on state, the compiler ensures you handle Loading, Success, and Error. Add a new variant like Refreshing? The compiler tells you exactly where you need to update your code. That turns "did I handle every case?" from a manual, error-prone checklist into something the compiler enforces—making your Bloc states safer and easier to evolve.

Define states with Freezed:

@freezed
class UserState with _$UserState {
  const factory UserState.initial() = _Initial;
  const factory UserState.loading() = _Loading;
  const factory UserState.loaded(User user) = _Loaded;
  const factory UserState.error(String message) = _Error;
}

Pattern match in the UI — the compiler enforces that all cases are handled:

return switch (state) {
  UserState.initial() => const Text('Tap to load'),
  UserState.loading() => const CircularProgressIndicator(),
  UserState.loaded(:final user) => Text(user.name),
  UserState.error(:final message) => Text('Error: $message'),
};

Add a new variant like UserState.refreshing()? The compiler will error until you handle it everywhere. That's the power of exhaustiveness checking—no forgotten cases at runtime.

Multi-state vs Mono-state

There are two main ways to define Bloc state: multi-state (separate state classes for each variant, like union types) and mono-state (a single state class with variables inside—e.g. an enum for status plus nullable data and error fields). Both are valid, but they lead to different ergonomics in the Bloc and in the UI.

Mono-state

One class, multiple variables:

class UserState {
  final UserStatus status;
  final User? user;
  final String? errorMessage;
  UserState({required this.status, this.user, this.errorMessage});
}
enum UserStatus { initial, loading, loaded, error }

• The benefit: fewer classes, simple to add new statuses.
• The downside: invalid combinations are possible (e.g. status == loaded but user == null), and the UI has to reason about which fields are valid for each status. You end up with if (state.status == UserStatus.loaded && state.user != null)—manual guards and a less expressive model of what the app state actually is.

Multi-state

One variant per state, each with only the data it needs:

@freezed
class UserState with _$UserState {
  const factory UserState.initial() = InitialUserState;
  const factory UserState.loading() = LoadingUserState;
  const factory UserState.loaded(User user) = LoadedUserState;
  const factory UserState.error(String message) = ErrorUserState;
}

• The benefit: each state is self-describing. UserState.loaded(user) always has a user; UserState.error(message) always has a message. No null checks, no invalid combinations. The compiler and pattern matching enforce that you only access data when the state actually contains it.
• The downside: more classes, more boilerplate to add new statuses. And some ambiguity when defining read state and write state (will see that later).

I prefer multi-state for a more elegant UI and a more expressive way to model app states. The UI maps directly to the states: each branch of the switch handles exactly one meaningful state, and the data is available by construction. The code reads like "when initial, show this; when loading, show that; when loaded, show the user." It makes the flow of your app explicit and keeps the UI free of defensive null checks and status flags. Mono-state can work for very simple flows, but as complexity grows, multi-state scales better and stays easier to reason about.

BlocBuilder and BlocListener with multi-state

BlocBuilder rebuilds the widget when the state changes. Use it for the visual representation of state—what the user sees. With multi-state, you typically switch on the state and return a widget for each variant. No buildWhen needed if you want to react to every state; use buildWhen only when you want to skip rebuilds for certain transitions (e.g. don't rebuild when going from loading to error if both show the same scaffold).

BlocBuilder<UserBloc, UserState>(
  builder: (context, state) => switch (state) {
    InitialUserState() => ElevatedButton(
        onPressed: () => context.read<UserBloc>().add(UserLoadRequested()),
        child: const Text('Load user'),
      ),
    LoadingUserState() => const Center(child: CircularProgressIndicator()),
    LoadedUserState(:final user) => UserProfile(user: user),
    ErrorUserState(:final message) => Text('Error: $message'),
  },
)

BlocListener runs side effects (snackbars, dialogs, navigation) when the state changes. It does not build widgets—it listens and reacts. Use it for one-time or ephemeral UI feedback that shouldn't be part of the widget tree (e.g. show a snackbar on error, navigate away on success). Prefer listenWhen to avoid running the same effect multiple times for the same logical event.

BlocListener<UserBloc, UserState>(
  listenWhen: (previous, current) => current case UserState.error(),
  listener: (context, state) => switch (state) {
    ErrorUserState(:final message) => ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(content: Text(message)),
    ),
    _ => null,
  },
  child: BlocBuilder<UserBloc, UserState>(...),
)

BlocConsumer combines both when you need listener and builder in the same place—side effects in listener, UI in builder. Use listenWhen and buildWhen to control when each runs.

BlocConsumer<UserBloc, UserState>(
  listenWhen: (prev, curr) => curr case UserState.error(),
  listener: (context, state) => switch (state) {
    ErrorUserState(:final message) => ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(content: Text(message)),
    ),
    _ => null,
  },
  builder: (context, state) => switch (state) {
    InitialUserState() => const Placeholder(),
    LoadingUserState() => const CircularProgressIndicator(),
    LoadedUserState(:final user) => UserProfile(user: user),
    ErrorUserState(:final message) => Text('Error: $message'),
  },
)

Summary: BlocBuilder = rebuild UI. BlocListener = side effects (snackbars, navigation). BlocConsumer = both. With multi-state, pattern matching keeps each branch clean and the compiler ensures you handle every case.

CRUD structure: separating reads and writes

A clean way to structure CRUD is to split reads (the list) from writes (create, update, delete). Use a [Feature]ListCubit to stream or load the list, and a [Feature]Bloc for mutations. The UI uses BlocListener on the mutation Bloc to trigger side effects (e.g. refresh the list, show snackbars)—no need to couple the list logic to mutations.

States and events

ItemsListCubit — read-only, holds the list:

@freezed
class ItemsListState with _$ItemsListState {
  const factory ItemsListState.initial() = InitialItemsListState;
  const factory ItemsListState.loading() = LoadingItemsListState;
  const factory ItemsListState.loaded(List<Item> items) = LoadedItemsListState;
  const factory ItemsListState.error(String message) = ErrorItemsListState;
}

class ItemsListCubit extends Cubit<ItemsListState> {
  final ItemsRepository _repo;

  ItemsListCubit(this._repo) : super(const ItemsListState.initial());

  Future<void> load() async {
    emit(const ItemsListState.loading());
    try {
      final items = await _repo.getItems();
      emit(ItemsListState.loaded(items));
    } catch (e) {
      emit(ItemsListState.error(e.toString()));
    }
  }

  void refresh() => load();
}

ItemsBloc — mutations only:

@freezed
class ItemMutationEvent with _$ItemMutationEvent {
  const factory ItemMutationEvent.create(Item item) = CreateItemMutationEvent;
  const factory ItemMutationEvent.update(Item item) = UpdateItemMutationEvent;
  const factory ItemMutationEvent.delete(String id) = DeleteItemMutationEvent;
}

@freezed
class ItemMutationState with _$ItemMutationState {
  const factory ItemMutationState.initial() = InitialItemMutationState;
  const factory ItemMutationState.creating() = CreatingItemMutationState;
  const factory ItemMutationState.createSuccess(Item item) = _CreateSuccess;
  const factory ItemMutationState.createError(String message) = CreateErrorItemMutationState;
  const factory ItemMutationState.updating() = UpdatingItemMutationState;
  const factory ItemMutationState.updateSuccess(Item item) = UpdateSuccessItemMutationState;
  const factory ItemMutationState.updateError(String message) = UpdateErrorItemMutationState;
  const factory ItemMutationState.deleting() = DeletingItemMutationState;
  const factory ItemMutationState.deleteSuccess(String id) = DeleteSuccessItemMutationState;
  const factory ItemMutationState.deleteError(String message) = DeleteErrorItemMutationState;
}

class ItemsBloc extends Bloc<ItemMutationEvent, ItemMutationState> {
  final ItemsRepository _repo;

  ItemsBloc(this._repo) : super(const ItemMutationState.idle()) {
    on<_Create>(_onCreate);
    on<_Update>(_onUpdate);
    on<_Delete>(_onDelete);
  }

  Future<void> _onCreate(_Create e, Emitter<ItemMutationState> emit) async {
    emit(const ItemMutationState.creating());
    try {
      final item = await _repo.create(e.item);
      emit(ItemMutationState.createSuccess(item));
    } catch (e) {
      emit(ItemMutationState.createError(e.toString()));
    }
  }
  // _onUpdate, _onDelete similar...
}

UI: BlocListener triggers list refresh

When a mutation succeeds, the UI uses BlocListener to refresh the list—no coupling between ItemsBloc and ItemsListCubit. Side effects stay in the UI layer.

BlocListener<ItemsBloc, ItemMutationState>(
  listenWhen: (prev, curr) =>
      curr case ItemMutationState.createSuccess() ||
      curr case ItemMutationState.updateSuccess() ||
      curr case ItemMutationState.deleteSuccess(),
  listener: (context, state) {
    context.read<ItemsListCubit>().refresh();
    ScaffoldMessenger.of(context).showSnackBar(switch (state) {
      CreateSuccessItemMutationState() => const SnackBar(content: Text('Created')),
      UpdateSuccessItemMutationState() => const SnackBar(content: Text('Updated')),
      DeleteSuccessItemMutationState() => const SnackBar(content: Text('Deleted')),
      _ => null,
    });
  },
  child: BlocBuilder<ItemsListCubit, ItemsListState>(
    builder: (context, state) => switch (state) {
      InitialItemsListState() => const SizedBox(),
      LoadingItemsListState() => const Center(child: CircularProgressIndicator()),
      LoadedItemsListState(:final items) => ListView.builder(...),
      ErrorItemsListState(:final message) => Text(message),
    },
  ),
)

CQRS-style: stream the list instead of fetching

You can go further with a CQRS-style read model: the list subscribes to a stream from the repository. When the backend or local store changes (e.g. after create/update/delete), the stream emits and the Cubit emits a new state. No manual refresh()—the list stays in sync automatically.

class ItemsListCubit extends Cubit<ItemsListState> {
  final ItemsRepository _repo;
  StreamSubscription<List<Item>>? _subscription;

  ItemsListCubit(this._repo) : super(const ItemsListState.initial());

  void watch() {
    emit(const ItemsListState.loading());
    _subscription?.cancel();
    _subscription = _repo.watchItems().listen(
      (items) => emit(ItemsListState.loaded(items)),
      onError: (e) => emit(ItemsListState.error(e.toString())),
    );
  }

  @override
  Future<void> close() {
    _subscription?.cancel();
    return super.close();
  }
}

With watch(), you call it once (e.g. when entering the screen). The repository's watchItems() stream (e.g. Firestore, Room, or a local reactive store) pushes updates whenever data changes. Mutations in ItemsBloc write to the same store; the stream emits, and the list updates. No BlocListener needed for refresh—though you may still use it for snackbars or navigation. The read model (list) and write model (mutations) are decoupled; the stream is the bridge.

Bloc is powerful when you lean into it: immutable, multi-state definitions with Freezed and Equatable, sealed classes and pattern matching for exhaustiveness, and a clear split between reads and writes. Use Bloc for traceable mutations, Cubit for simple reads. Let BlocListener handle side effects in the UI, and consider a CQRS-style stream for lists when your data source supports it. This is the approach I've found scales best—state stays predictable, the UI stays clean, and the compiler helps catch mistakes before they reach production. I hope it works for you too.

Creational Design Patterns

The creational design patterns are useful when you have to "create" something (lol).

They includes the following patterns:

• Factory Method
• Abstract Factory
• Builder
• Prototype
• Singleton

Nothing to say more about Creational Patterns in general since it's just "sugar syntax" to group design patterns into parent-classes of designs.

Factory Method

The Factory Method is a Creational Design Pattern that comes in handy when the application requires the creation of the same object multiple times.

To avoid ripeat the logic of the creation of this particular object the Factory Method allows the developer to don't repeat himself.

In a one-line sentence the Factory Method allows the developer to hide the business logic of the creation of an object in the application

Based on that definition we could think that the Factory Method behaves in this kind of way:

• You have some sort of logic behind the creation of an Object
• You do want to avoid repetition
• You create a Factory Method to handle this

Let's see it with a quick example.

class Prodcut {
 private int id;
 private int price;

  public Product(int id, int price) {
    this.id = id;
    this.price = price;
  }

}

class FactoryProduct {
  private static int currentId = 0;

  public static Product createProduct(int price) {
    currentId++;
    return new Product(currentId, price);
  }
}

This example is actually pretty stupid and probably also wrong in terms of logic.

The Factory Method capabilities do not stops here.

The Factory Method can be used to create objects of different classes that share the same parent class, or mor generally, the real benefits of the Factory Method are shown wiht polymorphism.

Let's see a more complex example.

Let's say you have a game in which you have to create space ships. The more the level of the game increases the more the space ships are powerful.

You could have a parent class SpaceShip and then you could have different classes that extends the SpaceShip class.

The Factory Method can be used to create the different space ships based on the level of the game.

abstract class SpaceShip {
  private int health;
  private int damage;

  public SpaceShip(int health, int damage) {
    this.health = health;
    this.damage = damage;
  }

  public void attack() {
    System.out.println("Attacking with " + damage + " damage");
  }
}

class WeakSpaceShip extends SpaceShip {
  public WeakSpaceShip() {
    super(100, 10);
  }
}

class MediumSpaceShip extends SpaceShip {
  public MediumSpaceShip() {
    super(200, 20);
  }
}

class StrongSpaceShip extends SpaceShip {
  public StrongSpaceShip() {
    super(300, 30);
  }
}

class SpaceShipFactory {
  public static SpaceShip createSpaceShip(int level) {
    switch(level) {
      case 1:
        return new WeakSpaceShip();
      case 2:
        return new LevMediumSpaceShipel2SpaceShip();
      case 3:
        return new StrongSpaceShip();
      default:
        return null;
    }
  }
}

In this example whenver we need to create a new space ship we can use the SpaceShipFactory class to create the space ship based on the level of the game.

But let's say taht we also have to create Aliens in the game, also the Aliens increase their power based on the level of the game, but of course the aliens are not space ships, and they have different powers.

In that case the correct way to proceed is to create Factory based on the level of the game.

class Alien {
  private int lifePoints;
  private int criticalDamage;

  public Entity(int lifePoints, int criticalDamage) {
    this.lifePoints = lifePoints;
    this.criticalDamage = criticalDamage;
  }

  public void attack() {
    System.out.println("Attacking with " + criticalDamage + " critical damage");
  }
}

class WeakAlien extends Alien {
  public WeakAlien() {
    super(100, 10);
  }
}

class MediumAlien extends Alien {
  public MediumAlien() {
    super(200, 20);
  }
}

class StrongAlien extends Alien {
  public StrongAlien() {
    super(300, 30);
  }
}

Abstract Factory Method

We just decide, as shown before, that the game has different levels, and also has different entities that has some sort of power based on the level of the game.

In that case we could just create a new Factory for aliens and so having something like this:

class AlienFactory {
  public static Alien createAlien(int level) {
    switch(level) {
      case 1:
        return new WeakAlien();
      case 2:
        return new MediumAlien();
      case 3:
        return new StrongAlien();
      default:
        return null;
    }
  }
}

[!WARNING] This snippet of code is actually bad, because we are repeating the same logic of the SpaceShipFactory class.

Plus if we want to add a new level to the game we then have to edito both the SpaceShipFactory and the AlienFactory classes.

In that case so we have to shift our focus on problem and start thinking about the family of problem.

So the problem is that we have to create different entities based on the level of the game -> So we need a LevelFactory.

This LevelFactory will be abstract since it doesn't have any kind of concrete implementation but it just defines the methods that the concrete factories have to implement.

In that case our concrete Factories will be the Level1Factory, Level2Factory and Level3Factory.

Let's see the code:

abstract class LevelFactory {
  abstract SpaceShip createSpaceShip();
  abstract Alien createAlien();
}

class Level1Factory extends LevelFactory {
  @override
  SpaceShip createSpaceShip() {
    return new WeakSpaceShip();
  }

  @override
  Alien createAlien() {
    return new WeakAlien();
  }
}

class Level2Factory extends LevelFactory {
  @override
  SpaceShip createSpaceShip() {
    return new MediumSpaceShip();
  }

  @override
  Alien createAlien() {
    return new MediumAlien();
  }
}

class Level3Factory extends LevelFactory {
  @override
  SpaceShip createSpaceShip() {
    return new StrongSpaceShip();
  }

  @override
  Alien createAlien() {
    return new StrongAlien();
  }
}

By doing that we actually create a solution for a set of problem (having more levels and more entities that depends on the level of the game), and we can easly add new levels to the game without headache and without going to change any client code that uses our Factories because in that case the benefit is that our client doesn't have to depend on the concrete classes but just on the abstract classes.

In that example the benefit is clear:

abstract class Level {
  private LevelFactory levelFactory;
  private String levelName;

  public Level(LevelFactory levelFactory, String levelName) {
    this.levelFactory = levelFactory;
    this.levelName = levelName;
  }
}

class Level1 extends Level {
  public Level1(LevelFactory levelFactory, String levelName) {
    super(levelFactory, levelName);
  }
}

An actual implementation of this would be:

public class Main {
  public static void main(String[] args) {
    // assuming that the client choose the level 1
    Level1 level = new Level1(new Level1Factory(), "Level 1");
    SpaceShip spaceShip = level.createSpaceShip();
    Alien alien = level.createAlien();

    spaceShip.attack();
    alien.attack();
  }
}

Builder

The Builder is a Creation Design Patterns very very useful and famous. It's mainly used when you have to build an Object and its creation process may involves several steps (and not every step is required) that you want the client to abstract from.

A quick and most famous axample would be an http call in wich you have to "assemble" several pieces togheter (url, headers, body, etc...) in order to create a valid http request, but the deal is that not every http request needs to have a body, or headers, or a specific method, etc...

A quick example to get you in the mood:

public static void main(String[] args) {
  HttpRequest request = new HttpRequest.Builder()
    .setUrl("https://api.example.com")
    .setMethod("GET")
    .setHeaders(new HashMap<String, String>() {{
      put("Authorization", "Bearer 123456");
    }})
    .build();
}

[!NOTE] This is a quick example and it's not a real code that you can run, but it's just to give you an idea of how the Builder Pattern works.

Just for fun let's stick with the SpaceShip example. In the previous example we saw that a SpaceShip can have a health and a damage property. But now let's dive more into the concept of the SpaceShip itself, so more a place in which the atronauts can navigate into the sky and more.

So let's say we materially want to build the Space Ship, a spaceship needs several parts to be built, and not every part is required to build a spaceship.

In that case we can use the Builder Pattern to build the spaceship.

class SpaceShip {
  private String name;
  private String model;
  private int crew;
  private int maxSpeed;
  private Srting fuel;
  private int health;

  public SpaceShip(String name, String model, int crew, int maxSpeed, String fuel, int health) {
    this.name = name;
    this.model = model;
    this.crew = crew;
    this.maxSpeed = maxSpeed;
    this.fuel = fuel;
    this.health = health;
  }
}

public interface Builder {
  void setName(String name);
  void setModel(String model);
  void setCrew(int crew);
  void setMaxSpeed(int maxSpeed);
  void setFuel(String fuel);
  void setHealth(int health);
}

class SpaceShipBuilder implements Builder {
  private String name;
  private String model;
  private int crew;
  private int maxSpeed;
  private String fuel;
  private int health;

  @override
  public void setName(String name) {
    this.name = name;
  }

  @override
  public void setModel(String model) {
    this.model = model;
  }

  @override
  public void setCrew(int crew) {
    this.crew = crew;
  }

  @override
  public void setMaxSpeed(int maxSpeed) {
    this.maxSpeed = maxSpeed;
  }

  @override
  public void setFuel(String fuel) {
    this.fuel = fuel;
  }

  @override
  public void setHealth(int health) {
    this.health = health;
  }

  public SpaceShip build() {
    return new SpaceShip(this.name, this.model, this.crew, this.maxSpeed, this.fuel, this.health);
  }
}

Of course in this case we are using primitives data types, but you can also build up more complex examples.

So couple of things to sum up:

• The SpaceShip class is the class that we want to build.
• The Builder interface - so the contract - that the SpaceShipBuilder class has to implement.
• An important method to keep in mind is the buid() method, that is the method that actually builds the SpaceShip object, basically what happens is that every time you set something, then the reference of the attribute of the class is updated and after all the sets, when you are done, you can call the build() method that will return the SpaceShip object with all the attributes setted.
• So if you are wondering how the builder remember everything...then the answer is that all the attributes are stored in-memory in the SpaceShipBuilder class.

A quick example of how to use the Builder Pattern:

public static void main(String[] args) {
  SpaceShip spaceShip = new SpaceShipBuilder()
        .setName("SpaceX")
        .setModel("Falcon 9")
        .setCrew(4)
        .setMaxSpeed(1000)
        .setFuel("Kerosene")
        .setHealth(100)
        .build();
}

In conclusion the Builder Pattern is very useful to decouple (and abstract) the client from the object creation process, and most imporant to separate logic for certain objects that requires a lot of steps to be created.

[!TIP] The Buidler Pattern is very used in Frameworks and Libraries, that most of the times abstract as much as possible for the developer to use the library.

Prototype

The Prototype Pattern is a Creational Design Pattern that is used when you have to create a new object by copying an existing object without making your code dependent on their classes.

This pattern is per se very easy to understand and to apply, and it's also very handy for some scenarios in which you have to duplicate an object. When performing some business logic, the duplication of an objects is usually very common and so the Prototype Pattern solves the biolerplate code that you have to write to duplicate an object like new and the fact that you have to pass all the attributes of the object to the new object.

So let's say that you have a SpaceShip object and you want to duplicate it, you can use the Prototype Pattern to do that.

class SpaceShip {
  private String name;
  private String model;
  private int crew;
  private int maxSpeed;
  private String fuel;
  private int health;

  public SpaceShip(String name, String model, int crew, int maxSpeed, String fuel, int health) {
    this.name = name;
    this.model = model;
    this.crew = crew;
    this.maxSpeed = maxSpeed;
    this.fuel = fuel;
    this.health = health;
  }

  public SpaceShip clone() {
    return new SpaceShip(this);
  }
}

This will also work for the class that inherits from the SpaceShip class.

class WeakSpaceShip extends SpaceShip {
  public WeakSpaceShip(String name, String model, int crew, int maxSpeed, String fuel, int health) {
    super(name, model, crew, maxSpeed, fuel, health);
  }

  public WeakSpaceShip(WeakSpaceShip weakSpaceShip) {
    super(weakSpaceShip);
  }

  @override
  public SpaceShip clone() {
    return new WeakSpaceShip(this);
  }
}

So double ++ for that :D.

To conclude the Prototype Pattern do not need any kind of interface or abstract class, but it's just a method that you can add to your class to duplicate the object.

Eventualy you can also create an Clonable or Prototype interface that has the clone() method and then you can implement that interface in the class that you want to duplicate, but it's not that big of a deal!

Singleton

The Singleton Pattern is one of the most abused pattern in the world of programming, and it's also one of the most famous.

It's very useful when you have to create an object that has to be unique across all the life-cycle of the application, so you have to create only one instance of that object.

Its implementation is very straightforward and make the job done without too much effort.

class Singleton {
  private static Singleton instance;

  private Singleton() {}

  public static Singleton getInstance() {
    if (instance == null) {
      instance = new Singleton();
    }

    return instance;
  }
}

The Singleton Pattern is also very useful when you have to create a shared resource across the application, like a Logger or a Database Connection.

I don't think I need to make some sort of exmaple related to our SpaceShip Game because it's pretty clear how the music goes.

Structural Design Patterns

The Structural Design Patterns are used to create a structure of objects in a way that they can work together in a more efficient way.

Adapter

The Adapter Pattern is a Structural Design Pattern that allows objects with incompatible interfaces to work together.

Basically when you want to provide some sort of communication bwtween two objects that have different interfaces you can use the Adapter Pattern.

For example

• if you have an API that communicates via XML but you application communicates via JSON you can use the Adapter Pattern to make the two objects communicate.
• or if you have some legacy code in your application that you want to use but it's not compatible with the new code you can use the Adapter Pattern to make the two objects communicate.

These are just a couple of examples of how the Adapter Pattern can be used.

Sticking with the SpaceShip Game example, let's pretend that we have a SpaceShip class that has a health and a damage property, but we want to use the SpaceShip class in a game that has a lifePoints and a criticalDamage property.

In that case we can use the Adapter Pattern to make the two objects communicate.

class SpaceShip {
  private int health;
  private int damage;

  public SpaceShip(int health, int damage) {
    this.health = health;
    this.damage = damage;
  }

  public fire() {
    System.out.println("Firing with " + damage + " damage");
  }
}

class Alien {
  private int lifePoints;
  private int criticalDamage;

  public Alien(int lifePoints, int criticalDamage) {
    this.lifePoints = lifePoints;
    this.criticalDamage = criticalDamage;
  }
}

class AlienAdapter extends SpaceShip {
  private Alien alien;

  public AlienAdapter(Alien alien) {
    super(alien.getLifePoints(), alien.getCriticalDamage());
    this.alien = alien;
  }
}

In this example the AlienAdapter class is the Adapter that allows the SpaceShip and the Alien class to communicate.

A quick example of how to use the Adapter Pattern:

public static void main(String[] args) {
  Alien alien = new Alien(100, 10);
  AlienAdapter alienAdapter = new AlienAdapter(alien);
  // we can use the AlienAdapter as a SpaceShip
  alienAdapter.fire();
}

[!NOTE] The Adapter Pattern doesn't need any kind of interface or abstract class since it's itself a child of a parent class, so it basically a smart way to use polymorphism and inheritance.

Bridge

The Bridge Pattern is more an abstract concept than a real implementation. It's used when you have to decouple an abstraction from its implementation so that the two can vary independently.

For example when you have a monolith application and you want to split it into microservices, you can use the Bridge Pattern to decouple the abstraction from the implementation. By doing that if you have a problem, or you have to make an improvement to the AuthService you can do that without affecting the other services.

Or another more practical example is a Cross Platform framework that can compile on several platforms, in that case the Framework serves as an abstraction layer that avoids the developer to repeat the same functionality for each platform.

Say that, explaining what actually is a Bridge can be a bit tricky, but the concept is very simple.

To make it even more clear I would like to make a distinction between the Bridge Pattern and the Adapter Pattern.

The Adapter Pattern that we saw earlier is commonly used with an existing app or system in order to make some otherwise-incompatible classes work together, on the other hand the Bridge Pattern is used up front in the design of a system to let the developers works indipendently havving a bridge between the two.

Composite

The Composite Pattern is a Structural Design Pattern that allows you to compose objects into tree structures to represent part-whole hierarchies.

So automatically this pattern is very used when in your application there's a well structured hierarchy of objects that you want to represent.

At first sight you may do not think about any real example of this pattern, it was the same for me before reading this example.

In some UI Framwork the UI components are rapresented in a tree-structure. Usually in these structure only the leaf nodes of the tree are responsible to the actually "paint on the canvas" (yes some UI Framworks actually paints pixels on a blank canvas, like Flutter for mobile development). In those scenarios as u might imagine the structure is something like this:

├── CustomButton
│   ├── Button
│       ├── Container
│           ├── Widget
│               ├── Element
│                   ├── RenderObject
│                       ├── RenderBox

This is just a made up example but the concept seems clear, the CustomButton is the root of the hierarchy and is the one that the user has defined on top of the Framework one ("Button"), and the Button is the one that the Framework has defined on top of the Container, and so on.

The RenderBox is the leaf node of the tree and is the one that actually paints on the canvas (or more professional way -> it render the object).

The point here is the fact that in a class POV the CustomButton, Container, Widget and so on don't have any render() or paint() method, but they have a child property that is the reference to the next object in the hierarchy.

Of course a node can also have more than one child, but the point here is that only the leaf are the concrete painters of the thing in the UI.

The same concept you can apply to the Dot concept. A Dot can be a Line that can be a Square and so on.

Decorator

The Decorator Pattern is a Structural Design Pattern that allows you to add new functionality to an existing object without altering its structure.

So you can consider it as a wrapper around an object that doesn't currently do what you need to do, so you use a Decorator, to decorate the object and make it do what you need to do.

Usually when you need to extend the functionality of an object in the OO world you would use inheritance, it works great, but it has its caveats.

Sometimes happen that you have class A that is being extended in class B since you need more funcionality. The first limitation here is that class A doesn't do what class B does, so if you ever needs a class that does what class A and B does then you CAN'T create a class C that extends both A and B, that's the limitation of the inheritance (technically in Python you can do that, but it has it's own caveats too).

So we understood that inheritance doesn't solves all our problems, sometime you need to use composition.

The Decorator Pattern is a way to use composition to extend the functionality of an object.

Let's see an example with the SpaceShip game, let's imagine that in our game we have different space ships that can have different weapons, and we want to add a weapon to a space ship.

Normally you would do something like this:

class SpaceShip {
  private Weapon weapon;

  public SpaceShip(Weapon weapon) {
    this.weapon = weapon;
  }

  public void fire() {
    weapon.fire();
  }
}

abstract class Weapon {
  public abstract void fire() {}
}

class LaserWeapon extends Weapon {
  @override
  public void fire() {
    System.out.println("Firing with laser");
  }
}

class RocketWeapon extends Weapon {
  @override
  public void fire() {
    System.out.println("Firing with rocket");
  }
}

class PlasmaWeapon extends Weapon {
  @override
  public void fire() {
    System.out.println("Firing with plasma");
  }
}

So far so good, if we want to add a special weapon to a space ship we can do it like that:

public static void main(String[] args) {
  SpaceShip spaceShip = new SpaceShip(new LaserWeapon());
  spaceShip.fire();
}

But what if we want to add more than one weapon to a space ship? We can't do that with the current implementation.

So we can use the Decorator Pattern to solve this problem.

class SpaceShip {
  private Weapon weapon;

  public SpaceShip(Weapon weapon) {
    this.weapon = weapon;
  }

  public void fire() {
    weapon.fire();
  }

  public void setWeapon(Weapon weapon) {
    this.weapon = weapon;
  }
}

// the rest of the weapons classes...

abstract class SpaceShipDecorator extends SpaceShip {
  protected SpaceShip wrappedSpaceShip;

  public SpaceShipDecorator(SpaceShip wrappedSpaceShip, Weapon weapon) {
    this.wrappedSpaceShip = wrappedSpaceShip;
    this.wrappedSpaceShip.setWeapon(weapon);
  }

  public void fire() {
    wrappedSpaceShip.fire();
  }
}

Okay but, how can we actually use it?

public static void main(String[] args) {
  SpaceShip spaceShip = new SpaceShip(new LaserWeapon());
  // will fire laser
  spaceShip.fire();

  SpaceShip spaceShipWithRocket = new RocketWeaponDecorator(spaceShip, new RocketWeapon());
  // will fire rocket
  spaceShipWithRocket.fire();

  SpaceShip spaceShipWithPlasma = new PlasmaWeaponDecorator(spaceShipWithRocket, new PlasmaWeapon());
  // will fire plasma
  spaceShipWithPlasma.fire();
}

And that's it, very handy, very easy.

Facade

The Facade Pattern is a pattern that handle the complex logic behind the scenes and provide a simple interface to the client.

Those complex logic ofter comes from a libarary or a framework, and the Facade provides a simple and intuitive interface to handle it.

Let's say that in our game we have someway to start the engine of the StarShip and we have to do several things to start the engine, like check the fuel, check the battery, check the oxygen, etc...

In that case we can use the Facade Pattern to provide a simple interface to start the engine.

class SpaceShip {
  private Engine engine;

  public SpaceShip(Engine engine) {
    this.engine = engine;
  }
}

class Engine {
  public void checkFuel() {
    System.out.println("Checking fuel");
  }

  public void checkBattery() {
    System.out.println("Checking battery");
  }

  public void checkOxygen() {
    System.out.println("Checking oxygen");
  }

  public void start() {
    System.out.println("Starting engine");
  }
}

class EngineStarter {
  private Engine engine;

  public EngineStarter(Engine engine) {
    this.engine = engine;
  }

  public void startEngine() {
    engine.checkFuel();
    engine.checkBattery();
    engine.checkOxygen();
    engine.start();
  }
}

Okay let's pretend for a minute that the engine is a bit more complex than this...But the point here is that the EngineStarter so our Facade is providing good API to start the engine.

Let's see it in action:

public static void main(String[] args) {
  SpaceShip spaceShip = new SpaceShip(new Engine());
  EngineStarter engineStarter = new EngineStarter(spaceShip.engine);
  engineStarter.startEngine();
}

Flyweight

The Flyweight Pattern is a Structural Design Pattern that allows you to share objects to reduce memory usage.

It basically enable use to avoid specifing some attributes of an object in multiple objects, but to share them in a common place.

Let's say for the SpaceShip game we have thousands of bullets being fired. Each bullet has a position, direction, speed, and appearance. The appearance (texture, color, shape) can be shared among many bullets to save memory.

// Flyweight - shared bullet properties
class BulletType {
  private final String texture;
  private final String color;
  private final String shape;

  public BulletType(String texture, String color, String shape) {
    this.texture = texture;
    this.color = color;
    this.shape = shape;
  }
}

// Concrete bullet with unique state
class Bullet {
  private int x, y;  // position
  private int speed;
  private BulletType type; // shared flyweight

  public Bullet(int x, int y, int speed, BulletType type) {
    this.x = x;
    this.y = y;
    this.speed = speed;
    this.type = type;
  }
}

// Factory to manage shared BulletTypes
class BulletFactory {
  private Map<String, BulletType> bulletTypes = new HashMap<>();

  public BulletType getBulletType(String texture, String color, String shape) {
    String key = texture + color + shape;
    if (!bulletTypes.containsKey(key)) {
      bulletTypes.put(key, new BulletType(texture, color, shape));
    }
    return bulletTypes.get(key);
  }
}

The reason behind the Factory is that we want to avoid creating the same BulletType object multiple times, and the factory here comes in handy since we separate this logic from the client. If you are wondering why we are using a Map to store the BulletType objects, the answer is that we want to avoid creating the same BulletType object multiple times.

Usage example:

BulletFactory factory = new BulletFactory();
BulletType laserType = factory.getBulletType("laser", "red", "line");

// Create many bullets sharing the same BulletType
List<Bullet> bullets = new ArrayList<>();
for (int i = 0; i < 1000; i++) {
  bullets.add(new Bullet(i, i, 10, laserType));
}

Proxy

The Proxy Pattern enable to control the access to a specific object.

Okay but how? It provides a placeholder for this object that the developer want to protect, in order to delegat it to the proxy object.

The Proxy Pattern is used when you want to add some sort of logic before or after the access to an object.

For example you can use the Proxy Pattern to add some sort of logging before or after the access to an object.

Let's say that in our game we have a SpaceShip object that has a health and a damage property, and we want to log every time the fire() method is called.

In that case we can use the Proxy Pattern to log every time the fire() method is called.

abstract class SpaceShip {
  public abstract void fire();
}

// The concrete Space Ship that can actually fire something
class LaserSpaceShip implements SpaceShip {
  @override
  public void fire() {
    System.out.println("Firing");
  }
}

class SpaceShipProxy implements SpaceShip {
  private SpaceShip spaceShip;

  public SpaceShipProxy(SpaceShip spaceShip) {
    this.spaceShip = spaceShip;
  }

  @override
  public void fire() {
    System.out.println("Logging before firing");
    spaceShip.fire();
    System.out.println("Logging after firing");
  }
}

In this example the SpaceShipProxy class is the Proxy that logs every time the fire() method is called.

A quick example of how to use the Proxy Pattern:

public static void main(String[] args) {
  SpaceShip spaceShip = new LaserSpaceShip();
  SpaceShip spaceShipProxy = new SpaceShipProxy(spaceShip);
  spaceShipProxy.fire();
}

Behavioral Design Patterns

The Behavioral Design Patterns are used to manage algorithms, relationships, and responsibilities between objects.

In this category of patterns there are the following patterns:

• Chain of Responsibility
• Command
• Iterator
• Mediator
• Memento
• Observer
• State
• Strategy
• Template Method
• Visitor

Let's see them.

Chain of Responsibility

The Chain of Responsability is a Behavioral Design Pattern that allows you to pass a request along a chain of handlers.

What that means?

It means that you can have a chain of objects that can handle a request, and the request is passed along the chain until one of the objects in the chain handles the request.

With this pattern I take the permission to pick another example that is not related to the SpaceShip Game...I know, I know, forgive me.

The most intuitive way to represent Chain of Responsability for me is with the concept of middleware in a web server.

Usually a middleware, as the name suggest, is a middle layer between a request and a response in a web server, so it's a set of one or more actions that are performed before the request is handled and a response is fired.

In a web server you can have multiple middlewares that handle the request, and the request is passed along the chain until one of the middlewares pass the middlware to the concrete request handler.

Let's image that between our request and response, in order, we have to:

• Log the request
• Check if the user is authenticated
• Check if the user has the permission to access the resource
• Check if the user has the permission to perform the action

In that case we can use the Chain of Responsability Pattern to handle the request.

class Request {}

abstract class Middleware {
  private Middleware next;

  public Middleware use(Middleware next) {
    this.next = next;
    return next;
  }

  public abstract boolean check(Request request);
}

class LogMiddleware extends Middleware {
  @override
  public boolean check(Request request) {
    System.out.println("Logging request");
    return next.check(request);
  }
}

class AuthMiddleware extends Middleware {
  @override
  public boolean check(Request request) {
    System.out.println("Checking authentication");
    return next.check(request);
  }
}

class PermissionMiddleware extends Middleware {
  @override
  public boolean check(Request request) {
    System.out.println("Checking permission");
    return next.check(request);
  }
}

class RoleMiddleware extends Middleware {
  @override
  public boolean check(Request request) {
    System.out.println("Checking role");
    return next.check(request);
  }
}

In this example the LogMiddleware, AuthMiddleware, PermissionMiddleware, and RoleMiddleware classes are the handlers that handle the request.

An example of how to use the Chain of Responsability Pattern:

public static void main(String[] args) {
  Request request = new Request();
  Middleware middleware = new LogMiddleware();
  middleware
    .use(new AuthMiddleware())
    .use(new PermissionMiddleware())
    .use(new RoleMiddleware());

  middleware.check(request);
}

In this example the LogMiddleware class logs the request, the AuthMiddleware class checks if the user is authenticated, the PermissionMiddleware class checks if the user has the permission to access the resource, and the RoleMiddleware class checks if the user has the permission to perform the action.

So as you can see the "CoR" respects the Single Responsibility Principle, since each middleware has a single responsibility, and you can clearly define the order of execution of the middlewares, plus you can easily add or remove a middleware from the chain.

Command

The Command Pattern is a Behavioral Design Pattern that allows you to encapsulate a request as an object, thereby allowing you to parameterize clients with queues, delayes, and various operations.

The Command itself is usally just an interface with a single method:

interface Command {
  void run();
}

Then we can define concrete implementation of that interface for various kind of actions that we need to perform. In the case of the SpaceShip example let's says that we have some sort of cool interface to create a SpaceShip, so user can add various pieces to the SpaceShip like the kind of metal which the shape is built, the kind of weapon or the kind of driver.

class SpaceShip {
  private String metal;
  private String weapon;
  private String driver;

  public SpaceShip(String metal, String weapon, String driver) {
    this.metal = metal;
    this.weapon = weapon;
    this.driver = driver;
  }

  public void launch() {
    System.out.println("Launching SpaceShip with " + metal + " metal, " + weapon + " weapon and " + driver + " driver");
  }
}
```

For each of these actions we can create a concrete command:

```java
class SetMetalCommand implements Command {
  private SpaceShip spaceShip;
  private String metal;
  public SetMetalCommand(SpaceShip spaceShip, String metal) {
    this.spaceShip = spaceShip;
    this.metal = metal;
  }

  @override
  public void run() {
    spaceShip.setMetal(metal);
  }
}

class SetWeaponCommand implements Command {
  private SpaceShip spaceShip;
  private String weapon;
  public SetWeaponCommand(SpaceShip spaceShip, String weapon) {
    this.spaceShip = spaceShip;
    this.weapon = weapon;
  }

  @override
  public void run() {
    spaceShip.setWeapon(weapon);
  }
}

class SetDriverCommand implements Command {
  private SpaceShip spaceShip;
  private String driver;
  public SetDriverCommand(SpaceShip spaceShip, String driver) {
    this.spaceShip = spaceShip;
    this.driver = driver;
  }

  @override
  public void run() {
    spaceShip.setDriver(driver);
  }
}

[!NOTE] As you can see in this example is not the Command that do the logic of setting the metal, weapon or driver, but it's the SpaceShip class that has to do that, the Command just encapsulate the request to do that.

Then we can create an Invoker class that will be responsible to execute the commands:

class Invoker {
  private Command command;
  public void setCommand(Command command) {
    this.command = command;
  }

  public void executeCommand() {
    command.run();
  }
}

An example of how to use the Command Pattern:

public static void main(String[] args) {
  SpaceShip spaceShip = new SpaceShip();
  Invoker invoker = new Invoker();

  invoker.setCommand(new SetMetalCommand(spaceShip, "Titanium"));
  invoker.executeCommand();

  invoker.setCommand(new SetWeaponCommand(spaceShip, "Laser"));
  invoker.executeCommand();

  invoker.setCommand(new SetDriverCommand(spaceShip, "John Doe"));
  invoker.executeCommand();
}

[!NOTE] In this example the "Client" of our application is the main method itself.

With this Invoker we can also create a queue of commands to be executed later, or we can create a history of commands to be undone.

class Invoker {
  private List<Command> commandHistory = new ArrayList<>();
  public void setCommand(Command command) {
    this.commandHistory.add(command);
  }

  public void executeCommands() {
    for (Command command : commandHistory) {
      command.run();
    }
    commandHistory.clear();
  }

  public void undoLastCommand() {
    if (!commandHistory.isEmpty()) {
      commandHistory.remove(commandHistory.size() - 1);
    }
  }
}

This pattern is very useful when you want to decouple the object that invokes the operation from the one that knows how to perform it.

This will open up a world of endless possibility, like implementing a queue of commands, a history of commands to be undone, or even a remote control system.

So to be clear the process of applying the Command Pattern is:

1. Define the Command interface with a single method.
2. Create concrete Command classes that implement the Command interface.
3. Identify (or create) classes that will act as senders of the commands.
4. Change the senders so they use Command objects instead of calling methods directly.

[!NOTE] The Command Pattern is very useful in scenarios where you need to decouple the sender of a request from the receiver, or when you need to implement features like undo/redo, logging, or queuing of operations. But in our example we overcomplicated a simple scenario (creating a SpaceShip) just to show how the pattern works.

Iterator

The Iterator Pattern is a Behavioral Design Pattern that allows you to traverse a collection of objects without exposing the underlying representation of the collection (list, stack, tree, etc..).

As hard as it might seem, the Iterator Pattern is very easy to understand and to implement. The key part is the "Collection" part, it's important to focus on that because the Iterator Pattern applies to collections of objects.

Collections are in each programming leanguage, and they are used to store multiple objects in a single object, such as an array, a list, a set, a map, a tree, etc...

The main problem with collections is that they have different ways to traverse (explore) the objects inside them.

The Iterataor Pattern in that case comes in handy since it provides a common Interface Iteartor that hase two simple methods that can be used to traverse the collection:

interface Iterator<T> {
  boolean hasNext();
  T next();
}

The hasNext() method returns true if there are more elements in the collection, and the next() method returns the next element in the collection.

So now we can create a concrete implementation of the Iterator interface for our collection, let's say that in our application we are storing all the SpaceShips in the game, so the Fleet as a tree, since a fleet can have multiple fleets inside it.

class SpaceShip {
  private String name;
  private String model;
  private int crew;
  private int maxSpeed;
  private String fuel;
  private int health;

  // constructor, getters and setters...
}

Now the Fleet class that will store all the SpaceShips in a tree structure MUST implements the IterableCollection interface that has the createIterator() method that returns an Iterator object.:

interface IterableCollection<T> {
  Iterator<T> createIterator();
}

Now let's define the Fleet class:

class Fleet implements IterableCollection<SpaceShip> {
  private List<SpaceShip> spaceShips = new ArrayList<>();
  private List<Fleet> fleets = new ArrayList<>();

  public void addSpaceShip(SpaceShip spaceShip) {
    spaceShips.add(spaceShip);
  }

  public void addFleet(Fleet fleet) {
    fleets.add(fleet);
  }

  @override
  public Iterator<SpaceShip> createIterator() {
    return new DepthFirstIterator(this);
  }

  public List<SpaceShip> getSpaceShips() {
    return spaceShips;
  }

  public List<Fleet> getFleets() {
    return fleets;
  }
}

Now based on our needs we can create as many as we want concrete implementation of the Iterator interface, for example we can create a DepthFirstIterator and a BreadthFirstIterator to traverse the tree in different ways.

class DepthFirstIterator implements Iterator<SpaceShip> {
  private Stack<Object> stack = new Stack<>();
  private SpaceShip current;

  public DepthFirstIterator(Fleet fleet) {
    stack.push(fleet);
  }

  @Override
  public boolean hasNext() {
    while (!stack.isEmpty()) {
      Object top = stack.pop();
      if (top instanceof SpaceShip) {
        current = (SpaceShip) top;
        return true;
      } else if (top instanceof Fleet) {
        Fleet fleet = (Fleet) top;
        for (SpaceShip spaceShip : fleet.getSpaceShips()) {
          stack.push(spaceShip);
        }
        for (Fleet subFleet : fleet.getFleets()) {
          stack.push(subFleet);
        }
      }
    }
    return false;
  }

  @Override
  public SpaceShip next() {
    return current;
  }
}

class BreadthFirstIterator implements Iterator<SpaceShip> {
  private Queue<Object> queue = new LinkedList<>();
  private SpaceShip current;

  public BreadthFirstIterator(Fleet fleet) {
    queue.add(fleet);
  }

  @Override
  public boolean hasNext() {
    while (!queue.isEmpty()) {
      Object front = queue.poll();
      if (front instanceof SpaceShip) {
        current = (SpaceShip) front;
        return true;
      } else if (front instanceof Fleet) {
        Fleet fleet = (Fleet) front;
        for (SpaceShip spaceShip : fleet.getSpaceShips()) {
          queue.add(spaceShip);
        }
        for (Fleet subFleet : fleet.getFleets()) {
          queue.add(subFleet);
        }
      }
    }
    return false;
  }

  @Override
  public SpaceShip next() {
    return current;
  }
}

Now we can use both the DepthFirstIterator and the BreadthFirstIterator to traverse the Fleet in different ways.

public static void main(String[] args) {
  Fleet fleet = new Fleet();
  fleet.addSpaceShip(new SpaceShip("Enterprise", "NCC-1701", 430, 9500, "Dilithium", 100));
  fleet.addSpaceShip(new SpaceShip("Defiant", "NX-74205", 50, 9000, "Antimatter", 100));

  Fleet subFleet = new Fleet();
  subFleet.addSpaceShip(new SpaceShip("Voyager", "NCC-74656", 150, 9000, "Dilithium", 100));
  fleet.addFleet(subFleet);

  System.out.println("Depth First Traversal:");
  Iterator<SpaceShip> depthFirstIterator = fleet.createIterator();
  while (depthFirstIterator.hasNext()) {
    SpaceShip ship = depthFirstIterator.next();
    System.out.println(" - " + ship.getName());
  }

  System.out.println("\nBreadth First Traversal:");
  Iterator<SpaceShip> breadthFirstIterator = new BreadthFirstIterator(fleet);
  while (breadthFirstIterator.hasNext()) {
    SpaceShip ship = breadthFirstIterator.next();
    System.out.println(" - " + ship.getName());
  }
}

Mediator

Mediator is a behavioral design pattern that allows you to reduce the chaotic dependencies between objects. The pattern restricts direct communications between the objects and forces them to collaborate only via a mediator object.

The Mediator Pattern try to solves this issue by introducing a new Mediator Object that will handle the communication and the interactions between the objects.

The Mediator object is a simple interface that most of the times has only one method, that is the notify() method.

interface Mediator {
  void notify(Object sender, Object event);
}

Then we can create as many concrete implementation of the Mediator interface as we want, based on our needs.

The concrete implementation of the Mediator are a bit more complex and they depends on the use case. Usually a concrete mediator class has all the dependencies of the objects that it has to mediate.

The objects that needs to mediate needs to have a reference of the Mediator interface (not the concrete mediator), this reference is usually passed in the constructor of the object and it will be used to notify the mediator when something happens.

Let's see an example with the SpaceShip game, let's say that we have a SpaceShip class that has a fire() method and a takeDamage() method, and we want to notify the Fleet when a SpaceShip fires or takes damage.

class SpaceShip {
  private String name;
  private Mediator mediator;

  public SpaceShip(String name, Mediator mediator) {
    this.name = name;
    this.mediator = mediator;
  }

  public void fire() {
    System.out.println(name + " is firing");
    mediator.notify(this, "fire");
  }

  public void takeDamage(int damage) {
    System.out.println(name + " is taking " + damage + " damage");
    mediator.notify(this, "takeDamage");
  }
}

class FleetMediator implements Mediator {
  private List<SpaceShip> spaceShips;

  public FleetMediator(List<SpaceShip> spaceShips) {
    this.spaceShips = spaceShips;
  }

  @override
  public void notify(Object sender, Object event) {
    if (event.equals("fire")) {
      System.out.println("FleetMediator: " + ((SpaceShip) sender).getName() + " has fired");
    } else if (event.equals("takeDamage")) {
      System.out.println("FleetMediator: " + ((SpaceShip) sender).getName() + " has taken damage");
    }
  }
}

An example of how to use the Mediator Pattern:

public static void main(String[] args) {
  List<SpaceShip> fleet = new ArrayList<>();
  FleetMediator fleetMediator = new FleetMediator(fleet);

  SpaceShip enterprise = new SpaceShip("Enterprise", fleetMediator);
  SpaceShip defiant = new SpaceShip("Defiant", fleetMediator);
  fleet.add(enterprise);
  fleet.add(defiant);

  enterprise.fire();
  defiant.takeDamage(50);
}

This is a very basic example, leet's see a more complex one. Let's pretend we have to handle a chat room where multiple users can send messages to each other.

class User {
  private String name;
  private Mediator mediator;

  public User(String name, Mediator mediator) {
    this.name = name;
    this.mediator = mediator;
  }

  public String getName() {
    return name;
  }

  public void sendMessage(String message) {
    System.out.println(name + " is sending message: " + message);
    mediator.notify(this, message);
  }
}

class ChatRoom implements Mediator {
  private List<User> users;

  public ChatRoom() {
    this.users = new ArrayList<>();
  }

  public void addUser(User user) {
    users.add(user);
  }

  @override
  public void notify(Object sender, Object event) {
    for (User user : users) {
      if (user != sender) {
        System.out.println(user.getName() + " received message: " + event);
      }
    }
  }
}

An example of how to use the Mediator Pattern in a chat room:

public static void main(String[] args) {
  ChatRoom chatRoom = new ChatRoom(); // the mediator

  User alice = new User("Alice", chatRoom);
  User bob = new User("Bob", chatRoom);
  chatRoom.addUser(alice);
  chatRoom.addUser(bob);

  alice.sendMessage("Hello Bob!"); // The user do the concrete action, but the mediator handle the communication
  bob.sendMessage("Hi Alice!");
}

Memento

Memento is a behavioral design pattern that allows you to capture and externalize an object's internal state so that the object can be restored to this state later, without violating encapsulation.

So basically the Memento Pattern is used to implement the undo/redo functionality in an application.

We have three main components in the Memento Pattern:

1. The Originator: the object whose state we want to save and restore, and is also the one who generates the state.
2. The Memento: the object that stores the internal past snapshots of state of the Originator, without exposing its implementation details, so that the Originator can restore its state from the Memento.
3. The Caretaker: the object that is responsible for storing and restoring the Mementos, often is used with the Command Pattern and the Command object is the Caretaker, its purpose is to create backups of the state, and undo/redo functionality.

Let's see an example with the SpaceShip game, let's say that we have a SpaceShip class that has a health property, and we want to save the state of the SpaceShip before taking damage, so that we can restore it later.

// In this case SpaceShip is the Originator, the one who holds the state that is the health in our case
class SpaceShip {
    private int health;

    public SpaceShip(int health) {
        this.health = health;
    }

    public void setHealth(int health) {
        this.health = health;
    }

    public int getHealth() {
        return health;
    }

    public void restore(SpaceShipMemento memento) {
        this.health = memento.getHealth();
    }

    // Creates a memento with current state
    public SpaceShipMemento save() {
        return new SpaceShipMemento(health);
    }

    // Inner Memento class that stores the past state of the SpaceShip
    // This is used so the caregiver doesnt have access to the internal state of the SpaceShip
    public class SpaceShipMemento {
        private final int health;

        public SpaceShipMemento(int health) {
            this.health = health;
        }

        public int getHealth() {
            return health;
        }
    }
}


// Store previous mementos state and eventually restore them
class Caretaker {
    private Stack<SpaceShip.SpaceShipMemento> history = new Stack<>();

    public void save(SpaceShip spaceShip) {
        history.push(spaceShip.save());
    }

    public void undo(SpaceShip spaceShip) {
        if (!history.isEmpty()) {
            SpaceShip.SpaceShipMemento memento = history.pop();
            spaceShip.restore(memento);
        }
    }
}

Observer

Observer is a behavioral design pattern that lets you define a subscription mechanism to notify multiple objects about any events that happen to the object they’re observing.

The Observer Pattern is used when you have a one-to-many relationship between objects, so when one object changes state, all its dependents are notified and updated automatically. This is a very common scenario so let's see how can we integrate it in the SpaceShip game.

Let's say that we have a Fleet class that has multiple SpaceShip objects, and we want to notify all the SpaceShip objects when the Fleet changes state, for example when a new SpaceShip is added to the Fleet.

interface Observer {
  void update(String message);
}

// Handy interface for the Subject, the one that notify all the observers
interface Subject {
  void attach(Observer observer); // attach a new observer (subscriber) to the subject
  void detach(Observer observer); // detach an observer (subscriber) from the subject
  void notifyObservers(String message); // notify all the observers (subscribers) about an event
}

// In this case the Fleet is the Publisher (or Subject) that notify all the SpaceShip (Observers) when something happens
class Fleet implements Subject {
  private List<Observer> observers = new ArrayList<>();
  private List<SpaceShip> spaceShips = new ArrayList<>(); // The main state of the Fleet

  public void addSpaceShip(SpaceShip spaceShip) {
    spaceShips.add(spaceShip);
    // Notify all observers about the new SpaceShip
    notifyObservers("New SpaceShip added: " + spaceShip.getName());
  }

  public void importantFleetEvent(String event) {
    // Notify all observers about the important event
    notifyObservers("Important Fleet Event: " + event);
  }

  public void attach(Observer observer) {
    observers.add(observer);
  }

  public void detach(Observer observer) {
    observers.remove(observer);
  }

  public void notifyObservers(String message) {
    for (Observer observer : observers) {
      observer.update(message);
    }
  }
}

// Its the concrete Subscriber (Observer) that wants to be notified when something happens in the Publisher (Subject)
class SpaceShip implements Observer {
  private String name;

  public SpaceShip(String name) {
    this.name = name;
  }

  public void update(String message) {
    // can perform something when receiving the notification from the publisher (Fleet)
    System.out.println(name + " received message: " + message);
  }
}

An example of how to use the Observer Pattern:

public static void main(String[] args) {
  Fleet fleet = new Fleet();
  SpaceShip ship1 = new SpaceShip("Ship 1");
  SpaceShip ship2 = new SpaceShip("Ship 2");

  fleet.attach(ship1);
  fleet.attach(ship2);

  fleet.addSpaceShip(new SpaceShip("Ship 3"));
  fleet.importantFleetEvent("Enemy fleet detected!");
}

Ofc also other entites can be attached to the Fleet and be notified when something happens, for example a FleetCommander class that wants to be notified when a new SpaceShip is added to the Fleet.

class FleetCommander implements Observer {
  private String name;

  public FleetCommander(String name) {
    this.name = name;
  }

  public void update(String message) {
    // can perform something when receiving the notification from the publisher (Fleet)
    System.out.println(name + " received message: " + message);
  }
}

An example of how to use the Observer Pattern with the FleetCommander:

public static void main(String[] args) {
  Fleet fleet = new Fleet();
  SpaceShip ship1 = new SpaceShip("Ship 1");
  FleetCommander commander = new FleetCommander("Commander");

  fleet.attach(ship1);
  fleet.attach(commander);

  fleet.addSpaceShip(new SpaceShip("Ship 2"));
  fleet.importantFleetEvent("Enemy fleet detected!");
}

State

State is a behavioral design pattern that allows an object to alter its behavior when its internal state changes. The object will appear to change its class.

Usually programs can be in different states, and based on the state the program can behave differently. Instead of handling the state with a lot of if or switch statements, we can use the State Pattern to handle the state in a more elegant way and scalable way.

We can define a State interface that has a method for each action that can be performed in the different states.

interface State {
  void handle();
}

For example in our SpaceShip game we can have a SpaceShip class that can be in different states, such as Idle, Flying, Attacking, and Damaged.

class SpaceShip {
  private State state;

  public SpaceShip() {
    this.state = new IdleState(this); // initial state
  }

  // logic to change the state
  public void setState(State state) {
    this.state = state;
  }

  // method to handle the state based on the current one
  // in our eample this will print something
  // but in a real game this will perform some concrete action
  public void handle() {
    state.handle();
  }
}

Then we can create concrete implementation of the State interface for each state.

class IdleState implements State {
  private SpaceShip spaceShip;

  public IdleState(SpaceShip spaceShip) {
    this.spaceShip = spaceShip;
  }

  public void handle() {
    System.out.println("SpaceShip is idle.");
  }
}

class FlyingState implements State {
  private SpaceShip spaceShip;

  public FlyingState(SpaceShip spaceShip) {
    this.spaceShip = spaceShip;
  }

  public void handle() {
    System.out.println("SpaceShip is flying.");
  }
}

class AttackingState implements State {
  private SpaceShip spaceShip;

  public AttackingState(SpaceShip spaceShip) {
    this.spaceShip = spaceShip;
  }

  public void handle() {
    System.out.println("SpaceShip is attacking.");
  }
}

class DamagedState implements State {
  private SpaceShip spaceShip;

  public DamagedState(SpaceShip spaceShip) {
    this.spaceShip = spaceShip;
  }

  public void handle() {
    System.out.println("SpaceShip is damaged.");
  }
}

A more complex example would be to have the state directly tells if a SpaceShip can perform a specific action or not, for example if the SpaceShip is in the DamagedState it cannot fly() or attack(), but it can only repair().

interface State {
  void fly();
  void attack();
  void repair();
}

Now let's define the SpaceShip class:

class SpaceShip {
  private State state;

  public SpaceShip() {
    this.state = new IdleState(this); // initial state
  }

  // logic to change the state
  public void setState(State state) {
    this.state = state;
  }

 // It's not the spaceship that handles the logic of the action, but it's the current state that handles it
 // so the system can behave differently based on the current state
  public void fly() {
    state.fly();
  }

  public void attack() {
    state.attack();
  }

  public void repair() {
    state.repair();
  }
}

Then we can create concrete implementation of the State interface for each state.

class IdleState implements State {
  private SpaceShip spaceShip;

  public IdleState(SpaceShip spaceShip) {
    this.spaceShip = spaceShip;
  }
  public void fly() {
    System.out.println("SpaceShip is flying.");
    spaceShip.setState(new FlyingState(spaceShip));
  }

  public void attack() {
    System.out.println("SpaceShip is attacking.");
    spaceShip.setState(new AttackingState(spaceShip));
  }

  public void repair() {
    System.out.println("SpaceShip is already in good condition.");
  }
}

// ... other states with different logic implementation

Strategy

The Strategy pattern defines a family of algorithms, encapsulates each one, and makes them interchangeable. This pattern lets the algorithm vary independently from clients that use it.

In our SpaceShip example, we could use the Strategy pattern to define different flying behaviors.

// Strategy contract
interface FlyStrategy {
  void fly();
}

// Concrete strategies implementing the FlyStrategy interface
class FlyWithWings implements FlyStrategy {
  public void fly() {
    System.out.println("Flying with wings!");
  }
}

class FlyWithFuel implements FlyStrategy {
  public void fly() {
    System.out.println("Flying with fuel!");
  }
}

// This calss is the context. Is the one that use the strategy
// and communicates with its object only via the strategy interface
class SpaceShip {
  private FlyStrategy flyStrategy;

  public SpaceShip(FlyStrategy flyStrategy) {
    this.flyStrategy = flyStrategy;
  }

  public void performFly() {
    flyStrategy.fly();
  }
}

And then we can use it like this:

// In this case is the client of the strategy pattern
public static void main(String[] args) {
  SpaceShip birdShip = new SpaceShip(new FlyWithWings());
  birdShip.performFly(); // Output: Flying with wings!

  SpaceShip rocketShip = new SpaceShip(new FlyWithFuel());
  rocketShip.performFly(); // Output: Flying with fuel!
}

Template Method

The teamplate method is a behavioral design pattern that defines the skeleton of an algorithm in the superclass but lets subclasses override specific steps of the algorithm without changing its structure.

This pattern is used when several classes uses the same algorithm, but with some variations in specific steps of the algorithm. So instead of duplicating the algorithm in each class, we can define the algorithm in a superclass and let the subclasses override the specific steps.

In our SpaceShip example, we could use the Template Method pattern to define a general algorithm for attacking, but let subclasses define specific attack strategies.

abstract class SpaceShip {
  // Template method defining the skeleton of the algorithm
  public final void attack() {
    prepareForAttack();
    executeAttack();
    retreat();
  }

  protected abstract void prepareForAttack(); // Step to be implemented by subclasses
  protected abstract void executeAttack(); // Step to be implemented by subclasses

  private void retreat() { // Common step for all subclasses
    System.out.println("Retreating to safe distance.");
  }
}

// The concrete classes implement the specific steps of the algorithm
// The benefit is that those SpaceShips doesn't have to implement the whole attack algorithm
// just the part that is different
public class LaserSpaceShip extends SpaceShip {
  @Override
  protected void prepareForAttack() {
    System.out.println("Charging laser weapons.");
  }

  @Override
  protected void executeAttack() {
    System.out.println("Firing laser beams!");
  }
}

public class PlasmaSpaceShip extends SpaceShip {
  @Override
  protected void prepareForAttack() {
    System.out.println("Preparing plasma weapons.");
  }

  @Override
  protected void executeAttack() {
    System.out.println("Firing plasma blasts!");
  }
}

Now let's see how to use the Template Method pattern:

public static void main(String[] args) {
  SpaceShip laserShip = new LaserSpaceShip();
  laserShip.attack();

  SpaceShip plasmaShip = new PlasmaSpaceShip();
  plasmaShip.attack();
}

Visitor

The Visitor pattern is a behavioral design pattern that lets you separate algorithms from the objects on which they operate. It allows you to add new operations to existing object structures without modifying the structures.

The Visitor pattern is used when you have a complex object structure, and you want to perform operations on the objects in the structure without changing their classes. Instead of adding methods to the classes, you create a visitor class that implements the operations.

interface Visitor {
  void visit(SpaceShip spaceShip);
  void visit(Fleet fleet);
}

interface Element {
  void accept(Visitor visitor);
}

class SpaceShip implements Element {
  private String name;

  public SpaceShip(String name) {
    this.name = name;
  }

  public String getName() {
    return name;
  }

  public void accept(Visitor visitor) {
    visitor.visit(this);
  }
}

class Fleet implements Element {
  private List<Element> elements = new ArrayList<>();

  public void addElement(Element element) {
    elements.add(element);
  }

  public List<Element> getElements() {
    return elements;
  }

  public void accept(Visitor visitor) {
    for (Element element : elements) {
      element.accept(visitor);
    }
    visitor.visit(this);
  }
}

class FleetStatusVisitor implements Visitor {
  public void visit(SpaceShip spaceShip) {
    System.out.println("Visiting SpaceShip: " + spaceShip.getName());
  }

  public void visit(Fleet fleet) {
    System.out.println("Visiting Fleet with " + fleet.getElements().size() + " elements.");
  }
}

class FleetRepairVisitor implements Visitor {
  public void visit(SpaceShip spaceShip) {
    System.out.println("Repairing SpaceShip: " + spaceShip.getName());
  }

  public void visit(Fleet fleet) {
    System.out.println("Repairing Fleet with " + fleet.getElements().size() + " elements.");
  }
}

public static void main(String[] args) {
  Fleet fleet = new Fleet();
  fleet.addElement(new SpaceShip("Enterprise"));
  fleet.addElement(new SpaceShip("Defiant"));

  Fleet subFleet = new Fleet();
  subFleet.addElement(new SpaceShip("Voyager"));
  fleet.addElement(subFleet);

  FleetStatusVisitor statusVisitor = new FleetStatusVisitor();
  fleet.accept(statusVisitor);

  FleetRepairVisitor repairVisitor = new FleetRepairVisitor();
  fleet.accept(repairVisitor);
}

::github{repo="fres-sudo/hono-auth"}

Introduction

In this article I'm will try my best to explain to you about the creation from the ground up of a complete authentication system for your next successful application.

I'm sorry for any grammatical errors, this is my first article and I'm not english mother tongue.

Functionalities

Here it is a quick break down of what functionalities your app will have at the end of the article:

• Email and password authentication
• JWT Access and Refresh Token System
• Email Verification
• Forgot password, OTP code verification, Reset password

Technologies

Those are the main technologies and libraries that you will need to spin up this simple application:

• Typescript, basically JS but a bit better,
• Hono, a ligthweigth Javascript framework to build fast web application,
• Drizzle ORM,
• Postgres SQL,
• Zod for DTOs,
• tsrynge an easy library for Dependence Injection in Typescript,

Notice that you can basically use what technologies you prefer, those are just based on my personal preference, you don't have to stick with them, but also notice that if you choose to go with something else you will have to make some changes at your code.

Architecture Overview

The architecture is heavy inspired by this awesome project, I'll just mention more or less what the creator said in his introduction.

There are a few popular architectures for structuring backends. Technical, Onion, DDD, VSA, and the list goes on.

Folder Structure

• controllers - Responsible for routing requests

• services - Responsible for handling business logic.

• repositories - Responsible for retrieving and storing data.

• infrastructure - Handles the implementation of external services or backend operations.

• middleware - Middlware our request router is responsible for handling.

• providers - Injectable services

• dtos - Data Transfer Objects (DTOs) are used to define the shape of data that is passed.

File Naming

Each file of the project is postfixed with its architectural type(e.g. iam.service.ts). This allows us to easily reorganize the folder structure to suite a different architecture pattern if the domain becomes more complex.

For example, if you want to group folders by domain(DDD), you simply drag and drop all related files to that folder.

└── events/
    ├── events.controller.ts
    ├── events.service.ts
    └── events.repository.ts

Why?

I am making this article to help people struggling with finding a resource that will help them to spin up a complete authentication system, often the guides and video tutorial online not includes all the functionalities that I will show you in this article.

The claim is to have a place to get a look when you feel lost while writing your authentication system.

This IS NOT the perfect authentication system, this is just mine authentication system.

Authentication is usually a non-trivial area, so use my implementation at your own risk.

Who?

This guide is for developers that already know the basics of Javascript or Typescript, you don't need to know any JS framework, if you already play with Express.js or something like that you will probably will understand more, but it is not required.

Of course basic understanding of how an HTTP server works and the interaction between client and server is mandatory, also what is a RESTful API and how it works.

In this article I will not go in the details of the architectural implementation of the system, or how to install the software, it will use bun as package manager, but you can use whatever you prefer, it will change quite nothing.

Also a basic understand of Docker is better to complete understand the course.

Where?

No worries, you will find all the code in this Github repository. If you will find this article useful I will highly appreciate a Github ⭐ I still highly suggest you to follow

Getting Started

To get started right we first need to create a new project.

bun create hono@latest

This command will guide you through a wizard for the creation of your bun application, the process for other packer manager is more or the less the same.

The first thing you will get asked is to choose a target directory, this means that if you are already in your project directory you just need to type ., otherwise just type the name of the folder of the project, I will use hono-auth, you can choose your own.

After that you will prompted to choose from a template, this is the most important part, for this guide I will choose bun, this will create a basic src/index.ts file, that is the entry point of our new application. It will also generate other files, such as the configuration of Typescript in tsconfig.json and the most important, the package.json, in here we can see that bun create a simple script for run our app.

  "scripts": {
    "dev": "bun run --hot src/index.ts"
  }

Notice that if you choose other template for other kind of project your output would be slightly different, choose what you need!

If he ask you to install the project dependencies just say yes, and for the package manger just choose what you prefer, as I said, I'll stick with bun.

So if we run our app with bun dev and we try to call the localhost:3000/ endpoint we should get some feedback.

I will use httppie that is just a CLI tool that can make you make request to endpoints, but you can use Postman or whatever you prefer.

so your output would be:

Hello Hono!

or something like that.

Dependencies

Before even touch any code, let's add some packages to our project so we don't have to do it later on the fly.

Just type in the terminal:

bun add tsyringe drizzle-kit drizzle-orm drizzle-zod zod reflect-metadata typescript arctic postgres nodemailer hono-rate-limiter @hono/zod-validator @paralleldrive/cuid2

Those are the main dependencies for this project, you just add those and you are ready to go.

Setup

Before starting there will be a quite long session of setup before starting. I'll break down the major steps for you, be sure to follows every single step to not get lost.

• Docker Setup
• Drizzle Setup
• Configuration Setup
• Dipendence Injection Setup

Let's get started.

Docker Setup

This step is not necessary but I personally highly reccomend to follow up and use docker, to avoid any problems related to your machine.

I will not explain the reason to choose docker, just do it, and you will not regret it! Aside from jokes, Docker will help us to ensure that we all got the same setup and you work on an isolated environment.

So first thing first you might need to install Docker (and Docker Compose) on you machine, you can find the installation here, if you are new to docker I will suggest you to download also the desktop version if is your first time with docker so you can visually see what is going on.

Dockerfile

So the first thing we need in our isolated environment is obviously our app and our dependencies, so we can create an entry point for docker to download it and serve to us.

This will be accomplished by creating a Dockerfile in our root directory, so in my case it will be hono-auth/Dockerfile:

FROM oven/bun:1.0.35

WORKDIR /home/bun/app

COPY ./package.json .

RUN bun install

COPY . .

CMD [ "bun", "run", "dev" ]

So basically here we are downloading bun, setting up out work directory, copying the package.json with all the necessary information and then install the dependencies in the environment, after that we're also telling docker that it has to execute bun run dev.

<a name="docker-compose"></a>

Docker Compose

Now that we have our entry- point, since we will have two different containers, running at the same time, we have to define a Docker Compose file, to handle the two container and the communication between the two.

For doing that we will need to create docker-compose.yaml file in out root directory.

services:
  app:
    container_name: hono-app
    build:
      dockerfile: Dockerfile
    depends_on:
      - postgres
    env_file:
      - .env
    ports:
      - 3000:3000
    restart: always
    networks:
      - app-network
  postgres:
    container_name: db
    image: postgres:latest
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: postgres
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - app-network

networks:
  app-network:
    driver: bridge

volumes:
  postgres_data:

So as you can see we are defining 2 differnet services:

• app : this will be the hono app, and it has a docker file, that is the file that we created earlier, it obviously depends on the db, since we need first the db to make the app starts, we define the .env file with all our secrets, the ports that we are using in the project and the port we want to expose on docker, and of course the network. The network is just a bridge that ensure the communication between 2 or more services (or containers).

• db : this is the postgres instance that we will use as databse in our app, the paramteres are quite the same and self explanatory.

Once we setup everything we can now define some scripts to effectively runs these 2 containers.

so in the package.josn we can define:

"scripts": {
    "dev": "bun run --hot src/index.ts",
    "docker:up": "docker-compose up -d",
    "docker:build": "docker-compose up -d --build",
  }

Drizzle Setup

Even if Drizzle is a fast ORM, it will require a small setup, nothing too crazy, don't worry. For more detailed introduction to setup Drizzle ORM I higly suggest you to check out their official documentation that is very great.

Setup Env variables

If you are using external database, like Neon, Supabase, ecc... Feel free to put your url as env variable.

To connect to the PostgreSQL database, you need to provide the database URL. The URL format is:

postgres://<user>:<password>@<host>:<port>/<database>

So create a .env file at root of the application and fill with the values you choose in the docker compose, in our case is:

DATABASE_URL=postgresql://postgres:postgres@postgres:5432/postgres

Configuration File

For the next setup we also need to define some structure of out environment variables, so we can do that as follows.

Since I'm using bun, the engine gives to me some useful API to retrive environment variables, without the need of external packages.

Please notice that if you are using other engine, we will need some adjustment and most likely also using a 3rd part package to interact with env variables.

In bun we can retrive an environment variable in some way, for personal preference I will use:

process.env.[ENV_VARIABLE_NAME]

For a better structured setup, create a config.type.ts under src/types/.

// src/types/config.type.ts

export const config: Config = {
 isProduction: process.env.NODE_ENV === "production",
 api: {
  origin: process.env.ORIGIN ?? "",
 },
 postgres: {
  url: process.env.DATABASE_URL ?? "",
 },
};

interface Config {
 isProduction: boolean;
 api: ApiConfig;
 postgres: PostgresConfig;
}

interface ApiConfig {
 origin: string;
}

interface PostgresConfig {
 url: string;
}

As you can see I also add a quite useful environment variable that is:

ORIGIN=http://localhost:3000 //3000 is the port we define in the docker-compose.yaml file

Since now the project is local, we just use localhost but when you will deploy it you will put here your correct url.

Drizzle Configuration

For correctly setup drizzle we need to define a configuration file, that will be placed in the root of our application, so in this case it will be hono-auth/drizzle.config.ts, this file will contains all the necessary information for drizzle to spin up.

// drizzle.config.ts
import type { Config } from "drizzle-kit";
import { config } from "./src/types/config.type";

export default {
 out: "./src/infrastructure/database/migrations",
 schema: "./src/infrastructure/database/tables/index.ts",
 breakpoints: false,
 strict: true,
 dialect: "postgresql",
 dbCredentials: {
  url: config.postgres.localUrl,
 },
 migrations: {
  table: "migrations",
  schema: "public",
 },
 verbose: true,
} satisfies Config;

As you can see a lot of stuff are going on here, but let's break down the important parts real quick.

• out is the output directory where the migrations will be localted, you can choose whatever you want;
• schema is the imporant file where drizzle will pull all the schemas of your database and will reflect your postgres instance accordingly

Drizzle Entry Point

The Drizzle entry point is basically where your app tells drizzle to connect with databse, in our case it will be located under.

In our case I prefer to locate it under src/infrastructure/database/index.ts, the file contente of index.ts will be:

// src/infrastructure/database/index.ts
import { drizzle } from "drizzle-orm/postgres-js";
import postgres from "postgres";
import * as schema from "./tables";
import { config } from "../../types/config.type";

export const client = postgres(config.postgres.url, { max: 10 });
export const db = drizzle(client, { schema });

So far our infrastructure structure looks like this:

└── infrastructure/
    └── database/
     ├── utils.ts
     ├── index.ts
     └── migrations/

As you can see there are also some files that we didn't meet so far. Let's break it down:

//src/infrastructure/database/utils.ts
import { HTTPException } from "hono/http-exception";

export const takeFirst = <T>(values: T[]): T | null => {
 if (values.length === 0) return null;
 return values[0]!;
};

export const takeFirstOrThrow = <T>(values: T[]): T => {
 if (values.length === 0)
  throw new HTTPException(404, {
   message: "Resource not found",
  });
 return values[0]!;
};

This file contains two crucial function that we will be using a lot in our queries.

The migration is the directory that we pointed in the index.ts file, and it will contains all our migration .sql file for out database.

Dependencies Injection Setup

As I said before for dependency injection, I'm going to use tsyringe but you can actually use whatever you want.

If you will use both bun and tsyringe you just need a small fix to make everything works, just follows these steps:

• Create reflect-metadata-import.ts under src/ folder,

  // src/reflect-metadata-import.ts
  
  import "reflect-metadata";
  

• Create bunfig.toml file under root folder

  // /bunfig.toml
  
  preload = ["./src/reflect-metadata-import.ts"]
  

<a name="email-and-password-authentication"></a>

Email and password authentication

Once you are done with the initial setup, we can now pass to implements the first step, that will be the creation of a basic email and password authentication.

Let's start by creating the controller, as I said in the Architecture Overview the controllers are responsible for routing requests.

Before define the actual controller let's explicit define how a controller is shaped.

Create a interfaces/ folder under src, and add the controller.interface.ts file.

This file as expected will contains the shape of all out Controller classes.

// src/interfaces/controller.interface.ts
import { Hono } from "hono";
import type { HonoTypes } from "./../types/hono.type";

import type { BlankSchema } from "hono/types";

export interface Controller {
 controller: Hono<HonoTypes, BlankSchema, "/">;
 routes(): any;
}

The HonoTypes is an handy type used to define some global type, let's define it in the src/types/hono.type.ts file.

//src/types/hono.type.ts
import type { Promisify, RateLimitInfo } from "hono-rate-limiter";

export type HonoTypes = {
 Variables: {
  userId: string;
  rateLimit: RateLimitInfo;
  rateLimitStore: {
   getKey?: (key: string) => Promisify<RateLimitInfo | undefined>;
   resetKey: (key: string) => Promisify<void>;
  };
 };
};

Now let's define the Authentication Controller, create a controllers/ folder under src/ and add auth.controller.ts file.

Here we have to define a controller class that implements the Controller interface. Let's do it.

// src/controllers/auth.controller.ts

import { Hono } from "hono";
import type { HonoTypes } from "./../types/hono.type";
import { injectable } from "tsyringe";
import { Controller } from "../interfaces/controller.interface";

@injectable()
export class AuthController implements Controller {
 controller = new Hono<HonoTypes>();

 constructor() {}

 routes() {
  return this.controller;
 }
}

This is the shape of our AuthController and it will be the shape of all the other controller that you will implements in your application.

The @injectable keywords is a decorator that tells us that this class is a dependency of the project and we can retrive its instance everywhere in the application, because it will be injected at runtime, I link here the official documentation.

Then we will se that we can retrive it by doing:

const instance = container.resolve(AuthController);

But the question is: where do I have to retrieve it? Easy, in the index.ts . This file is very important, it is the entry point of your application, every thing starts from there.

Most likely, by running

bun create hono@latest

You will probably get a index.ts like this:

// src/index.ts
import { Hono } from "hono";

const app = new Hono();

app.get("/", (c) => {
 return c.text("Hello Hono!");
});

export default app;

We will now edit a bit to reflect our needs.

// src/index.ts
import "reflect-metadata";
import { Hono } from "hono";
import { container } from "tsyringe";
import { AuthController } from "./controllers/auth.controller";

/* ----------------------------------- Api ---------------------------------- */

const app = new Hono().basePath("/api");

/* --------------------------------- Routes --------------------------------- */

const authRoutes = container.resolve(AuthController).routes();

app.route("/auth", authRoutes);

app.get("/", (c) => {
 return c.text("Hello Hono!");
});

/* -----------------------------------Exports----------------------------------*/

export default app;

Seems all clear:

• We add a base path for the application, now all the routes that out app handle are under the /api route.
• We "import" our instance of the AuthController.
• We define the /auth route, for handling our authentication routes.
• We add the import "reflect-metadata"; for the tsyringe lib to run on bun.
• We can keep the GET endpoint on / for now, just for testing purpose, but it is up to you.

Defining routes

Now that we have our controller we can just define routes inside of it.

As you can imagine for now we need just login and signup, let's see how can we do it in Hono with our setup.

// src/controllers/auth.controller.ts
import { Hono } from "hono";
import type { HonoTypes } from "./../types/hono.type";
import { inject, injectable } from "tsyringe";
import { Controller } from "../interfaces/controller.interface";
import { zValidator } from "@hono/zod-validator";
import { loginDTO } from "../dtos/login.dto";
import { signUpDTO } from "../dtos/signup.dto";
import { AuthService } from "../services/auth.service";
import { limiter } from "../middlewares/limiter.middleware";

@injectable()
export class AuthController implements Controller {
 controller = new Hono<HonoTypes>();

 constructor(
  @inject(AuthService) private readonly authService: AuthService,
  @inject(RefreshTokenService)
  private readonly refreshTokenService: RefreshTokenService,
  @inject(EmailVerificationsService)
  private readonly emailVerificationsService: EmailVerificationsService,
  @inject(PasswordResetService)
  private readonly passwordResetService: PasswordResetService
 ) {}

 routes() {
  return this.controller
   .post(
    "/login",
    zValidator("json", loginDTO),
    limiter({ limit: 10, minutes: 60 }),
    async (context) => {
     const body = context.req.valid("json");
     const { user, accessToken, refreshToken } =
      await this.authService.login(body);
     return context.json({ user, accessToken, refreshToken });
    }
   )
   .post(
    "/signup",
    zValidator("json", signUpDTO),
    limiter({ limit: 10, minutes: 60 }),
    async (context) => {
     const data = context.req.valid("json");
     const newUser = await this.authService.signup(data);
     return context.json(newUser);
    }
   );
 }
}

Of course we need 2 POST endpoint, and in Hono, you can pass few things as parameter in a route, I will not go in detail of everything since we will see what we need on the fly.

For now you need to know that:

• The first parameter is the path of your endpoint,
• You can eventually pass a validator and/or a limiter or whatever middleware you want,
• lastly you will have your function that will be exectued whenever the endpoint get triggered, usually it is asyncronous, for obvious reason.

As you can see I keep the response JSON as clean as possibile, to make it easier to deserialize in the frontend, but it is just my preference, you can pick wich standard you most like, in this case I will highly suggest you to make a custom response object, to be as consistent as possible.

There are a lot of stuff beign added in this snippet, so let's try to make some order.

Zod DTOs Validation

The zValidator() function comes from the zod-validator hono library, as you can imagine, this function actually takes 2 parameters, a string, that will be used to validate it, and a zod object.

I prefer to keep all the DTOs (Data Transfer Object) in a separate folder. You can create the folder /dtos under /src and create the file login.dto.ts and user.dto.ts.

Data Transfer Objects (DTOs) are used to define the shape of data that is passed. They are used to validate data and ensure that the correct data is being passedto the correct methods.

For the Login DTO is all simple, just email and password, so:

// src/dtos/login.dto.ts

import { z } from "zod";

export const loginDTO = z.object({
 email: z
  .string({
   required_error: "email-required",
  })
  .email(),
 password: z
  .string({
   required_error: "password-required",
  })
  .min(8, "password-too-short")
  .max(32, "password-too-long"),
});

export type LoginDTO = z.infer<typeof loginDTO>;

As you can see in Zod you can also include custom error messages, and custom type of validation, I also infer the type from the zod object, so we can use it also in the service, as object that is passed from the controller, it will be much cleaner in a minute.

Of course in the body of the function I actually validate this object that I recive as a request with:

const data = context.req.valid("json");

We use "json" as a key, and is the same key we put in the zValidator(). This process ensure us that we will have full type safety across the endpoint, and we do not get some data that we don't actually need.

The next step is to do the same for Sign Up DTO,

// src/dtos/signup.dto.ts

import { z } from "zod";
import { createInsertSchema, createSelectSchema } from "drizzle-zod";
import { usersTable } from "./../tables";

export const signUpDTO = createInsertSchema(usersTable)
 .extend({
  passwordConfirmation: z.string({
   required_error: "password-confirmation-required",
  }),
  email: z.string().email(),
 })
 .omit({
  id: true,
  createdAt: true,
  updatedAt: true,
 })
 .refine((data) => data.password === data.passwordConfirmation, {
  message: "passwords-donot-match",
  path: ["passwordConfirmation"],
 });

export type SignUpDTO = z.infer<typeof signUpDTO>;

So now the "music" is a bit different than before, as you can see we introduce two new things, createInsertSchema and usersTable.

The createInsertSchema() is a function that comes from drizzle-zod a very convenient package to use in combo with Drizzle. It provides some time-saving API that will "translate" your Drizzle Schema into zod object, both for insert and for the selection.

So the createInsertSchema() will take a Zod Schema as an argument and will return a Zod Object.

For the usersTable we will get there in a minute.

In this case we do also need some other adjustment to the created Zod Object, since we have to extend it with the password confirmation and we of course do not need to insert the id, createdAt and updatedAt when we create a new user from the signup form.

We finally refine the Zod Object by ensuring that the password and passwordConfirmation are the same.

Users Table

I talk about zod validation and I mention the usersTable but I actually never declare it, let's do it right now.

As I said early in the article we will store all the Drizzle Schema of the database under the src/infrastructure/database/tables/ folder, so create the users.table.ts file under this folder.

// src/infrastructure/database/tables/users.table.ts
import { citext, timestamps } from "./utils";
import { boolean, pgTable, text } from "drizzle-orm/pg-core";
import { createId } from "@paralleldrive/cuid2";

export const usersTable = pgTable("users", {
 id: text("id")
  .primaryKey()
  .$defaultFn(() => createId()),
 email: citext("email").notNull().unique(),
 password: text("password").notNull(),
 ...timestamps,
});

This is the structure of the usersTable so far, I will not go in detail of the Drizzle implementation, you can find a good guide on their documentation.

Just a quick reminder to create a src/infrastructure/database/tables/index.ts file:

// src/infrastructure/database/tables/index.ts
export * from "./users.table";

In that way we can reference all the schemas in one in the drizzle.config.ts, we just mention last chapter.

// src/infrastructure/database/index.ts
import { drizzle } from "drizzle-orm/postgres-js";
import postgres from "postgres";
import * as schema from "./tables"; // Add the import here

export const client = postgres(Bun.env.DATABASE_URL ?? "", { max: 10 });
export const db = drizzle(client, { schema });

There are somethings that we actually did not encounter so far, the createId() function, that is just a function to create reliable id from the paralleldrive library, but also the citext and timestamps.

The citext represent the case insensitive text and it is just a customType for Drizzle, and the timestamps as you can imagine are just the createdAt and updatedAt fields "merged together".

You can place both under the src/infrastructure/database/tables/utils.ts file, that you have to create.

// src/infrastructure/database/tables/utils.ts
import { timestamp } from "drizzle-orm/pg-core";
import { customType } from "drizzle-orm/pg-core";

export const citext = customType<{ data: string }>({
 dataType() {
  return "citext";
 },
});

export const timestamps = {
 createdAt: timestamp("created_at", {
  mode: "date",
  withTimezone: true,
 })
  .notNull()
  .defaultNow(),
 updatedAt: timestamp("updated_at", {
  mode: "date",
  withTimezone: true,
 })
  .notNull()
  .defaultNow(),
};

A very important step is to create

Limiter Middleware

The limiter middleware comes in handy when you have to ensure that users not spam your endpoints, so you can create a src/middleware/limiter.middleware.ts file.

// src/middleware/limiter.middleware.ts
import { rateLimiter } from "hono-rate-limiter";
import type { HonoTypes } from "./../types/hono.type";

export function limiter({
 limit,
 minutes,
 key = "",
}: {
 limit: number;
 minutes: number;
 key?: string;
}) {
 return rateLimiter({
  windowMs: minutes * 60 * 1000, // every x minutes
  limit, // Limit each IP to 100 requests per `window` (here, per 15 minutes).
  standardHeaders: "draft-6", // draft-6: `RateLimit-*` headers; draft-7: combined `RateLimit` header
  keyGenerator: (c) => {
   const vars = c.var as HonoTypes["Variables"];
   const clientKey = vars.userId || c.req.header("x-forwarded-for");
   const pathKey = key || c.req.routePath;
   return `${clientKey}_${pathKey}`;
  }, // Method to generate custom identifiers for clients.
 });
}

Login and Signup Service

As you can see I almost cover everything I show you in the AuthController but I didn't mention the most important part, the AuthService.

As I mention before services in general are responsible for handling business logic.

Obviously we will use Dependency Injection also for the Services, the base of the AuthService and in general of the other services too, will be a basic @injectable() class with a bunch of methods:

@injectable()
export class AuthService {
 constructor() {}
}

Inside of the service a right as we saw before, we'll need only two methods for now, login and signup.

// src/services/auth.service.ts
import { inject, injectable } from "tsyringe";
import { BadRequest, InternalError } from "../common/error";
import { HTTPException } from "hono/http-exception";
import { HashingService } from "./hashing.service";
import { LoginDTO } from "../dtos/login.dto";
import { SignUpDTO } from "../dtos/signup.dto";
import { UsersRepository } from "../repositories/user.repository";

@injectable()
export class AuthService {
 constructor(
  @inject(HashingService) private readonly hashingService: HashingService,
  @inject(UsersRepository) private readonly usersRepository: UsersRepository
 ) {}

 async login(data: LoginDTO) {
  try {
   const user = await this.usersRepository.findOneByEmail(data.email);
   if (!user) {
    throw BadRequest("invalid-email");
   }
   const hashedPassword = await this.hashingService.verify(
    user.password,
    data.password
   );

   if (!hashedPassword) {
    throw BadRequest("wrong-password");
   }

   return user;
  } catch (e) {
   if (e instanceof HTTPException) {
    throw e;
   }
   throw InternalError("error-login");
  }
 }

 async signup(data: SignUpDTO) {
  try {
   const existingEmail = await this.usersRepository.findOneByEmail(
    data.email
   );
   if (existingEmail) {
    throw BadRequest("email-already-in-use");
   }
   const hashedPassword = await this.hashingService.hash(data.password);
   data.password = hashedPassword;

   const newUser = await this.usersRepository.create(data);

   return newUser;
  } catch (e) {
   if (e instanceof HTTPException) {
    throw e;
   }
   throw InternalError("error-signup");
  }
 }
}

I know I introduced a lot of code, so let's break it down.

• Login

  • Check if an user at given email address is extisting, if not we throw error;
  • Check the password that the user send in the request and the hash of the password stored in the database, be basically hash again the password in the request and check if the two hash are the same, if yes it means it is the correct password, otherwise it is the wrong password.
  • then return the user.

• Signup

  • Check if email in the request is linked to some user, and exsist in the database;
  • If exist a user with the email sended in the request, you can't proceed with the sign up since a user with this email already exist, and the email is a unique attribute for the user.
  • If the email is not associated to any user, proceed with hashing the password in the request, set the hash as the password of the user;
  • create the new user and return it.

Error Handling

With the introduction of the service, I of course introduce the error handling part.

As for the response, I want to keep it minimal. So I create some predefined wrappers, so I can easy reference to them in my services:

// src/commons/error.ts
import { StatusCodes } from "./status-codes";
import { HTTPException } from "hono/http-exception";

export function TooManyRequests(message: string = "Too many requests") {
 return new HTTPException(StatusCodes.TOO_MANY_REQUESTS, { message });
}

export function Forbidden(message: string = "Forbidden") {
 return new HTTPException(StatusCodes.FORBIDDEN, { message });
}

export function Unauthorized(message: string = "Unauthorized") {
 return new HTTPException(StatusCodes.UNAUTHORIZED, { message });
}

export function NotFound(message: string = "Not Found") {
 return new HTTPException(StatusCodes.NOT_FOUND, { message });
}

export function BadRequest(message: string = "Bad Request") {
 return new HTTPException(StatusCodes.BAD_REQUEST, { message });
}

export function InternalError(message: string = "Internal Error") {
 return new HTTPException(StatusCodes.INTERNAL_SERVER_ERROR, { message });
}

As you can see these function wraps the default HTTPException that hono give to us, the StatusCode is an enum that is stored in a separate file, I will not paste it here, since it is a quite big file, but you can find it by yourself here, you just need to paste it, and copy in the src/costants/status-codes.ts file.

Hashing Service

Before diving into the Repository I will first introduce the Hashing Service, this is a very small service that is responsible to handle, as you can imagine, the hashing part of the application.

// src/services/hashing.service.ts
import { injectable } from "tsyringe";
import { Scrypt } from "oslo/password";

@injectable()
export class HashingService {
 private readonly hasher = new Scrypt();
 // private readonly hasher = new Argon2id(); // argon2id hasher

 async hash(data: string) {
  return this.hasher.hash(data);
 }

 async verify(hash: string, data: string) {
  return this.hasher.verify(hash, data);
 }
}

I use Scrpt as the hashing algorithm due to its higher compatability and it uses less memory than Argon2id.

You can use Argon2id or any other hashing algorithm you prefer, it will be the same as you can see in the comment line of code.

User Repository

As written in the introduction the repository layer is responsible to handle the interaction with the db and he does not know anything about the buisness logic or route handling.

It just write, delete, update and retrive data from the database.

Since DrizzleORM offers also the possibility to perform transaction in PostgreSQL we will define a general shape for a Repository.

// src/interfaces/repository.interface.ts
import type { DatabaseProvider } from "../providers/database.provider";

export interface Repository {
 trxHost(trx: DatabaseProvider): any;
}

The interface is really simple, but as usual I introduce a new piece of the puzzle.

Database Provider

I do not introduced the provider concept so far, so let me explain better.

This is how the DatabaseProvider looks like.

// src/providers/database.provider.ts
import { container } from "tsyringe";
import { db } from "../infrastructure/database";

// Symbol
export const DatabaseProvider = Symbol("DATABASE_TOKEN");

// Type
export type DatabaseProvider = typeof db;

// Register
container.register<DatabaseProvider>(DatabaseProvider, { useValue: db });

As you can see I'm using the db instance that I previously declared in the infrastructure part. In that way we ensure that we are using the same instance of db across all the application, and we avoid the "error prone" approach of importing manually the db inside each repository.

Indeed in this case tsyringe provides us the same instance of the same object across all the application, thanks to Dependency Injection.

User Repository Implementation

In this project I will not make a separate distinction between the shape of the repository and the repository implementation it self, you follow this approach if you prefer ,but let's see how the user repository is made up.

// src/repositories/user.repository.ts
import { inject, injectable } from "tsyringe";
import type { Repository } from "../interfaces/repository.interface";
import { eq, type InferInsertModel } from "drizzle-orm";
import { DatabaseProvider } from "../providers/database.provider";
import { usersTable } from "../infrastructure/database/tables";
import { takeFirstOrThrow } from "../infrastructure/database/utils";
import { BadRequest } from "../common/error";

export type CreateUser = InferInsertModel<typeof usersTable>;
export type UpdateUser = Partial<CreateUser>;

@injectable()
export class UsersRepository implements Repository {
 constructor(@inject(DatabaseProvider) private db: DatabaseProvider) {}

 async findAll() {
  return this.db.query.usersTable.findMany();
 }

 async findOneById(id: string) {
  return this.db.query.usersTable.findFirst({
   where: eq(usersTable.id, id),
  });
 }

 async findOneByIdOrThrow(id: string) {
  const user = await this.findOneById(id);
  if (!user) throw BadRequest("user-not-found");
  return user;
 }

 async findOneByEmail(email: string) {
  return this.db.query.usersTable.findFirst({
   where: eq(usersTable.email, email),
  });
 }

 async create(data: CreateUser) {
  return this.db
   .insert(usersTable)
   .values(data)
   .returning()
   .then(takeFirstOrThrow);
 }

 async update(id: string, data: UpdateUser) {
  return this.db
   .update(usersTable)
   .set(data)
   .where(eq(usersTable.id, id))
   .returning()
   .then(takeFirstOrThrow);
 }

 trxHost(trx: DatabaseProvider) {
  return new UsersRepository(trx);
 }
}

Here we are using a lot of things that we mention in the previous paragraphs, like the takeFirstOrThrow function, the DatabaseProvider the super helpfull InferInsertModel from drizzle-zod, so I will not go in details of these, as I wont go in details of the drizzle query creation, since it really depends on your ORM that of course could possibly be not Drizzle.

Starting Docker and Testing

So far we actually implement a very basic email and password system we will go in deep with the other features (sessions, refreshToken, email validation, etc...) later on in the article, I really wanna go step-by-step so you can fully understand the whole process.

For testing out what you made so far you can use Postman or httpie or what you prefer to test your endpoint.

But first you need to start the whole system.

• Generate the migration: drizzle-kit generate,
• Push the changes: drizzle-kit push,
• Start Docker: docker-compose up -d --build

For the for the sake of simplicity I will just put those script inside my package.json:

"scripts": {
    "db:push": "drizzle-kit push",
    "db:generate": "drizzle-kit generate",
    "db:migrate": "drizzle-kit migrate",
    "db:studio": "drizzle-kit studio --verbose",
    "dev": "bun run --hot src/index.ts",
    "initialize": "bun install && docker-compose up --no-recreate -d && bun db:migrate",
    "docker:up": "docker-compose up -d",
    "docker:build": "docker-compose up -d --build"
  },

I just add some self explanatory scripts.

For spin up for the first time the system, just run:

bun db:generate

To generate the SQL file for the migration and:

bun initialize

To spin up everything, install dependencies, start docker and do the migration.

Once everything is done correctly you can move on with testing out the endpoints.

The json body of the POST request for the signup will be something like that:

{
 "email": "email@example.com",
 "password": `test1234`,
 "passwordConfirmation": "test1234"
}

And the json body of the POST request for the login will be something like that:

{
 "email": "email@example.com",
 "password": `test1234`
}

The url can vary depends on what you put in the controller, in the base path, your port, ecc..

In my case I just need to query http:

JWT Access and Refresh Token System

Before deep diving into the implementation of the system, let me explain what a Refresh Token system is and how it works.

What is it?

In the refresh token system, there are two different tokens refreshToken and accessToken.

• The accessToken is a short-live token (usually from couple of minutes up to few days), it is the token that is in the Authorization field of the http request from the client. This token is being validated each times we put a special middleware in the route (we will see it later on), it is not validated, the server will respond with a 401 Unauthorized.

How it works?

So far it seems like a normal JWT authentication in wich the user ,when the accessToken is expired, logs out even if he use the application and send request every day (very bad UX).

• In the refreshToken system we ensure that if the user keeps using the application, and keeps sending request to the server it will always get fresh new accessToken when it expires, so we the user will not logs out.
• For doing that we actually have the needs of a new token, the refreshToken , this is usually a long-live token (usually a month or so), that the client store in a persistent database, cache or shared preferences.
• The server does not have to store it, but it can be usefull if you wanna for example logs out a user if something bad happen, or if you wanna log out only certain devices (if you store the device ID), we will not cover this section in this article, but we will still store in the database the refreshToken.
• This token is responsible to handle the case in wich the user request the access to a protected routes with an expired accessToken, in this case the refreshToken "tells" the server that this user (who own the refreshToken) have the right to access the resource even if his accessToken, because his refreshToken is still valid.
• The whole process is handled both from the client and the server, the flow is the following.
  • The user request the access to a protected resource with an expired accessToken,
  • The server respond with a 401 Unathorized
  • The client intercept this error from the server, and try to send a POST request to the /refresh-token endpoint in the server, with his own refresh token that he's is storing in some memory or disk.
  • The server recive the POST request within the client refreshToken in the body.
  • If the refreshToken is still valid, and it is not expired, the server will proceed to generate fresh new accessToken and new refreshToken (and store it in disk) and send it back to the client.
  • The client, if everything so far goes well, will fetch the response, stores the new accessToken and refreshToken from the server, and retry the previous request, with the updated accessToken, otherwise it will presumably log out the user.

As you can see there is a lot of client-server communication, and I will cover only the server parts, because the client implementation can be various depends on your platform and technology (web, mobile, etc...).

Defining Routes

The first thing we need is to specify the endpoint where the user can send the POST request to ask for a new refresh and accessToken.

We can put in the AuthController since it is part of the domain of the "authentication".

As explained before, the user has to send his stored refresh token (the one in the client) to be able to request a new one. I will not separate the DTO for this route, since it is only a string.

// src/controllers/auth.controlle.ts

import { Hono } from "hono";
import type { HonoTypes } from "../types";
import { injectable } from "tsyringe";
import { zValidator } from "@hono/zod-validator";
import { UserService } from "../services/user.service";
import { AuthService } from "../services/auth.service";
import { RefreshTokenService } from "../services/refresh-token.service";
import { loginDto } from "./../../../dtos/login.dto";
import { limiter } from "../middleware/rate-limiter.middlware";
import { z } from "zod":

@injectable()
export class AuthController implements Controller {

 controller = new Hono<HonoTypes>();

 constructor(){
    @inject(AuthService) private readonly authService: AuthService,
    @inject(RefreshTokenService) private readonly refreshTokenService: RefreshTokenService,
 }

 routes(){
     return this.controller
        // login and signup routes...
        .post(
        "/refresh-token",
        zValidator("json", refreshTokenDTO),
        limiter({ limit: 10, minutes: 60 }),
        async (context) => {
          const refreshTokenBody = context.req.valid("json");
          const { accessToken, refreshToken } =
            await this.refreshTokenService.refreshToken(
              refreshTokenBody.refreshToken,
            );
          return context.json({ accessToken, refreshToken });
        },
      );
 }
}

Refresh Token DTO

The Refresh Token DTO is straight forward, I wont spend more time on it.

// src/dtos/refresh-token.dto.ts
import { z } from "zod";

export const refreshTokenDTO = z.object({
 refreshToken: z.string(),
});

export type RefreshTokenDTO = z.infer<typeof refreshTokenDTO>;

Refresh Token Service

As for the the other endpoints, we do not want to manage the business logic inside the controller, so we create a separate class for it. Create the refresh-token.service.ts under the service folder.

// src/services/refresh-token.service.ts
import { inject, injectable } from "tsyringe";
import { sign, verify } from "hono/jwt";
import { config } from "../common/config";
import { RefreshTokenRepository } from "../repositories/refresh-token.repository";
import { BadRequest, Unauthorized } from "../common/errors";


@injectable()
export class RefreshTokenService {
  constructor(
    @inject(RefreshTokenRepository) private readonly refreshTokenRepository: RefreshTokenRepository,
  ) {}

  // Update refresh token by generating a new one and invalidating the old one
  async refreshToken(refreshToken: string) {
    const session =
      await this.refreshTokenRepository.getSessionByToken(refreshToken);

    if (!session || session.expiresAt < new Date()) {
      throw BadRequest("invalid-refresh-token");
    }

    const newAccessToken = await this.generateAccessToken(session.userId);
    const newRefreshToken = await this.generateRefreshToken(session.userId);

    await this.refreshTokenRepository.updateRefreshToken(
      session.userId,
      refreshToken,
      newRefreshToken,
      config.jwt.refreshExpiresInDate
    );

    return { refreshToken: newRefreshToken, accessToken: newAccessToken };
  }

  async storeSession(userId: string, refreshToken: string) {
    await this.refreshTokenRepository.storeRefreshToken(
      userId,
      refreshToken,
      config.jwt.refreshExpiresInDate
    );
  }

  async generateRefreshToken(userId: string){
    const payload = {
      sub: userId,
      exp: config.jwt.refreshExpiresIn,
    };
    const refreshToken = await sign(payload, config.jwt.refreshSecret));
    return refreshToken;
  }

  async generateAccessToken(userId: string): Promise<string> {
    const payload = {
      sub: userId,
      exp: config.jwt.accessExpiresIn,
    };
    const accessToken = await sign(payload, config.jwt.accessSecret);
    return accessToken;
  }

  async removeRefreshToken(refreshToken: string){
    await this.refreshTokenRepository.removeRefreshToken(refreshToken);
  }

  async invalidateUserSessions(userId: string) {
    await this.refreshTokenRepository.invalidateAllTokensForUser(userId);
  }
}

As usual I will break down the code in different steps.

• Refresh Token Function

  • The refresh token function is responsible to retrieve, if exist in the database, a session based on the given refresh token in the request.
  • If it does not exist or it is expired, the function will throw an error.
  • Otherwise it will generate both accessToken and refreshToken and it wills store them in the database.
    • Both the tokens are generated via the hono/jwt library, that hono provides us.
    • They are generated based on the configuration parameters.
  • Finally return both the tokens

• JWT Secrets I introduced new secrets that need to be added to the .env file.

JWT_ACCESS_SECRET="your_access_secret"
JWT_REFRESH_SECRET="your_refresh_secret"

Now the config.type.ts file where there are all the types of the configuration need to be updated too.

// src/types/config.type.ts

export const config = (): Config => ({
 isProduction: process.env.NODE_ENV === "production",
 api: {
  origin: process.env.ORIGIN ?? "",
 },
 postgres: {
  url: process.env.DATABASE_URL ?? "",
 },
 jwt: {
  accessSecret: process.env.JWT_ACCESS_SECRET || "your_access_secret",
  refreshSecret: process.env.JWT_REFRESH_SECRET || "your_refresh_secret",
  accessExpiresIn: Math.floor(Date.now() / 1000) + 60 * 60 * 24 * 7, // 7 days
  refreshExpiresIn: Math.floor(Date.now() / 1000) + 60 * 60 * 24 * 30, // 30 days
  refreshExpiresInDate: new Date(Date.now() + 60 * 60 * 24 * 30 * 1000), // 30 days
 },
});

// the rest of the configuration ...

interface Config {
 isProduction: boolean;
 api: ApiConfig;
 postgres: PostgresConfig;
 jwt: JwtConfig;
}
interface JwtConfig {
 accessSecret: string;
 refreshSecret: string;
 accessExpiresIn: number;
 refreshExpiresIn: number;
 refreshExpiresInDate: Date;
}

Now it is up to you to choose the expiration dates of the accessToken and refreshToken, as well as the secrets.

Refresh Token Repository

Also this service requires a repository since the sessions are stored in the persistent database as discussed previously.

// src/repositories/refres-token.repository.ts
import { inject, injectable } from "tsyringe";
import { DatabaseProvider } from "../providers";
import { eq } from "drizzle-orm";
import { sessionsTable } from "../tables";
import { and } from "drizzle-orm/expressions";
import { takeFirstOrThrow } from "../infrastructure/database/utils";
import { config } from "../common/config";

@injectable()
export class RefreshTokenRepository {
 constructor(@inject(DatabaseProvider) private db: DatabaseProvider) {}

 async storeRefreshToken(userId: string, token: string, expiresAt: Date) {
  return this.db
   .insert(sessionsTable)
   .values({ userId, token, expiresAt })
   .returning()
   .then(takeFirstOrThrow);
 }

 async removeRefreshToken(token: string) {
  return this.db.delete(sessionsTable).where(eq(sessionsTable.token, token));
 }

 async getSessionByToken(refreshToken: string) {
  return this.db.query.sessionsTable.findFirst({
   where: eq(sessionsTable.token, refreshToken),
  });
 }

 async updateRefreshToken(
  userId: string,
  oldToken: string,
  newToken: string,
  expiresAt: Date
 ) {
  const body = { userId, token: newToken, expiresAt };
  await this.db.transaction(async (trx) => {
   await trx.delete(sessionsTable).where(eq(sessionsTable.token, oldToken));
   await trx.insert(sessionsTable).values(body);
  });
 }

 async invalidateAllTokensForUser(userId: string) {
  return this.db
   .delete(sessionsTable)
   .where(eq(sessionsTable.userId, userId));
 }
}

In this service the Database Provider that has been declared in the past is needed since a db transaction is needed. For a reference of what is a transaction I will leave the official definition in the postgres documentation:

Transactions are a fundamental concept of all database systems. The essential point of a transaction is that it bundles multiple steps into a single, all-or-nothing operation. The intermediate states between the steps are not visible to other concurrent transactions, and if some failure occurs that prevents the transaction from completing, then none of the steps ?affect the database at all.

Sessions Table

The session table introduced in the repository contains all the sessions of the users.

It will be located under the src/infrastructure/database/tables/ folder:

// src/infrastructure/database/tables/sessions.table.ts
import { cuid2 } from "./utils";
import { usersTable } from "./users.table";
import { pgTable, text, timestamp } from "drizzle-orm/pg-core";
import { relations } from "drizzle-orm";
import { createId } from "@paralleldrive/cuid2";

export const sessionsTable = pgTable("sessions", {
 id: text("id")
  .primaryKey()
  .$defaultFn(() => createId()),
 token: text("token").notNull(),
 userId: text("user_id")
  .notNull()
  .references(() => usersTable.id, { onDelete: "cascade" }),
 expiresAt: timestamp("expires_at", {
  withTimezone: true,
  mode: "date",
 }).notNull(),
});

export const sessionRelationships = relations(
 sessionsTable,
 ({ many, one }) => ({
  users: one(usersTable, {
   fields: [sessionsTable.userId],
   references: [usersTable.id],
  }),
 })
);

Since we added the relationship in the sessionsTable we have to do the same for the usersTable

// src/infrastructure/database/tables/users.table.ts
import { relations } from "drizzle-orm";
import { sessionsTable } from "./sessions.table";
// rest of the imports ...

export const usersTable = ... // table declaration

//rest of the code and table definitions ...

export const usersRelations = relations(usersTable, ({ many, one }) => ({
  sessions: many(sessionsTable),}));

[ ⚠️⚠️⚠️ ] Do not forget to generate the migration and push it once you have done with the editing of your schema [ ⚠️⚠️⚠️ ]

Authentication Middleware

Once defined the routes, the logic and the database integration of the JWT refresh token system, we need to find a way to actually prevent the access to certain resources.

In hono, and other frameworks too, offers the possibility of defining middleware as we did before for the limiter and zValidator().

Let's define one for protecting only certain routes.

// src/middleware/auth.middleware.ts
import type { MiddlewareHandler } from "hono";
import { createMiddleware } from "hono/factory";
import { verify } from "hono/jwt";
import { Unauthorized } from "../common/error";
import { config } from "../types/config.type";

export const validateAuthSession: MiddlewareHandler = async (c, next) => {
 const authHeader = c.req.header("Authorization") ?? "";
 const token = authHeader.startsWith("Bearer ") ? authHeader.slice(7) : null;

 if (!token) {
  c.set("userId", null);
  return next();
 }

 try {
  // Verify the access token
  const payload = await verify(token, config.jwt.accessSecret);
  const userId = payload.sub as string;

  if (!userId) {
   c.set("userId", null);
   return next();
  }

  // Set user id in context
  c.set("userId", userId);
 } catch (error) {
  // If token verification fails, set user to null
  c.set("user", null);
 }

 return next();
};

export const requireAuth: MiddlewareHandler<{
 Variables: {
  userId: string;
 };
}> = createMiddleware(async (c, next) => {
 const user = c.var.userId;
 if (!user)
  throw Unauthorized("You must be logged in to access this resource");
 return next();
});

As you can see I come up with 2 different middlewares, this is why I will use the validateAuthSession globally, so at each request, the JWT will be validated. And only where needed the requireAuth middleware is placed next to the route to protect it.

To define a global middleware just add this two lines in the index.ts :

// src/index.ts

import { validateAuthSession } from "./server/api/middleware/auth.middleware";

/* --------------------------- Global Middlewares --------------------------- */

app.use("*", cors({ origin: "*" })); // Allow CORS for all origins
app.use(validateAuthSession);
app.use(logger()); // [OPTIONAL] if you wanna log all the request and response, the import is import { logger } from "hono/logger";

and if you wanna protect a route, just use the requireAuth middleware on the route:

 .post(
        "/protected-resource",
        requireAuth,
        async (context) => {
          return context.text("Access acquired to the protected resource");
        },
      );

<a name="update-login-flow"></a>

Update Login Flow

Since now handle our sessions with JWT we need to find a way to send back to the client his accessToken and refreshToken so he can e authenticated and can access all the protected resources.

For doing that we take advantage of the RefreshTokenService previously created, since this is part of the business logic we're gonna handle it in the AuthService.

// src/services/auth.service.ts

// Rest of the imports...
import { RefreshTokenService } from "./refresh-token.service";

@injectable()
export class AuthService {
  constructor(
    @inject(HashingService) private readonly hashingService: HashingService,
    @inject(RefreshTokenService) private readonly refreshTokenService: RefreshTokenService,
    @inject(UsersRepository) private readonly usersRepository: UsersRepository,
  ) {}

  async login(data: LoginDTO) {
    try {
      const user = await this.usersRepository.findOneByEmail(data.email);
      if (!user) {
        throw BadRequest("invalid-email");
      }

      const hashedPassword = await this.hashingService.verify(
        user.password,
        data.password,
      );

      if (!hashedPassword) {
        throw BadRequest("wrong-password");
      }

      //if everything is good, create refresh token and access token
      const accessToken = await this.refreshTokenService.generateAccessToken(
        user.id,
      );
      const refreshToken = await this.refreshTokenService.generateRefreshToken(
        user.id,
      );
      //store the refresh token session in the database
      await this.refreshTokenService.storeSession(user.id, refreshToken);

      return { user, accessToken, refreshToken };
    } catch (e) {
      if (e instanceof HTTPException) {
        throw e;
      }
      throw InternalError("error-login");
    }
  }

// Rest of the code ...

Now let's reflect the changes in the AuthController.

// src/controllers/auth.controllers.ts

// Rest of the code...
 .post(
        "/login",
        zValidator("json", loginDTO),
        limiter({ limit: 10, minutes: 60 }),
        async (context) => {
          const body = context.req.valid("json");
          const { user, accessToken, refreshToken } =
            await this.authService.login(body);
          return context.json({ user, accessToken, refreshToken });
        },
      )
// Rest of the code...

Testing the endpoints

Now what you can do is to try is to perform a login as we seen in the last chapter.

You should receive an output like this when you login:

{
 "user": {
  "id": "mdh2e14meythwnvupsbxez2r",
  "email": "test@test.com",
  "password": "5b21310d820a9f0099c6e7fc8eefac3a:28160978a8833f334bd2c92f732b7572c73e5045189cf3b3efc39f45a1bab9b56b4dc23235895b304e46e4bbb6913238f3a79de5ef225d68f399baf76f36f062",
  "createdAt": "2024-10-27T15:31:10.420Z",
  "updatedAt": "2024-10-27T15:31:10.420Z"
 },

 "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJtZGgyZTE0bWV5dGh3bnZ1cHNieGV6MnIiLCJleHAiOjE3MzA3NDA5MzF9.-O2kj5Yf1c-PeAp2oDnlYYQZPmLdEG0b9TCFW_z_Yok",

 "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJtZGgyZTE0bWV5dGh3bnZ1cHNieGV6MnIiLCJleHAiOjE3MzI3MjgxMzF9.8DYcg6-y72tNmt6guYt5ePvoGiR1ZJto3M8J4ogVR14"
}

Now you can perform a POST request to the .../api/auth/refresh-token

According to our implementation the body should look like this.

{
 "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJtZGgyZTE0bWV5dGh3bnZ1cHNieGV6MnIiLCJleHAiOjE3MzI3MjgxMzF9.8DYcg6-y72tNmt6guYt5ePvoGiR1ZJto3M8J4ogVR14"
}

and you should get something like this

{
 "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJtZGgyZTE0bWV5dGh3bnZ1cHNieGV6MnIiLCJleHAiOjE3MzA3NDA5MzF9.-O2kj5Yf1c-PeAp2oDnlYYQZPmLdEG0b9TCFW_z_Yok",

 "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJtZGgyZTE0bWV5dGh3bnZ1cHNieGV6MnIiLCJleHAiOjE3MzI3MjgxMzF9.8DYcg6-y72tNmt6guYt5ePvoGiR1ZJto3M8J4ogVR14"
}

Two brand new accessToken and refreshToken.

<a name="email-verification"></a>

Email Verification

One thing necessary for a robust authentication is an email verification system, so the users cannot use incorrect or random email address to gather access at your content.

The general flow of an email verification system is the following:

• Once the user signup he will receive an email containing the instruction to activate his account (so verify his email), the possible ways at this point are more or less two:
  • Verify the user by making it click on a link. In this case the user will basically make a GET os POST request to a particular endpoint with some information in the query to verify himself.
  • Verify the user by sending him a verification code to enter after the registration in the client.
• Those two steps are similar but the final result is the same, the UX (for the client) will change a bit, in terms of server the system is basically identical, you will figure out how to switch between the two by your self.

Defining Routes

We needs just one route for this purpose, since there will be only one endpoint for the email validation.

// src/controllers/auth.controller.ts

// All the imports...

@injectable()
export class AuthController implements Controller {

 controller = new Hono<HonoTypes>();

 constructor(){
    @inject(AuthService) private readonly authService: AuthService,
    @inject(RefreshTokenService) private readonly refreshTokenService: RefreshTokenService,
    @inject(EmailVerificationsService) private readonly emailVerificationsService: EmailVerificationsService,
 }

 routes(){
     return this.controller
        // login, signup and refresh token routes...
        .get(
        "/verify/:userId/:token",
        limiter({ limit: 10, minutes: 60 }),
        async (context) => {
          const { userId, token } = context.req.param();
          await this.emailVerificationsService.processEmailVerificationRequest(
            userId,
            token,
          );
    // display or return something to the user
        return context.html(`<h1>Email verified!</h1>`)
        },
      );
  }
}

The returning object really depends on your client, I just put a generic title here because in my implementation the user is supposed click on a link and whenever he gets on this web page, a GET request will be made, and he will be validated (if token and userId are valid) .

Email Verification Service

The process here is pretty straightforward.

• Whenever a new user is created (signup) the service will process this request.
• It creates a new token, his hash (since we store the hash of the token, not the token itself), and the expiry.
• A new record in the emailVerificationsTable is created with the email that request the verification, the userId (the ones created in the signup), the hashed token, and the expiry.
• An email is sent to the email that request the verification.

That is when a new user is being created, let's see when the user request the actual verification.

• If a record in the emailVerificaitonsTable with the userId (the one in the param of the request) is found, the hased token is compared with the token in the params.
• If everything goes okay, the email verification record will be deleted.
• Finally the verified status inside the users record will be updated.

Let's implement what I just said.

// src/services/email-verification.service.ts
import { inject, injectable } from "tsyringe";
import { DatabaseProvider } from "../providers/database.provider";
import { HashingService } from "./hashing.service";
import { UsersRepository } from "../repositories/user.repository";
import { TokensService } from "./token.service";
import { MailerService } from "./mailer.service";
import { EmailVerificationsRepository } from "../repositories/email-verifications.repository";
import { BadRequest } from "../common/error";

@injectable()
export class EmailVerificationsService {
 constructor(
  @inject(DatabaseProvider) private readonly db: DatabaseProvider,
  @inject(TokensService) private readonly tokensService: TokensService,
  @inject(MailerService) private readonly mailerService: MailerService,
  @inject(HashingService) private readonly hashingService: HashingService,
  @inject(UsersRepository) private readonly usersRepository: UsersRepository,
  @inject(EmailVerificationsRepository)
  private readonly emailVerificationsRepository: EmailVerificationsRepository
 ) {}

 async dispatchEmailVerificationRequest(
  userId: string,
  requestedEmail: string
 ) {
  // generate a token and expiry
  const { token, expiry, hashedToken } =
   await this.tokensService.generateTokenWithExpiryAndHash({
    number: 15,
    time: 30,
    lifespan: "m",
    type: "STRING",
   });
  const user = await this.usersRepository.findOneByIdOrThrow(userId);

  // create a new email verification record
  await this.emailVerificationsRepository.create({
   requestedEmail,
   userId,
   hashedToken,
   expiresAt: expiry,
  });

  // A confirmation-required email message to the proposed new address, instructing the user to
  // confirm the change and providing a link for unexpected situations
  this.mailerService.sendEmailVerificationToken({
   to: requestedEmail,
   props: {
    link: token,
   },
  });
 }

 async processEmailVerificationRequest(userId: string, token: string) {
  const validRecord = await this.findAndBurnEmailVerificationToken(
   userId,
   token
  );
  if (!validRecord) throw BadRequest("invalid-token");
  await this.usersRepository.update(userId, {
   email: validRecord.requestedEmail,
   verified: true,
  });
 }

 private async findAndBurnEmailVerificationToken(
  userId: string,
  token: string
 ) {
  return this.db.transaction(async (trx: any) => {
   // find a valid record
   const emailVerificationRecord = await this.emailVerificationsRepository
    .trxHost(trx)
    .findValidRecord(userId);
   if (!emailVerificationRecord) return null;

   // check if the token is valid
   const isValidRecord = await this.hashingService.verify(
    emailVerificationRecord.hashedToken,
    token
   );
   if (!isValidRecord) return null;

   // burn the token if it is valid
   await this.emailVerificationsRepository
    .trxHost(trx)
    .deleteById(emailVerificationRecord.id);
   return emailVerificationRecord;
  });
 }
}

This service involve the actions of other services, since we need to generate tokens, hash and verify them, we need to send email and so on. So since this two features are most likely required in other part of the application let's split them in separated services.

Token Service

// src/services/token.service.ts
import { inject, injectable } from "tsyringe";
import { generateRandomString } from "oslo/crypto";
import { TimeSpan, createDate, type TimeSpanUnit } from "oslo";
import { HashingService } from "./hashing.service";

@injectable()
export class TokensService {
 constructor(
  @inject(HashingService) private readonly hashingService: HashingService
 ) {}

 generateNumberToken(number: number) {
  const alphabet = "1234567890";
  return generateRandomString(number, alphabet);
 }

 generateStringToken(number: number) {
  const alphabet = "23456789ABCDEFGHJKLMNPQRSTUVZ";
  return generateRandomString(number, alphabet);
 }

 generateTokenWithExpiry({
  number,
  time,
  lifespan,
  type,
 }: {
  number: number;
  time: number;
  lifespan: TimeSpanUnit;
  type: "NUMBER" | "STRING";
 }) {
  return {
   token:
    type === "NUMBER"
     ? this.generateNumberToken(number)
     : this.generateStringToken(number),
   expiry: createDate(new TimeSpan(time, lifespan)),
  };
 }

 async generateTokenWithExpiryAndHash({
  number,
  time,
  lifespan,
  type,
 }: {
  number: number;
  time: number;
  lifespan: TimeSpanUnit;
  type: "NUMBER" | "STRING";
 }) {
  const token =
   type === "NUMBER"
    ? this.generateNumberToken(number)
    : this.generateStringToken(number);
  const hashedToken = await this.hashingService.hash(token);
  return {
   token,
   hashedToken,
   expiry: createDate(new TimeSpan(time, lifespan)),
  };
 }
}

As you can see the token service is pretty straightforward, it relies mainly on the hashing service and it expose useful API to generate random and secure token.

Mailer Service

The mailer service is responsible to give the possibility to send email using html as template language.

// src/services/mailer.service.ts
import fs from "fs";
import path from "path";
import handlebars from "handlebars";
import { injectable } from "tsyringe";
import nodemailer from "nodemailer";

type SendMail = {
 to: string | string[];
 subject: string;
 html: string;
};

type SendTemplate<T> = {
 to: string | string[];
 props: T;
};

@injectable()
export class MailerService {
 private nodemailer = nodemailer.createTransport({
  host: "smtp.ethereal.email",
  port: 587,
  secure: false, // Use `true` for port 465, `false` for all other ports
  auth: {
   user: "adella.hoppe@ethereal.email",
   pass: "dshNQZYhATsdJ3ENke",
  },
 });

 sendEmailVerificationToken(data: SendTemplate<{ link: string }>) {
  const template = handlebars.compile(this.getTemplate("email-verification"));
  return this.send({
   to: data.to,
   subject: "Email Verification",
   html: template({ link: data.props.link }),
  });
 }

 sendResetPasswordOTP(data: SendTemplate<{ otp: string }>) {
  const template = handlebars.compile(this.getTemplate("reset-password"));
  return this.send({
   to: data.to,
   subject: "Password Reset",
   html: template({ code: data.props.otp }),
  });
 }

 private async send({ to, subject, html }: SendMail) {
  const message = await this.nodemailer.sendMail({
   from: '"Example" <example@ethereal.email>', // sender address
   bcc: to,
   subject, // Subject line
   text: html,
   html,
  });
 }

 private getTemplate(template: string) {
  const __dirname = path.dirname(__filename); // get the name of the directory
  return fs.readFileSync(
   path.join(__dirname, `../infrastructure/email-templates/${template}.hbs`),
   "utf-8"
  );
 }
}

Email Templates

Since this is not the main goal of the guide I will not dive into the email template part, but here you can find the templates that I have used in the guide.

Those files are .hbs that are basically Handlebars file, that is a templating engine, you can find the documentation here

Handlebars is a simple templating language. It uses a template and an input object to generate HTML or other text formats. Handlebars templates look like regular text with embedded Handlebars expressions.

Email Verifications Repository

The email verifications

// src/repositories/email-verifications.repository.ts
import { inject, injectable } from "tsyringe";
import { DatabaseProvider } from "../providers";
import { and, eq, gte, lte, type InferInsertModel } from "drizzle-orm";
import type { Repository } from "../interfaces/repository.interface";
import { takeFirst, takeFirstOrThrow } from "../infrastructure/database/utils";
import { emailVerificationsTable } from "./../../../tables";

export type CreateEmailVerification = Pick<
 InferInsertModel<typeof emailVerificationsTable>,
 "requestedEmail" | "hashedToken" | "userId" | "expiresAt"
>;

@injectable()
export class EmailVerificationsRepository implements Repository {
 constructor(
  @inject(DatabaseProvider) private readonly db: DatabaseProvider
 ) {}

 // creates a new email verification record or updates an existing one
 async create(data: CreateEmailVerification) {
  return this.db
   .insert(emailVerificationsTable)
   .values(data)
   .onConflictDoUpdate({
    target: emailVerificationsTable.userId,
    set: data,
   })
   .returning()
   .then(takeFirstOrThrow);
 }

 // finds a valid record by token and userId
 async findValidRecord(userId: string) {
  return this.db
   .select()
   .from(emailVerificationsTable)
   .where(
    and(
     eq(emailVerificationsTable.userId, userId),
     gte(emailVerificationsTable.expiresAt, new Date())
    )
   )
   .then(takeFirst);
 }

 async deleteById(id: string) {
  return this.db
   .delete(emailVerificationsTable)
   .where(eq(emailVerificationsTable.id, id));
 }

 trxHost(trx: DatabaseProvider) {
  return new EmailVerificationsRepository(trx);
 }
}

Email Verifications Table

The Email Verifications table will be used to store all the request of email verifications and also to store the tokens that we need to verify the email along the userId and email that performs the request.

import { createId } from "@paralleldrive/cuid2";
import { pgTable, text, timestamp } from "drizzle-orm/pg-core";
import { relations } from "drizzle-orm";
import { usersTable } from "./users.table";
import { timestamps } from "./utils";

export const emailVerificationsTable = pgTable("email_verifications", {
 id: text("id")
  .primaryKey()
  .$defaultFn(() => createId()),
 hashedToken: text("hashed_token").notNull(),
 userId: text("user_id")
  .notNull()
  .references(() => usersTable.id)
  .unique(),
 requestedEmail: text("requested_email").notNull(),
 expiresAt: timestamp("expires_at", {
  mode: "date",
  withTimezone: true,
 }).notNull(),
 ...timestamps,
});

export const emailVerificationsRelations = relations(
 emailVerificationsTable,
 ({ one }) => ({
   fields: [emailVerificationsTable.userId],
   references: [usersTable.id],
  }),
 })
);

Users Table

Since we are verifying the user email, we have to find a way to mark the user as selected, for this purpose we are gonna need a boolean field in the usersTable.

// ... all the imports
export const usersTable = pgTable("users", {
 id: text("id")
  .primaryKey()
  .$defaultFn(() => createId()),
 email: citext("email").notNull().unique(),
 password: text("password").notNull(),
 verified: boolean("verified").notNull().default(false), // flag to add
 ...timestamps,
});
// ...the rest of the code

and also update the relations:

export const usersRelations = relations(usersTable, ({ many, one }) => ({
 sessions: many(sessionsTable),
 emailVerifications: one(emailVerificationsTable, {
  fields: [usersTable.id],
  references: [emailVerificationsTable.userId],
 }),
}));

Forgot password, OTP code verification, Reset password

In addition to handling user authentication through access and refresh tokens, a robust authentication system must also provide mechanisms for users to recover access to their accounts. This is where the Forgot Password and Password Reset functionalities come into play. Let’s explore what these features entail and how they operate within the authentication flow.

What is it?

The Forgot Password and Password Reset system allows users to securely reset their passwords in case they forget them. This system typically involves the following steps:

• Forgot Password Request: Users initiate the password recovery process by providing their registered email address.
• OTP (One-Time Password) Verification: To ensure the request is legitimate, the system sends a one-time password (OTP) to the user's email, which they must verify.
• Password Reset: Once the OTP is validated, users can set a new password for their account.

These steps help maintain the security and integrity of user accounts by ensuring that only the rightful owner can reset the password.

How it works?

Implementing a secure password reset mechanism involves coordinated client-server interactions. Here’s an overview of the process:

1. Initiating Password Reset:

   • The user navigates to the "Forgot Password" section and submits their registered email address.
   • The client sends a POST request to the /forgotpassword endpoint with the user's email.
   • The server generates a unique password reset token, stores a hashed version of it in the database, and sends the token to the user's email via the MailerService.

2. Verifying the OTP:

   • Upon receiving the OTP in their email, the user enters it into the application.
   • The client sends a POST request to the /verify-token endpoint with the email and OTP.
   • The server validates the token by checking its existence, ensuring it hasn't expired, and verifying its correctness using the HashingService.
   • If the token is valid, the server responds with a success status, allowing the user to proceed to reset their password.

3. Resetting the Password: - The user enters a new password and confirms it. - The client sends a POST request to the /resetpassword/:token endpoint, including the new password and the token in the URL. - The server verifies the token again to ensure it's still valid. - Upon successful verification, the server updates the user's password in the database using the HashingService to securely hash the new password. - The server also invalidates any existing user sessions to prevent unauthorized access.

Defining routes

As usual we'll put the other routes inside the AuthController since this also those topic are parts of the bigger domain of the authentication.

// src/controllers/auth.controller.ts

// All the imports...

@injectable()
export class AuthController implements Controller {

 controller = new Hono<HonoTypes>();

 constructor(){
    @inject(AuthService) private readonly authService: AuthService,
    @inject(RefreshTokenService) private readonly refreshTokenService: RefreshTokenService,
    @inject(EmailVerificationsService) private readonly emailVerificationsService: EmailVerificationsService,
 }

 routes(){
     return this.controller
        // login, signup, refresh token and email verification routes...
 .post(
  "/forgotpassword",
  zValidator("json", passwordResetEmailDTO),
  limiter({ limit: 10, minutes: 60 }),
  async (context) => {
   const { email } = context.req.valid("json");
   await this.passwordResetService.createPasswordResetToken({
    email,
   });
   return context.json({ status: "success" });
  }
 )
 .post(
  "/verify-token",
  zValidator("json", passwordResetEmailVerificationDTO),
  limiter({ limit: 10, minutes: 60 }),
  async (context) => {
   const { email, token } = context.req.valid("json");
   await this.passwordResetService.validateToken(token, email);
   return context.json({ status: "success " });
  }
 )
 .post(
  "/resetpassword/:token",
  zValidator("json", passwordResetDTO),
  limiter({ limit: 10, minutes: 60 }),
  async (context) => {
   const body = context.req.valid("json");
   const token = context.req.param("token");
   await this.passwordResetService.resetPassword(token, body);
   return context.json({ status: "success" });
  }
 );
  }
}

The response I choose in this case are pretty basics, you can customize them as you want.

Password Reset DTO

This is the definitions of the DTOs for the password reset.

• For the passwordResetEmailDTO in the body of the request we just need the email that perform the request.
• in the passwordResetEmailVerificationDTO we need to pass both the email and the token, in this case the OTP code.
• lastly the passwordResetDTOis pretty much identical to the system used in the singUpDTO we just need to add the email.

Notice that in this case the client is passing the email at every request, this is due the fact that the server is not caching the email, but you can implement a system to do it if you want to avoid the client to pass the email at every request.

// src/dtos/password-reset.dto.ts

import { InferInsertModel } from "drizzle-orm";
import { z } from "zod";
import { passwordResetTable } from "../infrastructure/database/tables/password-reset.table";

export const passwordResetEmailDTO = z.object({
 email: z.string().email(),
});

export const passwordResetEmailVerificationDTO = z.object({
 email: z.string().email(),
 token: z.string().min(6).max(6),
});

export const passwordResetDTO = z
 .object({
  newPassword: z
   .string({ required_error: "required-password" })
   .min(8, "password-too-short")
   .max(32, "password-too-long"),
  confirmNewPassword: z
   .string({ required_error: "required-confirmation-password" })
   .min(8, "password-too-short")
   .max(32, "password-too-long"),
  email: z.string().email(),
 })
 .refine((data) => data.newPassword === data.confirmNewPassword, {
  message: "passwords-donot-match",
  path: ["passwordConfirmation"],
 });

export type ResetPasswordEmailDto = z.infer<typeof passwordResetEmailDTO>;
export type ResetEmailVerificationDTO = z.infer<
 typeof passwordResetEmailVerificationDTO
>;
export type ResetPasswordDto = z.infer<typeof passwordResetDTO>;
export type CreatePasswordResetRecord = Pick<
 InferInsertModel<typeof passwordResetTable>,
 "hashedToken" | "email" | "expiresAt"
>;

Password Reset Service

import { inject, injectable } from "tsyringe";
import { MailerService } from "./mailer.service";
import { HTTPException } from "hono/http-exception";
import { isWithinExpirationDate } from "oslo";
import { HashingService } from "./hashing.service";
import { TokensService } from "./token.service";
import { UsersRepository } from "../repositories/user.repository";
import { PasswordResetRepository } from "../repositories/password-reset.repository";
import { BadRequest, InternalError } from "../common/error";
import {
 ResetPasswordDTO,
 ResetPasswordEmailDTO,
} from "../dtos/password-reset.dto";

@injectable()
export class PasswordResetService {
 constructor(
  @inject(HashingService) private readonly hashingService: HashingService,
  @inject(TokensService) private readonly tokensService: TokensService,
  @inject(MailerService) private readonly mailerService: MailerService,
  @inject(UsersRepository) private readonly usersRepository: UsersRepository,
  @inject(PasswordResetRepository)
  private readonly passwordResetRepository: PasswordResetRepository
 ) {}

 async validateToken(token: string, email: string) {
  try {
   const record =
    await this.passwordResetRepository.findValidRecordByEmail(email);

   if (!record || !isWithinExpirationDate(record?.expiresAt)) {
    throw BadRequest("invalid-or-expired-token");
   }

   const isValidToken = await this.hashingService.verify(
    record?.hashedToken,
    token
   );

   if (!isValidToken) {
    throw BadRequest("invalid-or-expired-token");
   }

   return { status: "success" };
  } catch (e) {
   if (e instanceof HTTPException) {
    throw e;
   }
   throw InternalError("error-veryfing-token");
  }
 }

 async resetPassword(token: string, data: ResetPasswordDTO) {
  try {
   const record = await this.passwordResetRepository.findValidRecordByEmail(
    data.email
   );
   if (!record || !isWithinExpirationDate(record?.expiresAt)) {
    throw BadRequest("invalid-or-expired-token");
   }

   const isValidToken = await this.hashingService.verify(
    record?.hashedToken,
    token
   );

   if (!isValidToken) {
    throw BadRequest("invalid-or-expired-token");
   }
   const user = await this.usersRepository.findOneByEmail(data.email);

   if (!user) {
    throw BadRequest("no-user-with-this-email");
   }

   if (data.newPassword !== data.confirmNewPassword) {
    throw BadRequest("password-donot-match");
   }

   await this.passwordResetRepository.deleteById(record.id);

   const hashedPassword = await this.hashingService.hash(data.newPassword);

   await this.usersRepository.update(user.id, {
    password: hashedPassword,
   });
  } catch (e) {
   if (e instanceof HTTPException) {
    throw e;
   }
   throw InternalError("error-resetting-password");
  }
 }

 async createPasswordResetToken(data: ResetPasswordEmailDTO) {
  try {
   // generate a token, expiry and hash
   const { token, expiry, hashedToken } =
    await this.tokensService.generateTokenWithExpiryAndHash({
     number: 6,
     time: 15,
     lifespan: "m",
     type: "NUMBER",
    });
   const user = await this.usersRepository.findOneByEmail(data.email);

   if (!user) {
    throw BadRequest("no-user-with-this-email");
   }
   //if there is an existing record delete it
   await this.findRecordAndDelete(user.id);
   // create a new email verification record
   await this.passwordResetRepository.create({
    email: user.email,
    hashedToken: hashedToken,
    expiresAt: expiry,
   });

   this.mailerService.sendResetPasswordOTP({
    to: user.email,
    props: {
     otp: token,
    },
   });
  } catch (e) {
   if (e instanceof HTTPException) {
    throw e;
   }
   throw InternalError("error-creating-password-reset-token");
  }
 }

 async findRecordAndDelete(email: string) {
  const existingRecord =
   await this.passwordResetRepository.findValidRecordByEmail(email);
  if (existingRecord) {
   await this.passwordResetRepository.deleteById(existingRecord.id);
  }
 }
}

Password Reset Repository

import { inject, injectable } from "tsyringe";
import { and, eq, gte, lte, type InferInsertModel } from "drizzle-orm";
import type { Repository } from "../interfaces/repository.interface";
import { takeFirst, takeFirstOrThrow } from "../infrastructure/database/utils";
import { DatabaseProvider } from "../providers/database.provider";
import { passwordResetTable } from "../infrastructure/database/tables/password-reset.table";
import { CreatePasswordResetRecord } from "../dtos/password-reset.dto";

@injectable()
export class PasswordResetRepository implements Repository {
 constructor(
  @inject(DatabaseProvider) private readonly db: DatabaseProvider
 ) {}

 async create(data: CreatePasswordResetRecord) {
  return this.db
   .insert(passwordResetTable)
   .values(data)
   .onConflictDoUpdate({
    target: passwordResetTable.email,
    set: data,
   })
   .returning()
   .then(takeFirstOrThrow);
 }

 async findValidRecordByEmail(email: string) {
  return this.db
   .select()
   .from(passwordResetTable)
   .where(
    and(
     eq(passwordResetTable.email, email),
     gte(passwordResetTable.expiresAt, new Date())
    )
   )
   .then(takeFirst);
 }

 async deleteById(id: string) {
  return this.db
   .delete(passwordResetTable)
   .where(eq(passwordResetTable.id, id));
 }

 trxHost(trx: DatabaseProvider) {
  return new PasswordResetRepository(trx);
 }
}

<a name="conclusion"></a>

Conclusion

Building an authentication system with Hono and Drizzle is an essential step towards securing your web application while ensuring smooth user management. From implementing basic email/password authentication to advanced features like JWT-based authentication and password reset flows, this guide covered the key building blocks required for a robust authentication mechanism.

By following this guide, you’ve learned how to create a secure environment with the following functionalities:

• User Registration: Secure sign-up and validation of user data.
• Login and Session Management: Efficient handling of JWT access and refresh tokens.
• Password Management: Secure password storage and recovery options.
• Email Verification: Ensuring that users verify their emails before full access.
• Forgot Password: Giving users an easy way to reset their passwords through OTP-based verification.

All of this is achieved with well-defined routes, Zod validation, and database interactions using Drizzle ORM. The integration with Docker ensures a smooth development and production environment.

This architecture provides a clean, scalable solution that can be expanded further as your application grows.

What do to now?

Now that you've set up the foundational authentication system, it's time to take the following steps to further enhance your application:

1. Security Features:

• Two-Factor Authentication (2FA):
  • Authy: A popular app for TOTP-based 2FA that you can integrate into your system for an additional security layer.
  • Duo Security: A comprehensive 2FA solution for web and mobile apps with enterprise-grade features.

1. User Experience:

• Social Logins:
  • Auth0: A popular Identity-as-a-Service (IDaaS) provider that simplifies the integration of multiple social logins (Google, Facebook, GitHub, etc.) with easy-to-use SDKs.
  • Okta: A powerful identity provider offering social login, SSO (Single Sign-On), and multi-factor authentication (MFA) with easy integration.
• Custom Email Templates:
  • SendGrid: A robust email delivery service that offers customizable email templates and APIs to send transactional emails such as verification and password reset emails.
  • Mailgun: Provides an API for sending emails with advanced analytics and email template management.

1. Testing and Quality Assurance:

• Test Coverage:
  • SonarCloud: A code quality and coverage analysis tool that integrates with your CI/CD pipeline and ensures your authentication system is thoroughly tested.

1. Documentation:

• Swagger / OpenAPI:
  • SwaggerHub: A platform for designing, documenting, and testing your REST APIs. It offers a comprehensive interface for documenting your authentication API, and it can generate client libraries for different languages.
  • Redocly: Another popular OpenAPI-based API documentation tool with a more modern UI for end-users.

1. Monitor and Maintain:

• Error Monitoring:
  • Sentry: Provides real-time error tracking and performance monitoring, which can help you track down issues in your authentication routes (like invalid tokens or failed login attempts).
  • Rollbar: Another tool for tracking runtime errors and sending notifications for any unhandled exceptions or performance issues.
• Logs and Monitoring:
  • Datadog: Offers infrastructure monitoring, log management, and application performance monitoring (APM). You can track authentication issues, like slow login responses or downtime.
  • Loggly: A logging tool for aggregating, searching, and analyzing logs. It's useful for tracking authentication-related logs, such as failed login attempts or token generation events.

1. Scaling:

• Load Balancers:
  • AWS Elastic Load Balancing (ELB): Automatically distributes incoming application traffic across multiple instances, which helps scale the authentication system as your traffic increases.
  • Nginx: Can be used as a reverse proxy server for load balancing to distribute requests evenly across your application servers.

1. User Feedback and Monitoring:

• New Relic: Provides full-stack observability, including user interaction and API monitoring. It helps you track how users interact with your authentication system and whether there are any bottlenecks.
• Hotjar: Allows you to understand user behavior through heatmaps and session recordings. It helps identify where users are getting stuck during login or registration, making it easier to improve the flow.

1. CI/CD Integration:

• GitHub Actions: Can be used to automate testing, deployment, and continuous integration for your authentication system.
• CircleCI: Another CI/CD tool that allows you to automate your build, test, and deployment process for your authentication system.

By following these next steps, you can ensure your authentication system remains secure, user-friendly, and ready for scaling as your project grows. Keep iterating and improving based on feedback, and your users will have a secure and seamless experience.

Contributing

If you think you can add value to the project, please feel free to submit a pull request or open a issue.

Resources

The reference of the resources used in this guide.

• Architecture: Tofu Stack
• Framework HonoJs
• ORM: DrizzleORM
• Database: PostgreSQL
• Authentication Reference : The Copenhagen Book