Forem: Sacha Clerc-Renaud

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.