DEV Community: Sacha Clerc-Renaud

Easy Animations for Architecture Diagrams

Sacha Clerc-Renaud — Fri, 17 Apr 2026 09:23:02 +0000

For years I wanted to create simple animations to illustrate technical architectures. But everytime I tried there was no tools that is free and easy to use that allows to animate simple diagrams.

There are some tools, but they are either too complex, not free, or a pain to use.

Because basically all I want is just moving some blocks and arrows to make my architecture diagram easier to understand.

This is where one of my co-worker showed me one of his Linked Post with a great animation. When I asked how he did this, Hhe told me "I just used Remotion and ask Claude to code the animation"

That's it!

Remotion is a tool that allows to create animation from react components. This is code. I know that pretty well.
But the best part is, I don't need to code the whole animation by myself. Claude can do the heavy lifting and I'll just fine tune the output. Also I don't care if the code is not clean. I just need this code until my video is exported.

This is so much faster than using After Effects or any other animation tools!

If you want to check out what it can do. I've created a small animation to explain the Outbox Pattern for Ontologic

Tell me in the comments if you already knew about this combo: Remotion + Claude

Modeling a domain with Ontologic Part 1: The Librarian’s Problems

Sacha Clerc-Renaud — Thu, 16 Apr 2026 09:42:19 +0000

This is the first article in a hands-on series about shaping a real-world kind of problem into code using Ontologic. Each article focuses on one main idea and points to the library-examples repo so you can read, run, and change the code yourself.

In this article we stay close to the problem: a small library moving off a paper register. We derive use cases and rules in plain language, spot Book and Loan as things with lifecycles, then model our first Domain Entity the Book.

From the librarian’s problem to modeling

Imagine you work with a small town library that still runs lending off a paper register. Staff write down who borrowed which book, when it is due, and when it came back. Searching the catalogue means walking the shelves or flipping a card file. They want to digitize that experience: one place to record copies, find books, and track loans.

We are not coding yet naming folders or installing packages. The goal is to notice, together, that the language of the business already points toward how we might model the system later.

What the app should help them do

If we listen to how they describe their day, we hear the Staff talking about Books, ISBN, Loans and Members. For our teaching project, we narrow that to a manageable set of use cases:

Add a book to their collection when new books arrive (title, author, ISBN, and so on).
Search for a book the collection when a library member asks for a book by title or author.
Lend a book to a member: record who has it, when the loan started, and when it is due back.
Return a book when the book comes back.
Mark a book as lost when it does not return and the library writes it off.
See what is still out for the whole register, or for one member (useful when someone asks, “What do I still have at home?”).

Those are use cases in everyday language: discrete jobs the software must support. We have not said “entity” or “database” yet.

Library's Business Rules

Paper or software, the library has policies. Some are obvious; some only come up when you speak enough with the librarian:

One book, one active loan. The same physical book cannot be on two open loans at once. If it is already out, you refuse or queue the request.
Lost books cannot be lended. A book marked lost is no longer lendable.
Borrowing limits. The library caps how many books someone may have at the same time. In our example repo that cap is three concurrent active loans per member.
Dates have to make sense on a loan. A due date should not be before the loan date; you cannot “return” before you borrowed. Those sound obvious but they are exactly the kind of detail that blows up a naive form if nobody encodes them.

When someone says, “The system must never allow X,” they are not describing a button, they are describing a rule that must hold no matter which screen or API triggered the action. In modeling terms, rules that must always be true for a given thing (or a given operation) are often talked about as invariants: properties and constraints we refuse to violate when we change state.

Listening for “things” that live and change

Read the use cases again and notice the nouns that are used.

A Book is added once, can be found, can be marked lost, and can be tied to a loan. It has a lifecycle: it exists over time, and its state (available, out, lost) matters.
A Loan is opened, then either closed by a return or left open until then.

When a concept has identity (“which book?”, “which loan?”) and state that evolves over its life, it is a strong candidate to model as an Entity.

By contrast, a member in our example repo stays thin: we only need an identifier (like a library card number) to know who borrowed. We are not modeling their address, fines, or reading history here. That keeps the example small; a real system might later promote “member” to its own entity with its own rules.

So far, discovered from the story: at least Book (one row per copy we track) and Loan as entities worth modeling explicitly.

Discovering structure in the rules

Some rules attach naturally to one of those things:

“This book is lost” belongs to the Book Entity .
“Due after loan date” belongs to the Loan Entity.

Others connect two things or the register as a whole:

“Not already on loan” ties a Book to open Loans.
“At most three active loans for this member” ties Loans to a member id and a count.

That split is useful later: Invariants often live on the entity they protect; Business Rules lives in a use case that coordinates several entities.

Modeling the book: start with state

We said a Book is something the library tracks over time. Before we talk about Ontologic or constructors, we write down what we need to remember about each book in the system: the catalogue fields staff already care about (title, author, ISBN, category, tags) and whether this book is lost or not. In TypeScript that becomes an interface BookState with those fields.

export interface BookState {
  title: string;
  author: string;
  isbn: string;
  category: string;
  tags: string[];
  lost: boolean;
}

Nothing clever yet: state is just the data we agree represents “a book as we know it right now.”

Turning state into a `DomainEntity`

