Clean Architecture in TypeScript, enforced.

Two sides, many contexts

Your business lives in bounded contexts: messages, orders, billing. Each context is a folder, on the side of the backend or of the frontend, and holds the same four layers. The kernel finds the contexts by their di.ts: there is nothing to register.

The two sides are two projects that share nothing but the HTTP API. A context never imports another context of its side, and never the routes: the dependencies always point inward.

Four layers, one direction

Ports and their contracts

This is the hexagonal architecture, also called ports and adapters. The domain declares what it needs as a port: an interface, and a token with the same name. The infra gives it adapters: one for production, one in memory for the tests. di.ts binds each port to its production adapter; test.di.ts binds it to the in-memory adapter or the fake.

/** The messages that the app keeps. */
export interface MessageRepository {
  /** An id that no message has yet. */
  nextId(): Promise<string>;
  /** The messages, in the order they were added. */
  list(): Promise<Message[]>;
  find(id: string): Promise<Message | undefined>;
  /** Adds the message, or replaces the message that has its id. */
  save(message: Message): Promise<void>;
  /** Removes the message that has this id. An id that no message has changes nothing. */
  remove(id: string): Promise<void>;
}

export const MessageRepository = new Token<MessageRepository>();

Next to each port, a contract says what every adapter must do: give a new id each time, list the messages in their order, replace a message with the same id. The test of each adapter runs it. The fake of your tests and the real adapter pass the same contract, so a test that passes in memory tells the truth about production.

// in-memory-message-repository.test.ts: the adapter of the tests
describeMessageRepositoryContract("InMemory", async () => new InMemoryMessageRepository());

// file-message-repository.test.ts: the adapter of production
describeMessageRepositoryContract("File", async () =>
  new FileMessageRepository(join(await freshDirectory(), "not-made-yet"), "messages.json"));

How a request flows

A new message of the example app, from the click to the file. Each step is one small file, in its layer. The answer goes back the same way.

1. MessageBoard.markoFrontend presentation

   The view publishes MessageAdditionRequested.

2. messagesStore.tsFrontend presentation

   The store turns the event into an AddMessageCommand.

3. add-message.handler.tsFrontend application

   The handler calls the MessagesGateway port.

4. http-messages-gateway.tsFrontend infra

   The adapter posts the text to /api/messages.

5. routes/_backend/api/messagesRoute

   The route gives the request to the controller.

6. add-message-http.controller.tsBackend presentation

   The controller sends an AddMessageCommand.

7. add-message.handler.tsBackend application

   The handler asks the domain, then the MessageRepository port.

8. Message.tsBackend domain

   The entity refuses an empty text, or one that is too long.

9. file-message-repository.tsBackend infra

   The adapter keeps the message in a JSON file.

Follow the whole path, drawn step by step, on each side →

Small files, one shape

A use case of the example app, and its test. Every use case has this shape, so you, your teammates and your agent always know where to look. The handler gets its port from the container; the test uses the in-memory adapter, through test.di.ts.

export class AddMessageHandler {
  constructor(private readonly messages: MessageRepository) {}

  async execute(command: AddMessageCommand): Promise<AddMessageOutput> {
    const message = Message.create(await this.messages.nextId(), command.text);
    await this.messages.save(message);
    return new AddMessageOutput(message.id, message.text);
  }
}

const kept = async (app: TestApplication) => (await app.get(MessageRepository).list()).map(({ id, text }) => [id, text]);

describe("add message", () => {
  test("keeps the text without the spaces around it, under a new id, and answers with the message", async ({ app }) => {
    await applicationScenario(app)
      .givenTheDto(new AddMessageCommand("  Hello  "))
      .expectTheOutputToBe(new AddMessageOutput("message-1", "Hello"));

    expect(await kept(app)).toEqual([["message-1", "Hello"]]);
  });

  // … each message gets an id of its own; a text of the maximum length is accepted

  test.for([
    ["", "A message cannot be empty."],
    ["   ", "A message cannot be empty."],
    ["x".repeat(Message.MAX_LENGTH + 1), "A message has at most 280 characters."]
  ])("the domain refuses %j, and keeps nothing", async ([text, reason], { app }) => {
    await applicationScenario(app)
      .givenTheDto(new AddMessageCommand(text))
      .expectTheErrorToBe(new InvalidMessageError(reason));

    expect(await kept(app)).toEqual([]);
  });
});

A test for each layer

Each layer has its kind of test, and CAITS gives each layer its test helper. The end-to-end tests run Playwright, set up for you. No mocking library: the tests use the in-memory adapters, which pass the same contracts as the real ones.

The 52 rules

npm run check checks each rule on src/ and test/, at every run. A rule that breaks names the file, the import when there is one, and the rule. Here they are, as CAITS 0.5 checks them.

Make the rules yours

The rules are code, in quality/architecture.mjs, a file of your project. It starts from CAITS's rules: remove one, replace one, or add your own. Your file has the last word, and npx caits update never changes it.

import { rules } from "./caits/architecture.mjs";

export default rules.filter(rule => rule.name !== "routes-folders");

import { rules } from "./caits/architecture.mjs";

const noLodashInDomain = {
  name: "no-lodash-in-domain",
  description: "The domain does not import lodash.",
  on: "import",
  check: ({ from, specifier }) => from.layer === "domain"
    && specifier.startsWith("lodash") && "the domain does not import lodash"
};

export default [...rules, noLodashInDomain];

Write a test for your rule in quality/*.test.mjs: npm test runs it with the others. All the tools that you can tune →