This is a boilerplate to build REST APIs, Monolithic Modular and Microservice applications with Typescript.
The application aims to run Anywhere, Anytime, Anyhow. Dedicated servers, virtual machines, containers, EC2, ECS or lambdas, with Express, Fastify, Hyper-Express and serverless.
See it running as Fastify implementation at:
It is built over a simplistic interpretation of Hexagonal Architecture, the Domain Driven Design and Event Driven Architecture philosophies.
It aims to be as much agnostic as possible, avoiding to add any frameworks or libraries to the stack.
It can be used as boilerplate to create modular monolithor microservice applications.
It implements incoming data validation, in the infrastructure level, through custom logic and based in the Open API specification.
It implements basic HTTP auth mechanism with a custom role system. Replaceable with other auth mechanisms. Tied to the API OAS spec.
It implements a HTTP web server port actually implementing adapters for Express.js, Fastify and Hyper-Express. A serverless implementation is coming soon.
It implements an agnostic data repository port that actually writes/reads data from a In Memory database adapter. It is easily replaceable with Mongoose, Sequelize, etc.
Diagram illustrating the components:
https://miro.com/app/board/uXjVNq5nWJY=/?share_link_id=603404471489
The API doc might be visualized at: http://localhost:3000/doc/
Note: Remember to start the application before trying to reach it through the browser.
Request Handler -> Controller -> Domain Service -> Domain Use Case -> Data Repository -> Data Adapter -> DBClient
Request Handler <- Controller <- Domain Service <- Domain Use Case <- Data Repository <- Data Adapter <- DBClient
It is the entry point in a request to the service.
It is a infrastructure's component.
It performs params, body, url and access permission validations against the incoming request, using the associated OAS specification for each end point.
It may offers adapters for different outside service interfaces:
- HTTP - Lambdas (AWS, Azure, Google)
- HTTP - Express
- HTTP - Fastify
- HTTP - Hyper-Express
- HTTP - etc
- Events/SQS
- Events/SNS
- Events/etc
It is the entry point for the application core (domains).
It is a domain's component.
May works as aggregation root / bounded contexts talking directly to injected domain services (aka domains and subdomains).
It should be the unique option working as communication interface between infrastructure and domain components.
It has a databaseClient adapter and a mutexClient adapter injected on it instance.
It may lock resources to avoid race conditions by using the injected mutexClient.
It knows it internal domain use cases.
It doesn't knows external domain use cases.
The Use Cases, as the meaning of the words, are the use cases implemented in the Product.
They represents the features delivered to the customers.
It is a domain's component. They known and are consumed by the Domain Service component only.
They are the point entry for all Data Repository calls. They handle Data Models rather than raw objects.
They have an associated Data Repository that is injected into it scope when calling Use Case clojure.
The Data Repository layer implements, in a agnostic manner, all actions related to the data persistency.
It does not talk directly to a database. I has a port to adapt different Database Clients.
It is a domain's component. They are consumed by Use Case component only.
The Data adapter is a kind of database client implementation that respect the Data Repository port.
It may implement database access through native drivers or ORMs and ODMs.
It is a domain's component.
- Node.js (20 preferred)
- Typescript
- Jest
- Redis - used to implement mutex (included as Docker image)
- OpenAPI official typings
- yaml - yaml parser
- Express
- Install the project
npm install- Run Redis (if you don't have already)
npm run docker:composeredis npm testRun with Express
npm run dev:fastifyRun with Fastify
npm run dev:fastify- Reach the URL http://localhost:3000/doc/ and click in the
Version 1.0.0. It will open the API documentation. - Reach http://localhost:3000/docs/1.0.0 to see the JSON version of the API documentation.
- Create a new branch.
Run the app in TDD mode - live reload of tests
npm run tdd- Make your changes.
- Commit it
- Ask for PR
lint code
npm run lintlint && fix code
npm run lint:fixcommit
It will run lint and test before asking info about the commit
npm run commitCommiting code
Commit messages must follow the Angular Commit Message Guidelines
It generates a changelog following the Commitizen conventional changelog