Next we declare a class Book that extends DomainEntity<BookState>.
Ontologic gives us a simple way model to an Entity and encapsulate it's internal State.

import { DomainEntity } from "ontologic";

export class Book extends DomainEntity<BookState> {
  constructor(id: string, state: BookState) {
    super(id, state);
  }
}

At this point we have named the Entity and its State; we still need to decide how the outside world is allowed to change that state.

Creating an Entity

If you keep talking with the librarian, they might mention that they track how many books are added to the collection each month for reporting, budgets, or grants. That is a useful insight: introducing a new book is an interesting event for the business. In the model, this is what we call a domain event. In the code, BookCreatedEvent (see the class definition in the repo for the payload and BOOK_CREATED name).

So when we create a Book in the code, we must emit that event in the same move as building the entity. Anything that “adds a book” without producing the event could break the librarian’s monthly picture.

In JavaScript and TypeScript, a constructor cannot return anything other than the instance (or throw). The expression new Book(...) always evaluates to the Book object. You cannot type a constructor so callers get both the entity and its BookCreatedEvent from a single new.

You might try to stash the event in the entity's state (that's a path I've explored at some point) but it pollutes the state and requires developers to remember they need to go fetch the event from the state afterwards. I think it is more explicit if the entities methods directly returns a domain event as a consequence of a command/mutation. It makes it harder to forget.

A good solution to workaround this limitation of the constructor is to hide construction behind a private constructor: only methods inside the class may call new Book(...). We expose static create(...), which allocates id, builds initial state, constructs the book once, builds BookCreatedEvent, and returns both in one object—something the language allows for ordinary methods but not for new.

This technique also allows to name the creation logic with a domain term if there is one. Here I chose create for simplicity but we could go deeper in the domain modeling with something like Book.createNewBookToRegister().

import { randomUUID } from "node:crypto";
import { DomainEntity } from "ontologic";
import { BookCreatedEvent } from "./events/bookCreated.event";

export class Book extends DomainEntity<BookState> {
  private constructor(id: string, state: BookState) {
    super(id, state);
  }

  static create(state: Omit<BookState, "lost">): {
    book: Book;
    event: BookCreatedEvent;
  } {
    const id = randomUUID();
    const initialState: BookState = { ...state, lost: false };
    const event = new BookCreatedEvent(id, initialState);

    return {
      book: new Book(id, initialState),
      event,
    };
  }
}

Then in a use case the code looks like this:

const { book, event } = Book.create({
  title: "Clean Code",
  author: "Robert C. Martin",
  isbn: "9780134685991",
  category: "software",
  tags: ["craft"],
});

await libraryCollection.saveWithEvents(book, event);

So the private constructor is not secrecy for its own sake; it is a discipline: new books always go through create and always carry their creation event.

Notice that you can perfectly keep a classic constructor and not generate any domain event if your domains don't need to. Ontologic tries to give you the maximum freedom on How you do things.

Behavior: declaring a book lost

A useful first behavior is mark this book as lost. The business rule is simple: you cannot declare the same book lost twice.

Not every refusal is a bug or an error. A staff member might submit “declare lost” twice, or two desks might race the same request. The library’s answer “this book is already lost” is a normal, valid business outcome, not a crashed server or a programmer mistake. The code should represent that outcome on purpose, so callers can show a clear message, log it, or map it to an HTTP response later. Throwing an exception hoping that it will be properly handled so it does not crash the full application is very risky. When an action can "fail" for business reasons it must be part of the domain model and handled explicitly.

In Ontologic, a domain error is a small, typed value, typically a class extending DomainError with a stable name (for example BOOK_ALREADY_DECLARED_LOST), a message for people, and optional context (such as the book id). It lives in the domain layer; it is not an HTTP status and not a technical error. It says: the operation was rejected for a reason the business understands.

import { DomainError } from "ontologic";

export class BookAlreadyDeclaredLostError extends DomainError<
  "BOOK_ALREADY_DECLARED_LOST",
  { bookId: string }
> {
  constructor(bookId: string) {
    super({
      name: "BOOK_ALREADY_DECLARED_LOST",
      message: "This book has already been declared lost",
      context: { bookId },
    });
  }
}

To model both branches without throw/catch we use Result<Success, Failure> from Ontologic: either ok(successValue) or err(failureValue), where failureValue is usually a domain error. The type of the method documents both possibilities: success might carry a domain event. Failure carries BookAlreadyDeclaredLostError. Use cases and controllers can then branch on result.isOk() / result.isErr(). Also in JS/TS thrown errors are not typed. On the contrary by using the result pattern the error path is typed and you know exactly what kind of failure you're manipulating.

So declareLost returns a Result: on success we update state and hand back a BookLostEvent; on failure we hand back a domain error.

import { Result, err, ok, DomainEntity } from "ontologic";

export class Book extends DomainEntity<BookState> {
  constructor(id: string, state: BookState) {
    super(id, state);
  }

  declareLost(): Result<BookLostEvent, BookAlreadyDeclaredLostError> {
    const state = this.readState();

    if (state.lost) {
      return err(new BookAlreadyDeclaredLostError(this.id()));
    }

    this.state = { ...state, lost: true };

    return ok(new BookLostEvent(this.id()));
  }
}

Wrapping up

We started from a concrete situation and listed use cases and rules before naming entities Book and Loan.

Then we clarified where rules sit: invariants on one thing vs coordination in a use case.

For Book, we defined BookState, wrapped it in DomainEntity, and showed why adding a copy must produce a BookCreatedEvent

We've found a pattern with the private constructor + static create to use when the constructor wants to return more that just the Book object.

Finally we added the declareLost behavior, and introduced DomainError, and Result so expected failures stays in the model with typed errors, not untyped throws.

Let me know if this article was useful for you or not (all constructive feedbacks are welcome). And tell me if the next article around domain invariants would be interesting for you.

Where to see it in the repo

The Book entity that matches this walkthrough lives in src/domain/entities/book/book.entity.ts, with BookCreatedEvent and BookLostEvent under src/domain/entities/book/events/ and BookAlreadyDeclaredLostError in src/domain/entities/book/errors/book.errors.ts.

Meaningful Domain Models in TypeScript

Sacha Clerc-Renaud — Thu, 26 Mar 2026 13:23:32 +0000

Most bugs I've seen in production weren't caused by wrong algorithms or bad infrastructure. They were caused by invalid state — an order with no items, a paid order without an invoice ID, a payment that spent more than expected.

The code was syntactically correct. TypeScript was happy. But the business rules were silently violated.

This post explores a few patterns that help you build domain models that make invalid states impossible — and when something does go wrong, make failures explicit.

The problem with implicit rules

Consider a typical order entity:

class Order {
  status: "DRAFT" | "PLACED" | "PAID";
  items: OrderItem[];
  invoiceId?: string;
}

Nothing stops you from creating a PAID order with no invoiceId. Nothing stops you from removing the last item. The rules exist in your head (or a comment somewhere), not in the code.

You might add validation in one place — a use case, a controller — but nothing prevents another developer (or future you) from mutating state from a different path and bypassing it entirely.

Invariants: rules that are always true

An invariant is a business rule that must hold at all times, not just after specific operations.

Instead of validating in one place and hoping nothing else touches the state, you declare the rule once and it is checked every time state is read:

// This rule is always enforced — no matter how state was mutated
const paidOrderHasInvoiceId = new BaseDomainInvariant<OrderState>(
  "Paid Order Has Invoice Id",
  (state) => {
    if (state.status === "PAID") {
      return state.invoiceId !== undefined;
    }
    return true;
  }
);

The entity registers its invariants in the constructor:

class Order extends DomainEntity<OrderState> {
  private constructor(id: string, state: OrderState) {
    super(id, state);
    this.addInvariant(orderHasAtLeastOneItem);
    this.addInvariant(paidOrderHasInvoiceId);
  }
}

Any time you call order.readState(), the invariants are checked. If any is violated, it throws "Corrupted state detected". You can never silently read a broken entity.

Invariants are also composable:

const complexRule = invariantA.and(invariantB).or(invariantC);

Explicit failures with the Result pattern

TypeScript lets you throw anything, anywhere. But throw is invisible in function signatures — callers have no idea what can go wrong unless they read the implementation (or discover it in prod).

The Result pattern makes failures a first-class return value:

lockCredits(params: { amount: number }): Result<CreditLocked, NotEnoughFunds> {
  if (this.state.subCreditBalance < params.amount) {
    return err(new NotEnoughFunds(
      `Not enough credits`,
      { available: this.state.subCreditBalance, amount: params.amount }
    ));
  }

  this.state.lockedBalance += params.amount;
  return ok(new CreditLocked(this.id(), { amount: params.amount }));
}

The return type tells you everything: this operation either succeeds with a CreditLocked event, or fails with a NotEnoughFunds domain error. No surprise exceptions. The caller is forced to handle both cases:

const result = creditBalance.lockCredits({ amount: 100 });

if (result.isErr()) {
  // result.error is typed as NotEnoughFunds
  console.log(result.error.context.available);
} else {
  // result.value is typed as CreditLocked
  await repository.saveWithEvents(creditBalance, result.value);
}

Typed errors also carry structured context, not just a message string — making logging and debugging much more useful.

Domain events: immutable facts

Every state change produces an event — an immutable, versioned record of what happened:

export class OrderPaid extends DomainEvent<"ORDER_PAID", 1, { invoiceId: string }> {
  constructor(entityId: string, payload: { invoiceId: string }) {
    super({ name: "ORDER_PAID", version: 1, entityId, payload });
  }
}

Operations return their event:

pay(params: { invoiceId: string }): Result<OrderPaid, InvalidStatusTransition> {
  if (this.state.status !== "PLACED") {
    return err(new InvalidStatusTransition(...));
  }
  this.state.status = "PAID";
  this.state.invoiceId = params.invoiceId;
  return ok(new OrderPaid(this.id(), { invoiceId: params.invoiceId }));
}

You persist both the entity state and its events atomically:

const result = order.pay({ invoiceId: "INV-123" });
if (result.isOk()) {
  await repository.saveWithEvents(order, result.value);
}

This gives you a full audit trail with no extra effort. Events are also great for triggering side effects (emails, webhooks, projections) in a decoupled way.

Putting it together: a use case

Here's a complete payOrder use case that composes all these patterns:

export async function payOrderUseCase(
  repository: OrderRepository,
  id: string,
  invoiceId: string,
): Promise<Result<OrderState, InvalidStatusTransition | EntityNotFound>> {

  const getResult = await repository.getById(id);
  if (getResult.isErr()) throw getResult.error; // infra error, not domain

  const order = getResult.value;
  if (order === undefined) {
    return err(new EntityNotFound("Order not found", { entityId: id }));
  }

  const payResult = order.pay({ invoiceId });
  if (payResult.isErr()) return err(payResult.error);

  const saveResult = await repository.saveWithEvents(order, payResult.value);
  if (saveResult.isErr()) throw saveResult.error;

  return ok(order.readState());
}

Notice how each kind of failure is handled differently:

Infrastructure errors (DB down): throw — these are exceptional, not domain logic
Domain failures (wrong status): returned as typed Result — callers handle them

The library

All of these patterns are available in Ontologic — a small TypeScript toolkit that provides DomainEntity, BaseDomainInvariant, DomainEvent, DomainError, Result, and a Repository interface.

npm install ontologic

It doesn't try to be a framework — no decorators, no magic, no IoC container required. Just plain TypeScript classes and types that you can drop into any project.

Full docs and examples (including the Order and CreditBalance aggregates shown above) are at ontologic.site.

These patterns aren't new — they come from Domain-Driven Design and functional programming. But they're underused in TypeScript codebases, where it's easy to reach for throw and optional fields instead.

The payoff is code that reads like business rules, fails loudly when something is wrong, and makes it hard to put entities into states that shouldn't exist.

Outbox Pattern: Never lose an event anymore

Sacha Clerc-Renaud — Wed, 25 May 2022 15:37:29 +0000

Today I wanted to present you a pattern that allowed us to solved the problem when you need to update your database and publish an event in a consistent manner.

Let's see the context.

Start with the why

While building the Spendesk's core banking system, my team faced a problem.
We needed to persist modifications in our database and also publish an event into our event bus.

For example you want to increase an account's balance and emit an event that describe this change so the accounting part of the system can take it into account.

The problem is that if you update your database then call your event bus. You're taking the risk that your code crashes between the DB insert and the event publish.

This was not an option for us, in Banking you just can't lose an event. You need consistency. Also ordering is important you can't swap a debit and a credit event on an account. They need to be read or consumed in the same order they were processed.

To solve this problem we discovered the Outbox Pattern.

The Outbox Pattern

The principle is pretty simple:

You write your events in a dedicated database table.

Then a Message Relay service is reading this table and replicate your events into your event bus.

The benefits of doing this are that you can leverage database transactions to ensure that your state update and your events are persisted together. This way you cannot have one and not the other. It's always both or nothing.

The problem is that you need to implement a Message Relay system that is reliable enough to publish your events consistently. Let's see how we solved this issue.

Message Relay implementation

As for us our event ordering is important we chose Kafka as our event bus. One of the benefits of Kafka is the powerful Kafka Connect API and the multiple connectors that are available.

For our message relay we decided to use the Debezium Connector for Postgres.
This connector is directly using the database's Replication Slots to read the database's CDC (Change Data Capture). This allows the connector to publish the events almost in real time and in the exact same order as they were inserted in the database.

The advantages of using such a connector are:

Your services has no idea there is an event bus. It just writes events in a database. So your service is agnostic to your event technology.
It's easy to test. You don't need to run another docker or start your event bus to test your implementation. You can just verify that your event is correctly inserted in the database.
Debezium Connector is robust. It avoids you the caveat of implementing the complex Message Relay logic with all the challenges it brings:
- How do I recover from failures?
- How do I guarantee the ordering?
- How do I poll data from the database?
- etc...
Your services will keep working if the connector or event bus is down. Your events will keep pilling up until the connector or the event bus is back online.
You have an event history for free in your Postgres database in case you need to search something in the past.

I hope you learned something reading this article. Don't hesitate to tell me in a comment if you already knew this pattern before and what's your feedback on it if you've used it in production.

Decouple Your Application Layer

Sacha Clerc-Renaud — Sat, 30 Apr 2022 05:50:16 +0000

In the past, I used to work on some Nodejs projects where a lot of things were mixed: business logic, data layer, HTTP, route handlers, etc...

Most of the time presentation layer (HTTP) and the application layer were tightly coupled.

If you take an Express or Koa application, it's common to find business logic in middlewares and route handlers. It's ok if your app is small, there is no need to over-engineer simple things.

The problem with this is you are coupling your application layer to Express and HTTP. As your application grows and your use cases become more complex you start having trouble testing your routes handlers.

As Uncle Bob says "Web is a detail".

Start with the why

At Spendesk, we build microservices with four layers following Domain-Driven Design principles (If you are interested in DDD, you should read this great book by Eric Evans):

The domain layer contains your domain logic.
The application layer contains your business use cases.
The infrastructure layer provides data sources and repositories to persist your data.
The presentation layer exposes your application features to your end-user.

During our design phase, we tried to follow these layers structure. We built a piece of software called the dispatcher that takes a command object and executes it. This dispatcher finds the correct handler for the command and will return the result. This way the HTTP layer(presentation) is just transforming a HTTP payload into a command object and asking the dispatcher (application layer) to execute it.

We were really happy with this as it keeps our presentation layer really dumb with no business logic at all. Allowing us to have 2 differents presentation layers for our application because we need to expose it in two different ways to our users.

But, we had an issue. For legal reason we need to save every command our system receives. The problem with the dispatcher we implemented was that it only allows to register command handlers. A solution would have been for us to add code to save our commands in every handler. I was not really convinced it was a good idea, it creates code duplication and you can easily forget to add this piece of code.
So we started to create a wrapper around our command handlers that saves the command before calling the handler.
Honestly it was quite messy as we had to wrap all our handlers. I decided to improve the dispatcher by providing some pre and post hooks execution methods. It works fine, we can apply logic to all our commands handlers with these hooks.

const dispatcher = createDispatcher();

dispatcher.preExecute(saveCommand);
dispatcher.postExecute(saveCommandResult);

dispatcher.register('Command1', command1Handler);
dispatcher.register('Command2', command2Handler);

// etc...

But I was still thinking that I would really appreciate something more flexible, something as flexible as a middleware system like Express or Koa.

This is why, I decided to start a small personal side project to implement a small NPM package called DYAL (
Decouple Your Application Layer) that is basically an application layer with a middleware system.

The goals of DYAL are:

To make you focus on business logic and use cases.
Allow you to choose or change your presentation layer later.
Make your application easy to test.
Bonus: Allows you to implement CQRS pattern.

How does it work?

All examples in this article are available here

For this article, we will build an application module that manages a video game inventory.

The only business rule is:

The inventory can only contain three objects at the same time

Let's create our app:

import { createApp } from 'dyal';

export type GameObject = 'sword' | 'shield' | 'bow' | 'spear';

export type GameInventory = { items: GameObject[] };

export type AppDependencies = {
  inventory: GameInventory;
};

const gameInventoryApp = createApp<AppDependencies>({
  inventory: { items: [] },
});

gameInventoryApp.use(addItemMiddleware); // Command
gameInventoryApp.use(removeItemMiddleware); // Command
gameInventoryApp.use(inspectContentMiddleware); // Query

Our application allows three different actions:

Add an item -> state changes, it's a command
Remove an item -> state changes, it's a command
Inspect our inventory content -> read the state, it's a query

If you are familiar with Express or Koa you have spotted that DYAL replicates the middleware stack feature with app.use(). The difference is those middlewares are not handling HTTP requests but UseCase objects that you will define according to your business use cases. A UseCase is either a Command or a Query object depending on if it modifies or reads your application state.

Now let's take a look at our addItemMiddleware that will handle a Command as it modifies our application state:

import { UseCase, Context, Next } from 'dyal';

import { AppDependencies, GameObject } from '..';

export interface AddItemCommand extends UseCase {
  type: 'command';
  name: 'AddItem';
  payload: {
    item: GameObject;
  };
}

export type AddItemResult = 'Inventory is full' | 'Item added';

type AddItemContext = Context<AppDependencies, AddItemCommand, AddItemResult>;

export async function addItemMiddleware(context: AddItemContext, next: Next) {
  const { inventory } = context.dependencies;
  const { useCase } = context;

  if (useCase.type === 'command' && useCase.name !== 'AddItem') {
    await next();
    return;
  }

  const { item } = useCase.payload;

  if (inventory.items.length >= 3) {
    context.result = 'Inventory is full';
    return;
  }

  inventory.items.push(item);

  context.result = 'Item added';
  return;
}

We can see with this implementation that we'll need to repeat this piece of code in all our middlewares:

if (useCase.type === 'command' && useCase.name !== 'AddItem') {
  await next();
  return;
}

That would be nice to have a way to automate that...
That's what I thought while implementing DYAL, so I did it.

DYAL provides CommandBus and QueryBus objects that route your commands and queries to the appropriate handler.
Let's migrate our application:

1   const gameInventoryApp = createApp<AppDependencies>({
2     inventory,
3   });
4
5   const commandBus = createCommandBus();
6   commandBus.register('AddItem', addItemHandler);
7   commandBus.register('RemoveItem', removeItemHandler);
8
9   gameInventoryApp.on('command').use(logger) // Will log only the commands.
10  gameInventoryApp.on('command').use(commandBus.middleware);
11
12  const queryBus = createQueryBus();
13  queryBus.register('InspectContent', inspectContentHandler);
14
15  gameInventoryApp.on('query').use(queryBus.middleware);

And the command handler :

export async function addItemHandler(
  context: AddItemContext,
): Promise<AddItemResult> {
  const { inventory } = context.dependencies;
  const { useCase } = context;

  const { item } = useCase.payload;

  if (inventory.items.length >= 3) {
    return 'Inventory is full'; // We don't write result in the context we return directly the expected result.
  }

  inventory.items.push(item);

  return 'Item added'; // We don't write the result in the context we return directly the expected result.
}

This example shows that you can have two different middleware stacks for commands and queries.

In the example above I added a logger only for the commands at line 9.
This could be interesting if, for example, you have specific needs on the command side that are not necessary on the query side like authentication, validation, etc...

This is at the core of the CQRS pattern and DYAL as a bonus allows you to implement it if you need.

What's the value?

Ok let's see if we've reached our goals:

1. To make you focus on business logic and use cases:

This piece of code seems pretty explicit to me. It is not coupled with any communication protocol. It's pure business modelization:

export interface AddItemCommand extends UseCase {
  type: 'command';
  name: 'AddItem';
  payload: {
    item: GameObject;
  };
}

// Notice that DYAL provides also utility types Command and Query
export interface RemoveItemCommand extends Command {
  name: 'RemoveItem';
  payload: {
    item: GameObject;
  };
}

export interface InspectContentQuery extends Query {
  name: 'InspectContent';
  payload: undefined;
}

2. Allows you to choose or change your presentation layer later:

Here is the diff if you decide to migrate from Express to Koa:

Nothing has changed in my application layer. My presentation layer is limited to its role: validating user's inputs, reshaping them into a UseCase object, asking the application layer to execute the command.

This allows you to test any presentation layer with your app. So you can determine which one is the best fit.
Also if one day the presentation framework you use is deprecated or unmaintained you can migrate to a more recent one.

3. Makes your application easy to test:

If I want to test my app I can easily instantiate the app and build command and query objects directly. No need to set up an HTTP server and perform HTTP requests to verify my code works.

You can guarantee that your application use cases works as expected independently from the network or the UI.

4. Bonus: Allows you to implement CQRS pattern:

This one is a bonus but as we've seen we can completely separate the middleware stack that is used for command and queries which is one of the core principles of CQRS.

Conclusion:

I think DYAL could be useful if you have a large application with a lot of business logic. Please don't use it to implement a CRUD API it would be over-engineered.

But if you need to implement complex business use cases and want to avoid being too dependent on a presentation framework. Or you just prefer to wait before choosing one. DYAL could be a great tool for you.

Don't hesitate to tell me in the comments if you've tried it or are using it for your application. The package is in version 1.0.9 while I'm writing those lines. Let me know if you find bugs or have feedback I'll be happy to make some evolutions.

Thanks for having read that far.

Happy coding!

Meaningful implementation for business rules

Sacha Clerc-Renaud — Thu, 31 Oct 2019 09:06:12 +0000

Recently at Spendesk we try to adopt a Domain Driven Design (DDD) approach. To better understand what it is I decided to read the reference book about it.

If you are already used to it or being evaluating using DDD, I recommend you to read it. There are very interesting principles in it. I will present one of them that I think can be very useful in some situations, the specification pattern.

Specification allow you to know if an object satisfies some conditions. This can be very useful to explicit in your code some business rules.

let's take a simple example : You work on an application for a car retailers and during a meeting with sales people you learned that in that company there is a discount on Ford and blue cars from Tesla.

The basic pattern:

The specification pattern looks like this:

const car = {
  color: 'blue',
  model: 'X',
  brand: 'Tesla',
};

isDiscountEligibleSpecification.isSatisfiedBy(car); // => true

For the purpose of this article I wrote a small implementation of the specification pattern available here on NPM

Let's see how to use it :

import { createSpec } from 'spoeck';

const car = {
  color: 'blue',
  model: 'X',
  brand: 'Tesla',
};

const isDiscountEligible = createSpec({
  isSatisfiedBy: (car): boolean => {
    return (
      (car.color === 'blue' && car.brand === 'Tesla') || car.brand === 'Ford'
    );
  },
});

isDiscountEligible.isSatisfiedBy(car); // => true

Here the example is very basic and our code is not way better than creating a function dedicated to this check.

function checkDiscountAvailable(car) {
  return (
    (car.color === 'blue' && car.brand === 'Tesla') || car.brand === 'Ford'
  );
}

But this kind of functions tends to lives in a helper directory with a lot of other stuff and as it is not clearly identified some developers will not know it exist and as the rule is pretty simple, the code risk to be duplicated.

Specification allow to encapsulate business logic into identified objects that can be reused and composed (We will see that soon).

Use cases:

Validation:

The first use case that came to my mind when I discover this pattern was the validation one. It's easy to write code that might looks like this :

function applyDiscount(car) {
  if (!isDiscountEligible.isSatisfiedBy(car)) {
    throw new Error('Car is not eligible to discount');
  }
  ...
}

Selection:

The second one is the selection use case. When you want to filter over a collection:

const discounts = cars.filter((car) => isDiscountEligible.isSatisfiedBy(car));

This is working but in real life we often store our ressources in a database and use SQL requests to filter them. Filter all the cars from the database in memory is not a good idea as the number of rows could be huge. We will see later in this article how we can deal with specifications and databases.

Also what happen if you want to filter or validate 10 or even 1000 more rules?

Here come the composite pattern.

Composite pattern:

The real strength of specifications is when they are combined with the composite pattern.

A composite pattern is when an object is composed of objects that has the same type. In our case, our specifications will be composed by other specifications. This way we can combine them as building blocks to implement complexe business rules and avoid code duplication.

To combine them, specification object expose methods and or xor etc... and they are used like this : spec1.and(spec2) => composed_specification_1_AND_2

Let's use this with our car discount example :

const car = {
  color: 'blue',
  model: 'X',
  brand: 'Tesla',
};

const isBlue = createSpec(...);
const isFromTesla = createSpec(...);
const isFromFord = createSpec(...);

const isDiscountEligible = isFromFord.or(isFromTesla.and(isBlue));

isDiscountEligible.isSatisfiedBy(car); // => true

I dont know you, but it looks very elegant and readable to me. Being able to compose differents rules that your application can have in an extremely explicit manner is very valuable I think.

But...

This works well in memory. As said earlier filtering a huge collection from a database in memory is evil and SQL is here for that. Let's see how we can handle that.

Specifications and database storage:

There is multiple solutions to use databases with specifications that all have their pros and cons.

Expose request in specifications object:

You can add a method to your specification object to return the SQL query that fits your needs. And then pass it to your database access layer.

const isDiscountEligible = createSpec({
  isSatisfiedBy: (car): boolean => {
    return (
      (car.color === 'blue' && car.brand === 'Tesla') || car.brand === 'Ford'
    );
  },
  asSQL: () => {
    return `
      SELECT *
      FROM cars
      WHERE (color= 'blue' AND brand = 'Tesla')
      OR brand= 'Ford'`;
  },
});

This works but it tight couple our specification to our SQL storage which is not satisfying as SQL should be contained in our repository.

Use specialized repository methods:

If you're familiar with DDD you should know the repository pattern. If it's not the case basically a repository is an object that will abstract the storage technology for the client code. This way you never manipulate SQL or other query language outside the repository you just call methods that do it for you like getById() etc...

The second solution is to implement a method in our specification object that will call a specialized repository method that fit our needs.

const isDiscountEligible = createSpec({
  isSatisfiedBy: (car): boolean => {
    return (
      (car.color === 'blue' && car.brand === 'Tesla') || car.brand === 'Ford'
    );
  },
  satisfyingElementsFrom: async (carRepository) => {
    return await carRepository.getDiscountEligibleCars();
  },
});

This work fine, but it requires that you implement a specific method on the repository that will maybe be used only by your specification object.

Use generic repository methods:

This solution is similar to the previous one but we will use a more generic methods from the repository and finalize the selection in memory.

const isDiscountEligible = createSpec({
  isSatisfiedBy: (car): boolean => {
    return (
      (car.color === 'blue' && car.brand === 'Tesla') || car.brand === 'Ford'
    );
  },
  satisfyingElementsFrom: async (carRepository) => {
    const fordAndTeslaCars = await carRepository.getCarsByBrand([
      'Tesla',
      'Ford',
    ]);
    return fordAndTeslaCars.reduce((results, current) => {
      if (current.brand === 'Tesla' && current.color !== 'blue') {
        return results;
      }
      results.push(current);
    }, []);
  },
});

This present the advantage to use a generic repository function that can be used in multiple context. But there is a performance trade off as you have to filter the subset of rows in memory.

All these solutions are valid. But some are more adapted in certain situations. It's up to you to choose the right one for your needs.

Conclusion:

Pros:

Encapsulation: Keep business logic in a meaningful object (Avoid the helper directory).
Building blocks: Compose complex rules from other simpler rules.
Reusability: Composition of rules avoid code duplication.
Readability: Make the code more readable and expressive.
Adaptability: When your apllication requirements are changing. You can create or adapt new rules from previous one easily.

Cons:

Can be hard/impossible to implements combination when used against a DB.
Can be overengineered for small projects. The helper method may be enough.

Specification pattern is a powefull tools to modelize business rules and enforce them explicitly in the code in a reusable way. However if you have to deal with a database it is very hard to implement methods like and, or that can compose their database queries.

For me the real use case is for validating business rules and filtering on limited in memory collections.
In any case it's up to you to find the implementation that fits your needs.

Let me know in the comment what you think about this pattern. If you already use it how do you do to compose specifications with database queries ?

Dependency Injection in Koa app

Sacha Clerc-Renaud — Fri, 22 Mar 2019 10:43:32 +0000

Injecting dependencies can be very useful when you work on complex project. Here we will see how I use this pattern to make my tests easier to write and to be able to simulate some use cases that are complicated to reproduce in your tests like : DB failure, ECONNREFUSED error, etc...

This article is based on code samples from this repository : koa-template-samples. Himself based on the koa-template repository.

To implement the dependencies injection I use a small middleware called koa-depsi. You can look at his README.md file to see how it work.

I encourage you to clone the koa-template-samples repository to see the full source code of this example.

First we will see how to create our Koa app through a factory function.

// /lib/app.js

function createApp(dependencies = {}) {
  const app = new Koa()

  app.use(koadepsi(dependencies))

  app.use(todosRouter.routes())
  app.use(todosRouter.allowedMethods())
  return app
}

module.exports = createApp

full code here

This factory function allow us to create a Koa app on demand with different dependency injection. Will we see later that it will be very useful to write our tests.

Now look at the route handler createTodo.

// /lib/routes/todos/createTodo.js

const controller = require('../../controllers/todos')

async function createTodoHandler(ctx) {
  const dbClient = ctx.deps.dbClient
  const todo = await controller.createTodo(ctx.request.body, dbClient)

  ctx.status = 201
  ctx.body = todo
}

full code here

The route handler require the controller and get the connection to the database from the request context. It call the controller and pass the dbClient to the controller as an argument.

Note : It's possible to inject directly your controller into your routes if you prefer. You can implement this pattern as you like to use it.

Now we will look at the controller :

// /lib/controllers/todos/createTodo.js

async function createTodo(todoData, dbClient) {
  return await dbClient.query( todoData )
}

full code here

Here we see that the controller is completely decouple from the database. So if you pass a real dbCLient object the database will be called. But if you inject a fake dbClient you can completely control and simulate the values returned by the database.

Let's see a test example to better understand the advantages of this pattern:

// /tests/integrations/createTodo.test.js    

  it('Should return an error on database failure', async () => {
    const server = app({
      dbClient: {
        query: async () => {
          throw new Error('Database is down')
        },
      }, logger
    }).listen(config.app.port)

    const response = await request
      .post('http://localhost/todos')
      .send({ title: 'Lean Javascript' })
      .catch(err => err.response)

    server.close()

    assert.deepStrictEqual(response.body, {
      error: 'CREATE_TODO_ERROR',
      info: {
        done: false,
        priority: 0,
        title: 'Lean Javascript',
      },
      message: 'Something went wrong while inserting new todo: Database is down',
    }, 'Response body should be an error with error messages concatenated by verror module')
    assert.deepStrictEqual(response.status, 500, 'Status code should be 500')
  })

full code here

In this tests we want to verify that our code handle properly database error's. To simulate a database error we inject a fake dbCLient in the app. This fake dbCLient will throw new Error('Database is down') when you try to perform SQL query. This allow us to easily simulate any error that our database can throw.

Notice that the factory function to create the app is very useful. You can create a new app for each test you have to do and inject the real or fake dependencies according to your tests scenarios.

To summarize :

Create a factory function to create your Koa app.
Use koa-depsi to inject your dependencies on each request context.
Retrieve dependencies in your route from the request context.
Propagate theses dependencies to your controllers.
Inject fake or real dependencies in your tests according to your tests scenarios.

I hope this article will be useful for some of you. I encourage you to read the full code for this example here

Let me know if you like this testing recipe in the comments or if you have ideas to improve it. :-)

PS : English is not my native language. So let me know if you find some grammar mistakes.

Explicit error messages with VError

Sacha Clerc-Renaud — Thu, 21 Mar 2019 15:54:25 +0000

Today I will present you one of my favorite NPM modules. VError makes your errors more explicit.

I will not expose all the features here and just explain why I think this module is very useful. So don't hesitate to read the official documentation here

The thing I like with VError is the feature of building a composite error message through all applicative layers the error goes through.

Let see an example :

const VError = require('verror')

function model(json) {
  return JSON.parse(json)
}

function controller(json) {
  try {
    model(json)
  } catch (err) {
    const error = new VError(err, 'Model fail to parse json')
    throw error
  }
}

function routeHandler(rawJSON) {
  try {
    const data = controller(rawJSON)
    return data
  } catch (err) {
    const error = new VError(err, 'Controller fail to use json')
    throw error
  }
}

routeHandler('invalid json')

This script will generate the following error message :
VError: Controller fail to use json: Model fail to parse json: Unexpected token i in JSON at position 0

This is much more explicit to see than : SyntaxError: Unexpected token i in JSON at position 0

Also you can add some contextual information for each VError layers and get them at the end with the VError.info() function see documentation here

Examples :

const error = new VError({
  name: 'SERVICE_UNAVAILABLE',
  info: { json: rawJSON },
  cause: err,
}, 'Controller fail to use json')

console.log(VError.info(error)) // { json: 'invalid json' }
console.log(error.name) // SERVICE_UNAVAILABLE

Let me know in the comments if you use it already or if you will in the future and what are your feedbacks about VError.

DEV Community: Sacha Clerc-Renaud

Easy Animations for Architecture Diagrams

Modeling a domain with Ontologic Part 1: The Librarian’s Problems

From the librarian’s problem to modeling

What the app should help them do

Library's Business Rules

Listening for “things” that live and change

Discovering structure in the rules

Modeling the book: start with state

Turning state into a DomainEntity

Creating an Entity

Behavior: declaring a book lost

Wrapping up

Where to see it in the repo

Meaningful Domain Models in TypeScript

The problem with implicit rules

Invariants: rules that are always true

Explicit failures with the Result pattern

Domain events: immutable facts

Putting it together: a use case

The library

Outbox Pattern: Never lose an event anymore

Start with the why

The Outbox Pattern

Message Relay implementation

Decouple Your Application Layer

Start with the why

How does it work?

What's the value?

1. To make you focus on business logic and use cases:

2. Allows you to choose or change your presentation layer later:

3. Makes your application easy to test:

4. Bonus: Allows you to implement CQRS pattern:

Conclusion:

Meaningful implementation for business rules

The basic pattern:

Use cases:

Validation:

Selection:

Composite pattern:

Specifications and database storage:

Expose request in specifications object:

Use specialized repository methods:

Use generic repository methods:

Conclusion:

Pros:

Cons:

Dependency Injection in Koa app

Explicit error messages with VError

Turning state into a `DomainEntity`