DEV Community: Vıɔk A Hıƃnıʇɐ C.

Realmente no conoces la POO, el calefactor si♨️

Vıɔk A Hıƃnıʇɐ C. — Fri, 20 Feb 2026 15:31:00 +0000

En un bosque encantado, donde la lógica y la magia bailaban de la mano, existía una Caja Mágica. Dentro de ella, reinaba un caos ordenado de objetos, cada uno con una identidad única, un estado de ánimo y un comportamiento muy particular. Cada objeto conocía su propósito en la vida, pero era incapaz de realizar una función compleja por sí solo. Eran una comunidad de almas simples en busca de un objetivo común. ❄️

En un gélido día de invierno, cuando el frío calaba hasta los huesos de madera de la caja, la Resistencia, un objeto con el don de generar calor, se dio cuenta de una verdad fundamental: su don era inútil sin el poder de la energía. Entonces, la Batería, una fuente de vida rebosante de electrones mágicos, se ofreció a ayudar. Con un gesto de generosidad, le concedió a la Resistencia la capacidad de heredar ⬇️ su energía. La Resistencia, ahora alimentada, comenzó a brillar con un tenue calor rojizo. Pero pronto surgió un nuevo problema: el calor se acumulaba y no había quien lo dispersara por el ambiente.

El Ventilador, un objeto soñador y con aspas inquietas, se ofreció como voluntario. Sin embargo, para moverse y esparcir ese preciado calor, él también necesitaba heredar ⬇️ la energía de la Batería. La Batería, con su espíritu colaborador, aceptó. Juntos, estos tres objetos decidieron unir sus fuerzas y crear una nueva entidad, una clase más grande y poderosa a la que llamaron "Calefactor". 🏭

Pero al activar el sistema, reinó la confusión. El Ventilador no se movía. Estaba quieto, mudo. 🔇 Tras una rápida investigación, descubrieron el problema: la funcionalidad de poder que la Batería había otorgado directamente no servía para el Ventilador. La Resistencia funcionaba felizmente con Corriente Continua (CC), la esencia misma de la Batería. Pero el Ventilador, de diseño más complejo, necesitaba Corriente Alterna (CA) para hacer girar su motor. Era un conflicto de identidades.

La Batería, sabia y flexible, ideó una solución brillante. Decidió no dar su energía directamente, sino implementar un contrato, un «Interfaz» 🤝, una promesa de suministrar energía. A través de este acuerdo, cada objeto podría polimorfizarse 🎭, es decir, tomar la forma de energía que necesitaba. La Resistencia interpretó la energía del interfaz como CC y siguió calentándose. El Ventilador la interpretó como CA y, con un suspiro de alivio, comenzó a girar, esparciendo el calor por toda la Caja Mágica. ¡El polimorfismo había salvado el día!

Todo funcionaba a la perfección, pero el Calefactor, la clase de mayor rango, notó algo inquietante. Podía sentir el calor ambiente, pero no sabía a qué temperatura exacta estaba trabajando la Resistencia. Preocupado, le preguntó:

—Resistencia, ¿a qué temperatura estás? Necesito controlar tu estado para evitar un sobrecalentamiento.

La Resistencia, con un deje de orgullo en su voz metálica, respondió:

—Lo siento, señor. Mi temperatura es un asunto privado, un detalle de mi diseño. Lo tengo todo encapsulado 📦. Puedes disfrutar del calor que produzco, pero no puedes manipular mi termostato interno.

El Calefactor, sorprendido, reflexionó:
—Entiendo la necesidad de privacidad, la encapsulación protege tu integridad. Pero yo puedo ver y regular la velocidad del Ventilador. Para cumplir mi función de mantener un clima agradable, necesito la misma capacidad contigo. Necesito una interfaz pública para controlar tu temperatura.

La Resistencia comprendió. La protección no debía ser un muro que impidiera la colaboración, sino una puerta con llave. Decidió, entonces, exponer sus propiedades encapsuladas de forma controlada, creando métodos públicos para que el Calefactor pudiera leer y ajustar su temperatura de manera segura, sin violar su integridad interna. El Calefactor, ahora con el control total, pudo regular el sistema con maestría, logrando la temperatura perfecta. ⚖️

La paz y el calor reinaron por horas, hasta que, de repente, un escalofrío recorrió la Caja Mágica. La Batería, que había dado todo de sí, emitió un último destello y se agotó por completo. El agotamiento era total. Las cosas se ponían muy, muy frías. 🥶

Pero cuando la esperanza comenzaba a congelarse, un objeto que todos habían olvidado cobró vida: el Enchufe Eléctrico 🔌, que hasta entonces había permanecido inactivo, congelado en un rincón. Con un chasquido, ofreció su ayuda.

—Yo puedo proporcionarles energía ilimitada desde la gran red del castillo —zumbó con energía—. Pero necesito que el sistema se adapte.

El Calefactor, intrigado, preguntó cómo era posible. El Enchufe explicó el concepto de la abstracción 🏛️:

—Yo no necesito saber cómo funcionan internamente la Resistencia o el Ventilador. Solo necesito que el Calefactor, la clase que los engloba, entienda que puede recibir poder a través de mí. Yo seré la nueva fuente. Mi complejidad (el voltaje, el tipo de corriente de la red) queda oculta para ustedes. Solo expongo la acción «entregarEnergia()».

El Calefactor entendió a la perfección. Implementó la funcionalidad de poder a través del Enchufe, quien envió un torrente de energía que reanimó a la Batería. El ciclo de la vida (y del calor) podía continuar. Gracias a la abstracción, los objetos se comunicaban sin necesidad de conocer los complejos secretos internos de los demás. 🔄

Y así, la Resistencia (con su estado encapsulado pero controlado), el Ventilador (con su polimorfismo energético), la Batería (con su herencia de poder) y el Enchufe (con su gran abstracción), todos unidos bajo la clase del Calefactor, lograron sobrevivir al crudo invierno, creando un ambiente de temperatura perfecta y estable. La Caja Mágica se convirtió en el hogar más acogedor de todo el bosque. 🤩

Detalle de los conceptos mágicos 🚀

En términos de los hechizos de la Programación Orientada a Objetos, la historia ilustra a la perfección sus cuatro pilares fundamentales:

Encapsulación 📦: La Resistencia mantuvo su temperatura como un secreto de estado interno, protegido del exterior. Solo cuando fue necesario y de forma controlada (a través de métodos públicos «get» y «set»), expuso esta información, permitiendo la interacción sin comprometer su integridad. Es la protección de datos.
Herencia ⬇️: La Resistencia y el Ventilador recibieron (heredaron) la capacidad de tener energía de la Batería. Al formar parte de la clase Calefactor, también heredaron el contexto y el objetivo común de generar y dispersar calor.
Polimorfismo 🎭: La Batería definió un contrato (Interfaz) para suministrar energía. La Resistencia y el Ventilador implementaron ese contrato de maneras completamente diferentes (CC vs. CA), respondiendo al mismo mensaje ("toma mi energía") de forma única. Un mismo interfaz, múltiples comportamientos.
Abstracción 🏛️: La clase Calefactor representa una idea general, ocultando la complejidad de sus partes. El Enchufe, por su parte, es el ejemplo perfecto: esconde los complejos detalles de la red eléctrica y solo presenta una operación simple («entregarEnergia») que cualquier clase puede usar sin entender su funcionamiento interno.

En resumen, esta historia del Calefactor POO es un viaje encantado para comprender las ideas clave de la programación orientada a objetos. Al dotarla de un tono más mágico y narrativo, se vuelve más atractiva para todos los públicos, transformando conceptos abstractos en personajes con vida propia. Esperamos que esta aventura inspire a más personas a aprender sobre POO y a mejorar sus habilidades para crear sus propios mundos mágicos de código. 😎🚀

Y entonces, cuando todo parecía perfecto, un rayo de luz atravesó la Caja Mágica. Se oyeron unas voces conocidas a lo lejos... "¡Yo soy el vengador de la noche!"... "¡Es la hora de la furia cósmica!"... ¡Habían llegado Batman y los Power Rangers! Y... ¡continuará! 🤣

Professional Testing Experience in Golang

Vıɔk A Hıƃnıʇɐ C. — Fri, 19 Dec 2025 23:31:23 +0000

During my first year with Golang, I developed a complete development stack that finally satisfies me. The process took approximately two months of exploration and continuous refinement. However, it wasn't easy to reach this point, as I had to overcome several challenges, and one of the biggest was unit testing and the mocking pattern in Go.

In my professional experience, I've worked with various languages such as C, C++, Java, VB, C#, JavaScript, and TypeScript, and I miss some features from these languages when writing tests in Go. One thing that strikes me most is that while in languages with mocking frameworks (like Jest in JavaScript or NSubstitute in C#) creating a stub/mock is more straightforward (one-liners), in Go, due to its statically-typed nature and the absence of dynamic runtime reflection, you need to generate code that explicitly implements each interface you want to mock.

This characteristic makes tests in Go more verbose initially, although safer at compile-time. Sometimes it leads to tests looking messy if you don't follow a good development strategy. However, I never lost hope of finding a way to make tests cleaner and more maintainable in Go.

For example, in TypeScript with jest-mock-extended, creating a stub is as simple as:

// contracts
interface UserRepository {
  getById(id: string): Promise<{ id: string; name: string, superPower: string }>;
}

// test file
import { mock } from "jest-mock-extended";

// Create a stub
const userRepository = mock<UserRepository>();

// Define the behavior of the mock method
userRepository.getById.mockResolvedValue({ id: "unique-user-id", name: "John Doe", superPower: "Invisibility" });

// Example usage
const user = await userRepository.getById("unique-user-id");
console.log(user.name); // "John Doe"

And if we want to verify that a method was called with certain parameters (mock):

// Verify that the method was called with the expected ID
expect(userRepository.getById).toHaveBeenCalledWith("unique-user-id");

My Experience with testify/mock

At the organization where I collaborate, the testing stack used testify/mock. During the first three weeks working with this library, I identified that, although it's very popular and has many features, mock setup can be verbose, especially when configuring multiple expectations. While there are tools like mockery (a code generator that creates mocks using testify/mock internally) and recent versions have improved significantly, the usage pattern based on strings and runtime assertions didn't align with my preference for compile-time safety.

Limitations Found

After working with testify/mock, I identified the following aspects that didn't align with my preferences:

Limited type safety: Use of strings for method names and mock.Anything that postpones errors to runtime
Refactoring: When renaming interface methods, tests continue compiling giving false positives
IDE autocomplete: Limited due to string usage and generic types
Compile-time verification: Personal preference for detecting errors at compilation

This led me to propose improvements through a PR that included:

Type-safe method call verification
Better IDE autocomplete support
Compile-time validation of mock expectations

Although the PR added type-safety through generics, it wasn't accepted due to philosophical differences because apparently testify prioritizes simplicity and stable API over type-safety, while my proposal added generic complexity that, although technically valid, didn't align with the project's direction. This decision helped me understand that different projects have different valid trade-offs.

My Solution: Modern Architecture-Focused Testing Stack

Seeing that I needed a solution more suited to my needs for a new project, I decided to create my own stack from scratch, based on:

Hexagonal Architecture with DDD

cmd/                     # Entry point for applications (Apis, Functions)
src/
├── application/         # Business logic layer
│   ├── contracts/       # Interface definitions (ports)
│   ├── mocks/           # Mock implementations for domain (using builder pattern) 
│   ├── services/        # Application services
│   ├── shared/          # Shared application utilities
│   └── useCases/        # Use case implementations (by context and dtos)
├── domain/              # Domain entities and business rules
├── infrastructure/      # External adapters and implementations
│   ├── config/          # Project setup and settings
│   ├── controllers/     # HTTP API controllers
│   ├── core/            # Infrastructure core utilities (app, crun, http, openapi, web)
│   ├── db/              # Database connections and migrations
│   ├── handlers/        # Cloud Run/Cloud Functions handlers
│   ├── providers/       # Service implementations (adapters)
│   └── repositories/    # Data access implementations

Advantages of this architecture for testing:

Interfaces are well-defined in application/contracts/
Use cases are easy to test in isolation
Adapters can be easily mocked
Domain logic is free from external dependencies

GCP Deployment Strategy

The project supports two deployment strategies under the same codebase:

Cloud Run (containerized services): For stateful services, WebSockets, or those requiring greater control over the runtime
Cloud Functions (serverless): For event-driven functions, asynchronous processing, or simple endpoints

Example main.go for API Cloud Run Service:

package main

func main() {
    app := app.AppInstance // App instance based on Web framework

    // Register controllers (Controllers by context in microservices architecture strategy)
    loadControllers()
    // Or for monolithic
    // controllers.Index()

    if err := app.Setup(); err != nil {
        fmt.Fprintf(os.Stderr, "Failed to setup server: %v\n", err)
        os.Exit(1)
    }

    // WebSocket configuration for real-time features (Using Gorilla WebSocket)
    app.UseWebSockets(
        []string{"GET", "POST", "PUT", "DELETE", "PATCH"},
        infraConfig.WEB_SOCKET_SERVER_PATH,
    )

    port := appSharedSettings.AppSettingsInstance().PORT
    app.Listen(port)
}

Technology Stack

For project development, I selected the following technologies:

API Framework

Instead of Gin, I selected Web for:

Superior performance (benchmarks)
Reduced footprint
Minimalist philosophy that promotes best practices and separation of concerns

Personally, I opted to have a copy of the framework within the project adapted to my specific needs, and what was in the project's philosophy I shared as improvement proposals to the original repository.

I contributed improvements to the project:

PR #1: Query improvements
PR #12: Resource Management improvements

Dependency Management

For DI I implemented a thread-safe container pattern based on:

Use of interfaces to decouple implementations
Singleton pattern for shared instances
Lazy initialization to optimize startup time

Real-time & Notifications

Gorilla WebSocket: Stable and well-maintained WebSocket protocol

To use WebSockets with the Web framework, I needed to modify the framework's Request Context to facilitate WebSocket support and operation in a simpler and cleaner way.

Swagger / OpenAPI

For API documentation, instead of swaggo (which uses comment annotations), I implemented dynamic OpenAPI spec generation:

Stack:

kin-openapi: Library to manipulate OpenAPI 3.1 specs
Swagger UI: Web interface (static resources)

Implementation:

// Generate OpenAPI spec from route registry
func (app *App) GenerateOpenAPISpec(serverHost string) error {
  wd, err := os.Getwd()
  if err != nil {
    return fmt.Errorf("failed to get working directory: %w", err)
  }

  port := appSharedSettings.AppSettingsInstance().PORT
  routes := openApi.GetRoutesRegistry().GetRoutes()
  generator := openApi.CreateDocumentation(
    serverHost, 
    port, 
    app.ApiRootPath, 
    openApi.CreateDocumentInfo(infraConfig.ApiDocInfoInstance), 
    routes,
  )

  generator.AddServerUrl("/", "Current server")

  outputPath := filepath.Join(wd, "../../openapi.json")
  generator.SaveApiDoc("", outputPath)

  generator.Finish()

  app.logger.LogInfo("OpenAPI documentation generated successfully")
  return nil
}

Advantages:

✅ Doesn't depend on comments (DRY principle)
✅ Type changes automatically reflect in the spec
✅ Supports OpenAPI 3.1 (most recent)
✅ Generation using reflection from route definitions (Only at Application startup)
✅ Full control over the generation process

Input Validations

I use the DTO pattern with Ozzo Validation for contextual validations:

// DTOs with explicit validations per use case
type CreateUserDTO struct {
    Name       string
    Email      string
    Age        int
    SuperPower string
}

func (dto CreateUserDTO) Validate() error {
    return validation.ValidateStruct(dto,
        validation.Field(&dto.Name, validation.Required, validation.Length(3, 50)),
        validation.Field(&dto.Email, validation.Required, is.Email),
        validation.Field(&dto.Age, validation.Required, validation.Min(18)),
        validation.Field(&dto.SuperPower, validation.Required),
    )
}

type UpdateUserDTO struct {
    Name  *string // Optional in update
    Email *string
}

func (dto UpdateUserDTO) Validate() error {
    return validation.ValidateStruct(&dto,
        validation.Field(&dto.Name, validation.Length(3, 50)),
        validation.Field(&dto.Email, is.Email),
    )
}

Advantages:

✅ Contextual validations (Create vs Update have different rules)
✅ Clear separation: validation in DTO, logic in domain
✅ Declarative and testable validations
✅ Doesn't pollute domain model with validation tags
✅ Handled from application layer, not from infrastructure

ORM / Database

GORM: Mature ORM with support for multiple databases

Testing Stack: The Solution (Finally)

After evaluating various options and experiments with different combinations, I arrived at a solution that adapts to my personal preferences and project needs. The final combination includes:

Result Pattern for Response Handling

Before showing the tests, it's important to understand the Result[T] pattern I use to unify use case responses:

// application/shared/result.go
package shared

type Result[T any] struct {
    data    T
    err     error
    success bool
}

func NewResult[T any]() *Result[T] {
    return &Result[T]{}
}

func (r *Result[T]) SetData(data T) *Result[T] {
    r.data = data
    r.success = true
    return r
}

func (r *Result[T]) SetError(err error) *Result[T] {
    r.err = err
    r.success = false
    return r
}

func (r *Result[T]) IsSuccessful() bool { return r.success }
func (r *Result[T]) GetData() T { return r.data }
func (r *Result[T]) GetError() error { return r.err }
func (r *Result[T]) GetErrorMessage() string {
    if r.err != nil {
        return r.err.Error()
    }
    return ""
}

Advantages:

✅ Explicit success/error handling
✅ Type-safe for return data
✅ Facilitates testing (verify success flag)
✅ Avoids nil pointer panic
✅ Fluent API for construction

Now, let's see how tests look using this pattern along with generated mocks.

1. Counterfeiter for Mock Generation

Counterfeiter automatically generates mocks from interfaces:

# Generate mocks for all interfaces in contracts/
go generate ./...

Advantages over testify/mock:

✅ Type-safe by default
✅ Clean and readable generated code
✅ Complete IDE autocomplete
✅ Compilation fails if interface changes
✅ Built-in spy pattern to verify calls

2. Minimalist Assertion Library

Assert for simple and expressive assertions:

assert.True(t, result.IsSuccessful())
assert.Equal(t, expected, actual)
assert.Contains(t, slice, item)

3. Generic Factory for Mocks

I implemented a factory pattern using generics to simplify mock creation:

// contractsfakes/factory.go
package contractsfakes

import "sync"

type fakeContainer struct {
    Logger FakeLoggerProvider
    // Other shared fakes...
}

var (
    FakeContainer *fakeContainer
    initOnce      sync.Once
)

func init() {
    initOnce.Do(func() {
        FakeContainer = &fakeContainer{
            Logger: FakeLoggerProvider{},
        }
    })
}

// Get returns a new instance of fake type T
func Get[T any]() *T {
    return new(T)
}

Advantages:

✅ Type-safe fake creation
✅ Centralized management for shared fakes
✅ Simple and straightforward

Complete Test Example

Tests combine interface mocks (counterfeiter) with domain builders to create clean and expressive tests:

// getUserById_test.go
func TestErrorGettingUserByIdWithInvalidId(t *testing.T) {
    t.Parallel()

    // Arrange
    invalidID := "" // Empty ID
    errorMessage := "user id cannot be empty"

    fakeUserRepository := contractsfakes.Get[contractsfakes.FakeUserRepository]()
    fakeUserRepository.GetByIdReturns(nil, errors.New(errorMessage))

    logger := contractsfakes.FakeContainer.Logger
    useCase := NewGetUserByIdUseCase(logger, fakeUserRepository)

    // Act
    result := useCase.Execute(context.Background(), sharedLocales.LOCAL_EN_US, invalidID)

    // Assert
    assert.False(t, result.IsSuccessful())
    assert.Equal(t, errorMessage, result.GetErrorMessage())

    // Verify mock was called with invalid ID
    assert.Equal(t, 1, fakeUserRepository.GetByIdCallCount())
    _, actualID := fakeUserRepository.GetByIdArgsForCall(0)
    assert.Equal(t, invalidID, actualID)
}

func TestSuccessGettingUserById(t *testing.T) {
    t.Parallel()

    // Arrange
    userID := "user-123"
    expectedUser := mocks.NewUserBuilder().
        WithId(userID).
        WithName("John Doe").
        WithSuperPower("Invisibility").
        Build()

    fakeUserRepository := contractsfakes.Get[contractsfakes.FakeUserRepository]()
    fakeUserRepository.GetByIdReturns(expectedUser, nil)

    logger := contractsfakes.FakeContainer.Logger
    useCase := NewGetUserByIdUseCase(logger, fakeUserRepository)

    // Act
    result := useCase.Execute(context.Background(), sharedLocales.LOCAL_EN_US, userID)

    // Assert
    assert.True(t, result.IsSuccessful())

    user := result.GetData()
    assert.Equal(t, "user-123", user.ID)
    assert.Equal(t, "John Doe", user.Name)
    assert.Equal(t, "Invisibility", user.SuperPower)
}

func TestCreateUser_MultipleScenarios(t *testing.T) {
    t.Parallel()

    tests := []struct {
        name          string
        userBuilder   *mocks.UserMockBuilder
        repoError     error
        expectedOK    bool
        expectedError string
    }{
        {
            name: "success creating user",
            userBuilder: mocks.NewUserBuilder().
                WithId("user-456").
                WithName("Jane Smith").
                WithSuperPower("Telekinesis"),
            repoError:  nil,
            expectedOK: true,
        },
        {
            name: "error creating user without name",
            userBuilder: mocks.NewUserBuilder().
                WithId("user-789").
                WithSuperPower("Flight"),
            repoError:     errors.New("name is required"),
            expectedOK:    false,
            expectedError: "name is required",
        },
    }

    for _, tt := range tests {
        tt := tt // capture range variable
        t.Run(tt.name, func(t *testing.T) {
            t.Parallel()

            // Arrange
            user := tt.userBuilder.Build()

            fakeUserRepository := contractsfakes.Get[contractsfakes.FakeUserRepository]()
            fakeUserRepository.CreateReturns(tt.repoError)

            logger := contractsfakes.FakeContainer.Logger
            useCase := NewCreateUserUseCase(logger, fakeUserRepository)

            // Act
            result := useCase.Execute(context.Background(), sharedLocales.LOCAL_EN_US, user)

            // Assert
            assert.Equal(t, tt.expectedOK, result.IsSuccessful())

            if !tt.expectedOK {
                assert.Equal(t, tt.expectedError, result.GetErrorMessage())
            }

            // Verify repository interaction
            assert.Equal(t, 1, fakeUserRepository.CreateCallCount())
        })
    }
}

// Test cleanup to ensure test isolation
func TestMain(m *testing.M) {
    // Setup before tests (if needed)
    setup()

    // Run tests
    code := m.Run()

    // Cleanup after tests
    cleanup()

    os.Exit(code)
}

func setup() {
    // Common initialization if needed
}

func cleanup() {
    // Reset shared state if needed
    contractsfakes.FakeContainer = nil
}

Advantages of this combination:

✅ Interface mocks (counterfeiter): For port/adapter behavior
✅ Domain builders: To build entity state in a fluent and readable way
✅ Clear separation: Business logic in domain, I/O behavior in mocks
✅ Expressive tests: Builder pattern makes test code self-documenting

Implemented Best Practices

Test Isolation: Each test uses t.Parallel() for concurrent execution
AAA Pattern: Arrange-Act-Assert clearly separated
Mock Verification: Verify not only results but also interactions
Table-Driven Tests for multiple cases

Results

Test execution time: entire suite with parallelization by default
Type Safety: 100% of mock-related errors caught at compile-time
Maintainability: Interface changes detected at compile-time
Developer experience: significant reduction in test setup code lines

When to Consider testify/mock

Despite my choice of counterfeiter for this project, testify/mock remains an excellent option in many scenarios:

Advantages of testify/mock:

Adoption and Ecosystem:
- More GitHub stars than counterfeiter (This is community)
- Greater amount of examples, tutorials, and Stack Overflow content
- Better support in large teams with personnel rotation
Advanced Matchers (⚠️ Code Smell):

testify/mock allows complex matchers with logic:

   mockRepo.On("Get", 
       mock.MatchedBy(func(ctx context.Context) bool {
           deadline, ok := ctx.Deadline()
           return ok && time.Until(deadline) > time.Second
       }),
       "user-123",
   ).Return(&User{}, nil)

However, this is an architectural antipattern. If you need to validate complex logic in a mock, it's a signal that may indicate:

❌ Business logic is in the wrong place
❌ Your interface (port) is doing too much
❌ Single Responsibility Principle violation

Correct design: Mocks should be dumb stubs (input → output). Logic should live in the domain:

   // ✅ Logic in domain, not in mock
   type RequestValidator struct {
       minTimeout time.Duration
   }

   func (v *RequestValidator) ValidateContext(ctx context.Context) error {
       deadline, ok := ctx.Deadline()
       if !ok || time.Until(deadline) < v.minTimeout {
           return ErrInvalidTimeout
       }
       return nil
   }

   // ✅ Simple repository mock
   fakeRepo.GetReturns(&User{}, nil)

Behavior Verification:

   // Specific assertions about interactions
   mockRepo.AssertNumberOfCalls(t, "Get", 3)
   mockRepo.AssertCalled(t, "Update", mock.Anything, expectedUser)
   mockRepo.AssertExpectations(t) // Verify all expectations

Mockery v2.20+ with Expecters (partial improvement):

Mockery is a code generator that creates mocks using testify/mock internally. Since v2.20+, with --with-expecter=true it generates additional type-safe code:

   // Code generated by mockery with --with-expecter=true
   mockRepo.EXPECT().Get(mock.Anything, "123").Return(&User{}, nil)

Advantages over traditional testify/mock:

✅ Type-safety in method names (safe refactoring)
✅ Better IDE autocomplete
✅ No reflection overhead (code generated at compile-time)

Limitations that persist:

❌ Still requires mock.Anything for variable arguments
❌ No compile-time verification of argument types
❌ No compile-time verification of return types

It's an intermediate step between traditional testify/mock and counterfeiter, but doesn't completely resolve the type-safety problem that motivated my search for alternatives.

Runtime Flexibility:
- Useful for complex integration testing (Being careful not to mix domain logic in mocks)
- Simulation of race conditions
- Change behavior during test

Ideal use cases for testify/mock:

✅ Enterprise projects with large teams
✅ Behavior testing complex with multiple interactions
✅ Teams with prior experience in testify (organizational inertia)
✅ Projects that value API stability over strict type-safety
✅ Integration testing where call order verification is needed

⚠️ Note: If you find yourself frequently using complex matchers, consider evaluating whether your architecture respects the separation between ports (interfaces) and domain logic.

Why Complex Matchers Are Problematic

When you find yourself needing this:

// 🚩 RED FLAG: Business logic in the mock
mockValidator.On("Validate", mock.MatchedBy(func(u User) bool {
    return u.Age >= 18 && u.HasConsent && u.Country == "US"
})).Return(nil)

You're mixing responsibilities. Correct design separates:

// ✅ CORRECT: Logic in domain
type User struct {
    Age        int
    HasConsent bool
    Country    string
}

func (u User) CanPurchase() error {
    if u.Age < 18 {
        return ErrUnderage
    }
    if !u.HasConsent {
        return ErrNoConsent  
    }
    if u.Country != "US" {
        return ErrInvalidCountry
    }
    return nil
}

// ✅ Simple mock - only port behavior
fakeRepo.GetReturns(&User{Age: 25, HasConsent: true, Country: "US"}, nil)

// ✅ Separate domain test
func TestUser_CanPurchase(t *testing.T) {
    user := User{Age: 25, HasConsent: true, Country: "US"}
    assert.NoError(t, user.CanPurchase())
}

Fundamental principle:

Mocks model port behavior (interfaces), not domain logic.

This separation makes:

✅ Tests simpler and more readable
✅ Domain logic independently testable
✅ Mocks truly "dumb stubs"
✅ Refactoring safer
✅ Port And Adapters Architecture respected

My Choice: counterfeiter

For this specific project I chose counterfeiter because:

✅ Preference for compile-time safety
✅ Frequent interface refactoring
✅ Prioritization of IDE autocomplete and type-safety
✅ Enforces good design: Doesn't allow complex matchers (feature, not limitation)
✅ Clean interfaces following Ports And Adapters principles

The choice between testify/mock and counterfeiter is a valid architectural preference, not a right vs wrong decision. Both tools are excellent and the best option depends on the project context and team priorities.

Conclusions

This custom testing stack has proven effective for the specific needs of most of our new projects because it offers:

✅ Type-safe: Errors detected at compilation
✅ Maintainable: Interface changes automatically reflect in tests
✅ Clean: Readable and expressive test code
✅ Fast: Parallel test execution
✅ Scalable: Easy to add new tests following the same pattern

Lessons Learned

There's no one-size-fits-all solution: testify/mock and counterfeiter solve the same problem with different trade-offs
Context matters: The best tool depends on team size, experience, and project requirements
Type-safety vs Flexibility: It's a spectrum, not a dichotomy
Community matters: Sometimes it's worth sacrificing personal preferences for ecosystem adoption
Limitations can be features: The "impossibility" of creating complex matchers in counterfeiter enforces better architectural design
Simple mocks = Clean design: If your mocks are complex, your application probably has domain logic where it shouldn't be, and your domain obviously needs refactoring

The combination of counterfeiter + generic factory + minimalist assertions has resulted in a testing experience that fits my architectural preferences, maintaining the expressiveness necessary for clean tests. However, I recognize that testify/mock remains the industry standard for good reasons, and I would recommend evaluating both options according to the specific context of each project.

I hope this detailed explanation of my experience helps other developers make informed decisions about their testing stack in Go, but above all, to reflect on the importance of architectural design in the quality and maintainability of tests.

If you found this explanation useful, don't hesitate to share it with other developers who might benefit from these ideas and experiences, and I also invite you to share your own experiences and preferences in developing tests in Go because it's always valuable to learn from others' experiences.

Experiencia profesional de testing en Golang

Vıɔk A Hıƃnıʇɐ C. — Fri, 19 Dec 2025 23:26:20 +0000

Durante mi primer año con Golang, desarrollé un stack completo de desarrollo que finalmente me satisface. El proceso tomó aproximadamente dos meses de exploración y refinamiento continuo. Sin embargo, no fue fácil llegar a este punto, ya que tuve que superar varios retos y uno de los más grandes fue el tema de las pruebas unitarias (unit tests) y el patrón de mocking en Go.

En mi experiencia profesional he trabajado con varios lenguajes como C, C++, Java, VB, C#, JavaScript y TypeScript, y echo de menos algunas características de algunos de estos lenguajes cuando escribo tests en Go. Una de las cosas que más me llama la atención es que mientras en lenguajes con frameworks de mocking (como Jest en JavaScript o NSubstitute en C#) crear un stub/mock es más directo (cosas de una línea), en Go, debido a su naturaleza estáticamente tipada y la ausencia de reflection dinámico en runtime, se necesita generar código que implemente explícitamente cada interfaz que se quiere mockear.

Esta característica hace que los tests en Go sean más verbosos inicialmente, aunque más seguros en tiempo de compilación. A veces lleva a que los tests se vean desordenados si no se sigue una buena estrategia de desarrollo. Sin embargo, nunca perdí la esperanza de encontrar una forma de hacer tests más limpios y mantenibles en Go.

Por ejemplo, en TypeScript con jest-mock-extended, crear un stub es tan simple como:

// contracts
interface UserRepository {
  getById(id: string): Promise<{ id: string; name: string, superPower: string }>;
}

// test file
import { mock } from "jest-mock-extended";

// Create a stub
const userRepository = mock<UserRepository>();

// Define the behavior of the mock method
userRepository.getById.mockResolvedValue({ id: "unique-user-id", name: "John Doe", superPower: "Invisibility" });

// Example usage
const user = await userRepository.getById("unique-user-id");
console.log(user.name); // "John Doe"

Y si queremos verificar que un método fue llamado con ciertos parámetros (mock):

// Verify that the method was called with the expected ID
expect(userRepository.getById).toHaveBeenCalledWith("unique-user-id");

Mi experiencia con testify/mock

En la organización donde colaboro, el stack de testing utilizaba testify/mock. Durante las primeras tres semanas trabajando con esta librería, identifiqué que, aunque es muy popular y tiene muchas funcionalidades, el setup de mocks puede ser verboso, especialmente al configurar múltiples expectations. Si bien existen herramientas como mockery (un generador de código que crea mocks usando testify/mock internamente) y las versiones recientes han mejorado significativamente, el patrón de uso basado en strings y runtime assertions no se ajustaba a mi preferencia por compile-time safety.

Limitaciones encontradas

Después de estar trabajando con testify/mock, identifiqué los siguientes aspectos que no se alineaban con mis preferencias:

Type safety limitada: Uso de strings para nombres de métodos y mock.Anything que pospone errores a runtime
Refactorización: Al renombrar métodos de interfaces, los tests siguen compilando dando falsos positivos
Autocomplete en IDEs: Limitado debido al uso de strings y tipos genéricos
Verificación en compile-time: Preferencia personal por detectar errores en compilación

Esto me llevó a proponer mejoras mediante un PR que incluía:

Type-safe method call verification
Better IDE autocomplete support
Compile-time validation of mock expectations

Aunque el PR agregaba type-safety mediante generics, no fue aceptado debido a diferencias filosóficas porque al parecer testify prioriza simplicidad y API estable sobre type-safety, mientras mi propuesta añadía complejidad genérica que, si bien técnicamente es válida, no se alineaba con la dirección del proyecto. Esta decisión me ayudó a entender que diferentes proyectos tienen diferentes trade-offs válidos.

Mi solución: Stack moderno de testing enfocado en Arquitectura

Al ver que necesitaba una solución más adecuada a mis necesidades para un nuevo proyecto, decidí crear mi propio stack desde cero, basándome en:

Arquitectura Hexagonal con DDD

cmd/                     # Entry point for applications (Apis, Functions)
src/
├── application/         # Business logic layer
│   ├── contracts/       # Interface definitions (ports)
│   ├── mocks/           # Mock implementations for domain (using builder pattern) 
│   ├── services/        # Application services
│   ├── shared/          # Shared application utilities
│   └── useCases/        # Use case implementations (by context and dtos)
├── domain/              # Domain entities and business rules
├── infrastructure/      # External adapters and implementations
│   ├── config/          # Project setup and settings
│   ├── controllers/     # HTTP API controllers
│   ├── core/            # Infrastructure core utilities (app, crun, http, openapi, web)
│   ├── db/              # Database connections and migrations
│   ├── handlers/        # Cloud Run/Cloud Functions handlers
│   ├── providers/       # Service implementations (adapters)
│   └── repositories/    # Data access implementations

Ventajas de esta arquitectura para testing:

Las interfaces están bien definidas en application/contracts/
Los casos de uso son fáciles de probar en aislamiento
Los adapters pueden ser fácilmente mocked
La lógica de dominio está libre de dependencias externas

Estrategia de despliegue en GCP

El proyecto soporta dos estrategias de deployment bajo el mismo codebase:

Cloud Run (containerized services): Para servicios con estado, WebSockets o que requieren mayor control sobre el runtime
Cloud Functions (serverless): Para funciones event-driven, procesamiento asíncrono o endpoints simples

Ejemplo de main.go para API Cloud Run Service:

package main

func main() {
    app := app.AppInstance // App instance based on Web framework

    // Register controllers (Controllers by context in microservices architecture strategy)
    loadControllers()
    // Or for monolithic
    // controllers.Index()

    if err := app.Setup(); err != nil {
        fmt.Fprintf(os.Stderr, "Failed to setup server: %v\n", err)
        os.Exit(1)
    }

    // WebSocket configuration for real-time features (Using Gorilla WebSocket)
    app.UseWebSockets(
        []string{"GET", "POST", "PUT", "DELETE", "PATCH"},
        infraConfig.WEB_SOCKET_SERVER_PATH,
    )

    port := appSharedSettings.AppSettingsInstance().PORT
    app.Listen(port)
}

Stack tecnológico

Para el desarrollo del proyecto, seleccioné las siguientes tecnologías:

API Framework

En lugar de Gin, seleccioné Web por:

Performance superior (benchmarks)
Footprint reducido
Filosofía minimalista que promueve buenas prácticas y separación de responsabilidades

Personalmente opté por tener una copia del framework dentro del proyecto adaptada a mis necesidades específicas y lo que estaba en la filosofía del proyecto lo compartí como propuestas de mejora al repositorio original.

Contribuí con mejoras al proyecto:

PR #1: Mejoras en query
PR #12: Mejoras en administración de recursos

Gestión de dependencias

Para DI implementé un patron container thread-safe basado en:

Uso de interfaces para desacoplar implementaciones
Patrón Singleton para instancias compartidas
Lazy initialization para optimizar startup time

Real-time & Notificaciones

Gorilla WebSocket: Protocolo WebSocket estable y bien mantenido

Para poder usar Websockets con Web framework, tuve la necesidad de modificar el Request Context del framework para facilitar el soporte y operación de WebSockets de manera más sencilla y limpia.

Swagger / OpenAPI

Para documentación de API, en lugar de swaggo (que usa anotaciones en comentarios), implementé generación dinámica de OpenAPI specs:

Stack:

kin-openapi: Librería para manipular specs OpenAPI 3.1
Swagger UI: Interfaz web (recursos estáticos)

Implementación:

// Generate OpenAPI spec from route registry
func (app *App) GenerateOpenAPISpec(serverHost string) error {
  wd, err := os.Getwd()
  if err != nil {
    return fmt.Errorf("failed to get working directory: %w", err)
  }

  port := appSharedSettings.AppSettingsInstance().PORT
  routes := openApi.GetRoutesRegistry().GetRoutes()
  generator := openApi.CreateDocumentation(
    serverHost, 
    port, 
    app.ApiRootPath, 
    openApi.CreateDocumentInfo(infraConfig.ApiDocInfoInstance), 
    routes,
  )

  generator.AddServerUrl("/", "Current server")

  outputPath := filepath.Join(wd, "../../openapi.json")
  generator.SaveApiDoc("", outputPath)

  generator.Finish()

  app.logger.LogInfo("OpenAPI documentation generated successfully")
  return nil
}

Ventajas:

✅ No depende de comentarios (DRY principle)
✅ Cambios en tipos se reflejan automáticamente en la spec
✅ Soporta OpenAPI 3.1 (más reciente)
✅ Generación usando reflection desde definiciones de rutas (Sólo en el arranque de la Aplicación)
✅ Control total sobre el proceso de generación

Validaciones de entradas

Uso el patrón DTO con Ozzo Validation para validaciones contextuales:

// DTOs with explicit validations per use case
type CreateUserDTO struct {
    Name       string
    Email      string
    Age        int
    SuperPower string
}

func (dto CreateUserDTO) Validate() error {
    return validation.ValidateStruct(dto,
        validation.Field(&dto.Name, validation.Required, validation.Length(3, 50)),
        validation.Field(&dto.Email, validation.Required, is.Email),
        validation.Field(&dto.Age, validation.Required, validation.Min(18)),
        validation.Field(&dto.SuperPower, validation.Required),
    )
}

type UpdateUserDTO struct {
    Name  *string // Optional in update
    Email *string
}

func (dto UpdateUserDTO) Validate() error {
    return validation.ValidateStruct(&dto,
        validation.Field(&dto.Name, validation.Length(3, 50)),
        validation.Field(&dto.Email, is.Email),
    )
}

Ventajas:

✅ Validaciones contextuales (Create vs Update tienen reglas diferentes)
✅ Separación clara: validación en DTO, lógica en dominio
✅ Validaciones declarativas y testeables
✅ No poluta el modelo de dominio con tags de validación
✅ Manejadas desde la capa de aplicación, no desde infraestructura

ORM / Database

GORM: ORM maduro con soporte para múltiples bases de datos

Stack de Testing: La solución (finalmente)

Después de evaluar varias opciones y experimentos con diferentes combinaciones, llegué a una solución que se adapta a mis preferencias personales y necesidades del proyecto. La combinación final incluye:

Patrón Result para manejo de respuestas

Antes de mostrar los tests, es importante entender el patrón Result[T] que uso para unificar respuestas de use cases:

// application/shared/result.go
package shared

type Result[T any] struct {
    data    T
    err     error
    success bool
}

func NewResult[T any]() *Result[T] {
    return &Result[T]{}
}

func (r *Result[T]) SetData(data T) *Result[T] {
    r.data = data
    r.success = true
    return r
}

func (r *Result[T]) SetError(err error) *Result[T] {
    r.err = err
    r.success = false
    return r
}

func (r *Result[T]) IsSuccessful() bool { return r.success }
func (r *Result[T]) GetData() T { return r.data }
func (r *Result[T]) GetError() error { return r.err }
func (r *Result[T]) GetErrorMessage() string {
    if r.err != nil {
        return r.err.Error()
    }
    return ""
}

Ventajas:

✅ Manejo explícito de éxito/error
✅ Type-safe para datos de retorno
✅ Facilita testing (verificar success flag)
✅ Evita panic por nil pointer
✅ Fluent API para construcción

Ahora, veamos cómo se ven los tests usando este patrón junto con mocks generados.

1. Counterfeiter para generación de mocks

Counterfeiter genera mocks automáticamente desde interfaces:

# Generar mocks para todas las interfaces en contracts/
go generate ./...

Ventajas sobre testify/mock:

✅ Type-safe por defecto
✅ Código generado limpio y legible
✅ IDE autocomplete completo
✅ Compilación falla si la interfaz cambia
✅ Spy pattern built-in para verificar llamadas

2. Librería de aserciones minimalista

Assert para aserciones simples y expresivas:

assert.True(t, result.IsSuccessful())
assert.Equal(t, expected, actual)
assert.Contains(t, slice, item)

3. Factory genérico para mocks

Implementé un factory pattern usando generics para simplificar la creación de mocks:

// contractsfakes/factory.go
package contractsfakes

import "sync"

type fakeContainer struct {
    Logger FakeLoggerProvider
    // Other shared fakes...
}

var (
    FakeContainer *fakeContainer
    initOnce      sync.Once
)

func init() {
    initOnce.Do(func() {
        FakeContainer = &fakeContainer{
            Logger: FakeLoggerProvider{},
        }
    })
}

// Get returns a new instance of fake type T
func Get[T any]() *T {
    return new(T)
}

Ventajas:

✅ Type-safe creation de fakes
✅ Gestión centralizada para fakes compartidos
✅ Simple y directo

Ejemplo de test completo

Los tests combinan mocks de interfaces (counterfeiter) con builders de dominio para crear tests limpios y expresivos:

// getUserById_test.go
func TestErrorGettingUserByIdWithInvalidId(t *testing.T) {
    t.Parallel()

    // Arrange
    invalidID := "" // Empty ID
    errorMessage := "user id cannot be empty"

    fakeUserRepository := contractsfakes.Get[contractsfakes.FakeUserRepository]()
    fakeUserRepository.GetByIdReturns(nil, errors.New(errorMessage))

    logger := contractsfakes.FakeContainer.Logger
    useCase := NewGetUserByIdUseCase(logger, fakeUserRepository)

    // Act
    result := useCase.Execute(context.Background(), sharedLocales.LOCAL_EN_US, invalidID)

    // Assert
    assert.False(t, result.IsSuccessful())
    assert.Equal(t, errorMessage, result.GetErrorMessage())

    // Verify mock was called with invalid ID
    assert.Equal(t, 1, fakeUserRepository.GetByIdCallCount())
    _, actualID := fakeUserRepository.GetByIdArgsForCall(0)
    assert.Equal(t, invalidID, actualID)
}

func TestSuccessGettingUserById(t *testing.T) {
    t.Parallel()

    // Arrange
    userID := "user-123"
    expectedUser := mocks.NewUserBuilder().
        WithId(userID).
        WithName("John Doe").
        WithSuperPower("Invisibility").
        Build()

    fakeUserRepository := contractsfakes.Get[contractsfakes.FakeUserRepository]()
    fakeUserRepository.GetByIdReturns(expectedUser, nil)

    logger := contractsfakes.FakeContainer.Logger
    useCase := NewGetUserByIdUseCase(logger, fakeUserRepository)

    // Act
    result := useCase.Execute(context.Background(), sharedLocales.LOCAL_EN_US, userID)

    // Assert
    assert.True(t, result.IsSuccessful())

    user := result.GetData()
    assert.Equal(t, "user-123", user.ID)
    assert.Equal(t, "John Doe", user.Name)
    assert.Equal(t, "Invisibility", user.SuperPower)
}

func TestCreateUser_MultipleScenarios(t *testing.T) {
    t.Parallel()

    tests := []struct {
        name          string
        userBuilder   *mocks.UserMockBuilder
        repoError     error
        expectedOK    bool
        expectedError string
    }{
        {
            name: "success creating user",
            userBuilder: mocks.NewUserBuilder().
                WithId("user-456").
                WithName("Jane Smith").
                WithSuperPower("Telekinesis"),
            repoError:  nil,
            expectedOK: true,
        },
        {
            name: "error creating user without name",
            userBuilder: mocks.NewUserBuilder().
                WithId("user-789").
                WithSuperPower("Flight"),
            repoError:     errors.New("name is required"),
            expectedOK:    false,
            expectedError: "name is required",
        },
    }

    for _, tt := range tests {
        tt := tt // capture range variable
        t.Run(tt.name, func(t *testing.T) {
            t.Parallel()

            // Arrange
            user := tt.userBuilder.Build()

            fakeUserRepository := contractsfakes.Get[contractsfakes.FakeUserRepository]()
            fakeUserRepository.CreateReturns(tt.repoError)

            logger := contractsfakes.FakeContainer.Logger
            useCase := NewCreateUserUseCase(logger, fakeUserRepository)

            // Act
            result := useCase.Execute(context.Background(), sharedLocales.LOCAL_EN_US, user)

            // Assert
            assert.Equal(t, tt.expectedOK, result.IsSuccessful())

            if !tt.expectedOK {
                assert.Equal(t, tt.expectedError, result.GetErrorMessage())
            }

            // Verify repository interaction
            assert.Equal(t, 1, fakeUserRepository.CreateCallCount())
        })
    }
}

// Test cleanup to ensure test isolation
func TestMain(m *testing.M) {
    // Setup before tests (if needed)
    setup()

    // Run tests
    code := m.Run()

    // Cleanup after tests
    cleanup()

    os.Exit(code)
}

func setup() {
    // Common initialization if needed
}

func cleanup() {
    // Reset shared state if needed
    contractsfakes.FakeContainer = nil
}

Ventajas de esta combinación:

✅ Mocks de interfaces (counterfeiter): Para comportamiento de puertos/adapters
✅ Builders de dominio: Para construir estado de entidades de forma fluida y legible
✅ Separación clara: Lógica de negocio en dominio, comportamiento de I/O en mocks
✅ Tests expresivos: El builder pattern hace el código de test autodocumentado

Mejores prácticas implementadas

Test Isolation: Cada test usa t.Parallel() para ejecución concurrente
AAA Pattern: Arrange-Act-Assert claramente separado
Mock Verification: Verificar no solo resultados sino también interacciones
Table-Driven Tests para casos múltiples:

Resultados

Test execution time: suite con paralelización por defecto
Type Safety: 100% de errores relacionados a mocks detectados en compile-time
Mantenibilidad: Cambios en interfaces detectados en compile-time
Developer experience: Reducción significativa en líneas de código de setup de tests

Cuándo considerar testify/mock

A pesar de mi elección de counterfeiter para este proyecto, testify/mock sigue siendo una excelente opción en muchos escenarios:

Ventajas de testify/mock:

Adopción y Ecosistema:
- Más stars en GitHub que counterfeiter (Esto es comunidad)
- Mayor cantidad de ejemplos, tutoriales y Stack Overflow
- Mejor soporte en equipos grandes con rotación de personal
Matchers Avanzados (⚠️ Code Smell):
- testify/mock permite matchers complejos con lógica:

   mockRepo.On("Get", 
       mock.MatchedBy(func(ctx context.Context) bool {
           deadline, ok := ctx.Deadline()
           return ok && time.Until(deadline) > time.Second
       }),
       "user-123",
   ).Return(&User{}, nil)

Sin embargo, esto es un antipatrón arquitectural. Si necesitas validar lógica compleja en un mock, es una señal que puede indicar que:

❌ La lógica de negocio está en el lugar equivocado
❌ Tu interfaz (puerto) está haciendo demasiado
❌ Violación de Single Responsibility Principle

Diseño correcto: Los mocks deben ser dumb stubs (entrada → salida). La lógica debe vivir en el dominio:

   // ✅ Lógica en dominio, no en mock
   type RequestValidator struct {
       minTimeout time.Duration
   }

   func (v *RequestValidator) ValidateContext(ctx context.Context) error {
       deadline, ok := ctx.Deadline()
       if !ok || time.Until(deadline) < v.minTimeout {
           return ErrInvalidTimeout
       }
       return nil
   }

   // ✅ Mock simple del repositorio
   fakeRepo.GetReturns(&User{}, nil)

Verificación de Comportamiento:

   // Aserciones específicas sobre interacciones
   mockRepo.AssertNumberOfCalls(t, "Get", 3)
   mockRepo.AssertCalled(t, "Update", mock.Anything, expectedUser)
   mockRepo.AssertExpectations(t) // Verifica todas las expectations

Mockery v2.20+ con Expecters (mejora parcial):

Mockery es un generador de código que crea mocks usando testify/mock internamente. Desde v2.20+, con --with-expecter=true genera código adicional type-safe:

   // Code generated by mockery with --with-expecter=true
   mockRepo.EXPECT().Get(mock.Anything, "123").Return(&User{}, nil)

Ventajas sobre testify/mock tradicional:

✅ Type-safety en nombres de métodos (refactoring seguro)
✅ Mejor IDE autocomplete
✅ Sin overhead de reflection (código generado en compile-time)

Limitaciones que persisten:

❌ Aún requiere mock.Anything para argumentos variables
❌ No hay verificación de tipos de argumentos en compile-time
❌ No hay verificación de tipos de retorno en compile-time

Es un paso intermedio entre testify/mock tradicional y counterfeiter, pero no resuelve completamente el problema de type-safety que motivó mi búsqueda de alternativas.

Flexibilidad en Runtime:
- Útil para testing de integraciones complejas (Cuidando de no mezclar lógica de dominio en mocks)
- Simulación de condiciones race conditions
- Cambiar comportamiento durante el test

Casos de uso ideales para testify/mock:

✅ Proyectos enterprise con equipos grandes
✅ Testing de comportamiento complejo con múltiples interacciones
✅ Equipos con experiencia previa en testify (inercia organizacional)
✅ Proyectos que valoran estabilidad de API sobre type-safety estricto
✅ Testing de integraciones donde se necesita verificar orden de llamadas

⚠️ Nota: Si te encuentras usando matchers complejos frecuentemente, considera evaluar si tu arquitectura respeta la separación entre puertos (interfaces) y lógica de dominio.

Por qué los matchers complejos son problemáticos

Cuando te encuentras necesitando esto:

// 🚩 RED FLAG: Lógica de negocio en el mock
mockValidator.On("Validate", mock.MatchedBy(func(u User) bool {
    return u.Age >= 18 && u.HasConsent && u.Country == "US"
})).Return(nil)

Estás mezclando responsabilidades. El diseño correcto separa:

// ✅ CORRECTO: Lógica en dominio
type User struct {
    Age        int
    HasConsent bool
    Country    string
}

func (u User) CanPurchase() error {
    if u.Age < 18 {
        return ErrUnderage
    }
    if !u.HasConsent {
        return ErrNoConsent  
    }
    if u.Country != "US" {
        return ErrInvalidCountry
    }
    return nil
}

// ✅ Mock simple - solo comportamiento de puerto
fakeRepo.GetReturns(&User{Age: 25, HasConsent: true, Country: "US"}, nil)

// ✅ Test de dominio separado
func TestUser_CanPurchase(t *testing.T) {
    user := User{Age: 25, HasConsent: true, Country: "US"}
    assert.NoError(t, user.CanPurchase())
}

Principio fundamental:

Los mocks modelan comportamiento de puertos (interfaces), no lógica de dominio.

Esta separación hace que:

✅ Los tests sean más simples y legibles
✅ La lógica de dominio sea testeable independientemente
✅ Los mocks sean realmente "dumb stubs"
✅ El refactoring sea más seguro
✅ Se respete la Arquitectura de Port And Adapters

Mi elección: counterfeiter

Para este proyecto específico elegí counterfeiter porque:

✅ Preferencia por compile-time safety
✅ Refactoring frecuente de interfaces
✅ Priorización de IDE autocomplete y type-safety
✅ Fuerza buen diseño: No permite matchers complejos (feature, no limitación)
✅ Interfaces limpias siguiendo principios de Ports And Adapters

La elección entre testify/mock y counterfeiter es una preferencia arquitectónica válida, no una decisión de correcto vs incorrecto. Ambas herramientas son excelentes y la mejor opción depende del contexto del proyecto y las prioridades del equipo.

Conclusiones

Este stack de testing personalizado ha demostrado ser efectivo para las necesidades específicas de la mayoría de nuestros nuevos proyectos porque ofrece:

✅ Type-safe: Errores detectados en compilación
✅ Maintainable: Cambios en interfaces reflejan automáticamente en tests
✅ Clean: Código de test legible y expresivo
✅ Fast: Ejecución paralela de tests
✅ Scalable: Fácil agregar nuevos tests siguiendo el mismo patrón

Lecciones aprendidas

No hay solución única: testify/mock y counterfeiter resuelven el mismo problema con trade-offs diferentes
Context matters: La mejor herramienta depende del tamaño del equipo, experiencia y requisitos del proyecto
Type-safety vs Flexibilidad: Es un espectro, no una dicotomía
Comunidad importa: A veces vale la pena sacrificar preferencias personales por adopción del ecosistema
Las limitaciones pueden ser features: La "imposibilidad" de crear matchers complejos en counterfeiter fuerza mejor diseño arquitectural
Mocks simples = Diseño limpio: Si tus mocks son complejos, probablemente tu aplicación tiene lógica de dominio donde no debe estar y obviamente tu dominio necesita refactoring

La combinación de counterfeiter + factory genérico + aserciones minimalistas ha resultado en una experiencia de testing que se ajusta a mis preferencias arquitectónicas, manteniendo la expresividad necesaria para tests limpios. Sin embargo, reconozco que testify/mock sigue siendo la opción estándar de la industria por buenas razones, y recomendaría evaluar ambas opciones según el contexto específico de cada proyecto.

Espero que esta explicación detallada de mi experiencia ayude a otros desarrolladores a tomar decisiones informadas sobre su stack de testing en Go pero sobre todo a reflexionar sobre la importancia del diseño arquitectónico en la calidad y mantenibilidad de los tests.

Si te fue útil esta explicación, no dudes en compartirla con otros desarrolladores que puedan beneficiarse de estas ideas y experiencias, y también te invito a compartir tus propias experiencias y preferencias en el desarrollo de tests en Go porque siempre es valioso aprender de las experiencias de otros.

Scaling serverless development without losing health due to segregation 😎

Vıɔk A Hıƃnıʇɐ C. — Fri, 01 Sep 2023 18:29:43 +0000

Unveil the Secrets of Serverless Development in this short post. 🔍✨
Have you ever pondered over seemingly 'trivial' aspects of serverless applications, such as how to manage and scale such segregation in development without losing your sanity? 🤔

It's a question with multiple nuances, colors, and flavors...😊

And what if I told you there are ways to approach serverless development that emulate a monolithic project using a clean architecture framework, all while allowing the deployment of each function individually?

Imagine having complete control and the ability to scale without losing your sanity. 💡💪 Our latest research has led us to discover innovative approaches: practicing scaled development using the clean architecture structure and individually deploying each function—a fusion of the best of both worlds. 🏗️🌐

Curious to learn more? Don't miss the chance to see how you can achieve monolithic-like development efficiency along with the flexibility of serverless. Get ready for an enlightening small demo that will shift your perspective! 🎥

Unveiling the essence of Clean Architectures 🫣

Vıɔk A Hıƃnıʇɐ C. — Fri, 01 Sep 2023 13:58:30 +0000

In the world of software development, the term "Clean Architecture" is frequently discussed, yet its true essence often remains elusive. Let's demystify this concept and shed light on the fundamentals of clean architectures in a straightforward manner.

At its core, Clean Architecture is a software design approach that places a strong emphasis on separating concerns and achieving modular organization, with well-defined layers and responsibilities. The ultimate goal? Creating systems that are highly maintainable, scalable, and testable. Clean Architecture strives to keep source code clean, independent of frameworks and technologies, thus enabling seamless adaptability to changes and enhancements over time.

Within the realm of clean architectures, several distinctive approaches exist, each offering its own set of advantages and drawbacks. Among these approaches, we find notable names such as Layered Architecture, Hexagonal Architecture (also known as Ports and Adapters), Onion Architecture, Impure Domain Architecture, Schema Architecture, and, quite explicitly, Clean Architecture itself.

An Additional Key Insight: Avoiding Infrastructure Contracts in the Domain Layer

A prevalent and subtle mistake when implementing Clean Architecture is the direct introduction of contracts (Ports) for external concerns—such as repository interfaces or service clients from specific providers—directly into the Domain layer. While it's correct to depend on abstractions, the nature of these abstractions is critical. The Domain should contain only the pure business logic and rules that are fundamental to the problem being solved. When we define an interface like IUserRepository or IPaymentGateway within the Domain, we are implicitly modeling a technical concern (persistence, external communication) and dictating a data-access or integration pattern to the core business rules. This contaminates the domain with a narrative of implementation, binding it to a specific architectural pattern (like the Repository pattern) or a technological context (like "gateways"). Consequently, the Domain is no longer solely about the essential business concepts but becomes cluttered with solutions to infrastructure problems, violating the Dependency Rule and reducing its purity and longevity.

The Correct Abstraction: Domain-Centric Contracts

The proper approach is to ensure that all contracts owned by the Domain layer are expressed exclusively in terms of domain language and abstract, and eventually facades (compute libraries invertion), not technical mechanisms. Instead of a generic IRepository<T>, the Domain should define application-specific service interfaces, such as IUserRegistry or IOrderFulfillmentService, which declare the intent required by the business processes (e.g., ActiveCustomersByRegion, ProcessedPaymentForOrder). These interfaces articulate what the business needs, not how it should be achieved (e.g., via a SQL database, a REST API, or an event stream). The concrete implementations of these contracts—the Adapters—are then provided in the outer layers (Infrastructure/Data), which in turn may use generic technical patterns like Repositories or API clients. This inversion keeps the Domain completely agnostic of technical decisions, frameworks, and data sources, truly embodying the independence that Clean Architecture promises and ensuring that the core business rules remain the most stable and isolated part of the system.

Maybe in upcoming articles, we will delve deeper into each of these architectural paradigms, unraveling their intricacies and exploring their practical applications. Stay tuned for a journey through the world of clean architectures!

Exploring Abstraction and Decoupling in software development 🤩

Vıɔk A Hıƃnıʇɐ C. — Fri, 01 Sep 2023 12:39:00 +0000

In the world of software development, there are two distinct types of abstractions that play essential roles. The first is closely related to the Object-Oriented Programming (OOP) paradigm and serves as a technique to simplify the modeling and manipulation of real-world systems, including objects and their groups. This approach involves hiding intricate internal details while emphasizing elements that are crucial for a program's operation.

However, the primary focus of this article centers on abstraction, specifically the principle of dependency inversion.

To put it simply, abstraction involves separating the "what" from the "how". This means isolating the purpose or functionality of a component from the specific way it accomplishes that functionality.

Translating this concept into programming terminology, the "what" represents the action, often defined through interfaces or abstract classes. These actions may accept input parameters and produce results. The "how" pertains to the procedural details, encompassing the manipulation of these parameters and internal components to generate outcomes. This intricate process is embodied by concrete classes or implementations.

At its core, abstraction in software design serves a fundamental purpose in our solutions—namely, decoupling. This decoupling enhances modularity, flexibility, and maintainability. It breaks down dependencies, ensuring that modifications to one component do not trigger a chain reaction across the entire system.

Have you ever pondered what the landscape of software development would look like without the concept of decoupling? Such contemplation can evoke a sense of complexity, underscoring the profound impact of abstraction on our industry.

The intricate interplay between abstraction and decoupling enhances our ability to design sophisticated systems with elegance. As we navigate the dynamic realm of software engineering, comprehending and harnessing these concepts stand as pivotal tools in our pursuit of innovation and efficiency.

I suggest you continue reading the next article

You don't know OOP, the heater does♨️

Vıɔk A Hıƃnıʇɐ C. — Tue, 18 Apr 2023 02:21:48 +0000

In an enchanted forest, where logic and magic danced hand in hand, there lived a Magic Box. Inside, a structured chaos reigned, filled with objects, each with a unique identity, a state of mind, and a very particular behavior. Each one knew its purpose in life, but was incapable of performing a complex function on its own. They were a community of simple souls in search of a common goal. ❄️

On a bitterly cold winter day, when the chill penetrated the very wooden bones of the box, the Resistor, an object with the gift of generating heat, realized a fundamental truth: its gift was useless without the power of energy. Then, the Battery, a source of life overflowing with magical electrons, offered to help. With a gesture of generosity, it granted the Resistor the ability to inherit ⬇️ its energy. The Resistor, now powered, began to glow with a faint reddish warmth. But soon a new problem arose: the heat accumulated and there was nothing to disperse it into the air.

The Fan, a dreamy object with restless blades, volunteered. However, to move and spread that precious heat, it also needed to inherit ⬇️ the Battery's energy. The Battery, with its collaborative spirit, agreed. Together, these three objects decided to unite their forces and create a new entity, a larger and more powerful class they called "Heater." 🏭

But when they activated the system, confusion reigned. The Fan did not move. It was still, silent. 🔇 After a quick investigation, they discovered the problem: the power functionality that the Battery had directly granted was useless for the Fan. The Resistor worked happily with Direct Current (DC), the very essence of the Battery. But the Fan, with a more complex design, needed Alternating Current (AC) to spin its motor. It was a conflict of identities.

The Battery, wise and flexible, devised a brilliant solution. It decided not to give its energy directly, but to implement a contract, an "Interface" 🤝, a promise to supply energy. Through this agreement, each object could polymorph 🎭, meaning it could take the form of energy it needed. The Resistor interpreted the interface's energy as DC and kept on heating. The Fan interpreted it as AC and, with a sigh of relief, began to spin, spreading heat throughout the Magic Box. Polymorphism had saved the day!

Everything was working perfectly, but the Heater, the higher-ranking class, noticed something unsettling. It could feel the ambient heat, but it didn't know the exact temperature at which the Resistor was working. Worried, it asked:

—Resistor, what temperature are you at? I need to control your state to prevent overheating.

The Resistor, with a hint of pride in its metallic voice, replied:

—I'm sorry, sir. My temperature is a private matter, a detail of my design. I have it all encapsulated 📦. You can enjoy the heat I produce, but you cannot manipulate my internal thermostat.

The Heater, surprised, reflected:
—I understand the need for privacy; encapsulation protects your integrity. But I can see and regulate the Fan's speed. To fulfill my function of maintaining a pleasant climate, I need the same capability with you. I need a public interface to control your temperature.

The Resistor understood. Protection shouldn't be a wall that prevents collaboration, but rather a door with a lock. So, it decided to expose its encapsulated properties in a controlled manner, creating public methods for the Heater to safely read and adjust its temperature, without violating its internal integrity. The Heater, now in full control, could masterfully regulate the system, achieving the perfect temperature. ⚖️

Peace and warmth reigned for hours, until suddenly, a chill ran through the Magic Box. The Battery, which had given its all, emitted one final flicker and was completely drained. Exhaustion was total. Things were getting very, very cold. 🥶

But just as hope began to freeze, an object everyone had forgotten came to life: the Electrical Outlet 🔌, which until then had remained inactive, frozen in a corner. With a click, it offered its help.

—I can provide you with unlimited energy from the castle's main grid —it hummed energetically—. But I need the system to adapt.

The Heater, intrigued, asked how that was possible. The Outlet explained the concept of abstraction 🏛️:

—I don't need to know how the Resistor or the Fan work internally. I only need the Heater, the class that encompasses them, to understand that it can receive power through me. I will be the new source. My complexity (the voltage, the grid's current type) remains hidden from you all. I only expose the action 'deliverEnergy()'.

The Heater understood perfectly. It implemented the power functionality through the Outlet, who sent a surge of energy that revived the Battery. The cycle of life (and heat) could continue. Thanks to abstraction, the objects communicated without needing to know each other's complex internal secrets. 🔄

And so, the Resistor (with its encapsulated but controlled state), the Fan (with its energy polymorphism), the Battery (with its inheritance of power), and the Outlet (with its great abstraction), all united under the Heater class, managed to survive the harsh winter, creating an atmosphere of perfect and stable temperature. The Magic Box became the coziest home in the entire forest. 🤩

Detail of the magical concepts 🚀

In terms of the spells of Object-Oriented Programming, the story perfectly illustrates its four fundamental pillars:

Encapsulation 📦: The Resistor kept its temperature as a secret internal state, protected from the outside. Only when necessary and in a controlled manner (through public getter/setter methods), it exposed this information, allowing interaction without compromising its integrity. It's data protection.
Inheritance ⬇️: The Resistor and the Fan received (inherited) the ability to have energy from the Battery. By being part of the Heater class, they also inherited the context and the common goal of generating and dispersing heat.
Polymorphism 🎭: The Battery defined a contract (Interface) to supply energy. The Resistor and the Fan implemented that contract in completely different ways (DC vs. AC), responding to the same message ("take my energy") uniquely. One interface, multiple behaviors.
Abstraction 🏛️: The Heater class represents a general idea, hiding the complexity of its parts. The Outlet, for its part, is the perfect example: it hides the complex details of the electrical grid and only presents a simple operation ("deliverEnergy") that any class can use without understanding its internal workings.

In summary, this OOP Heater story is an enchanted journey to understand the key ideas of object-oriented programming. By giving it a more magical and narrative tone, it becomes more appealing to all audiences, transforming abstract concepts into characters with lives of their own. We hope this adventure inspires more people to learn about OOP and improve their skills to create their own magical worlds of code. 😎🚀

And then, when everything seemed perfect, a ray of light pierced the Magic Box. Familiar voices were heard in the distance... "I'm the avenger of the night!"... "It's morphin' time!"... Batman and the Power Rangers had arrived! And... to be continued!! 🤣

Software Architecture and Abstractions: A Beginner's Guide

Vıɔk A Hıƃnıʇɐ C. — Sat, 23 Apr 2022 23:21:00 +0000

How many times have you come across terms like: inversion of control (IoC), dependency inversion (DI - DIv), dependency injection (DI - DIj) and abstraction, a lot of times, right?
And I am sure that many times you have been practicing them without understanding in depth what is all that, so today is our day and I promise you that we are going to learn these terms in an easy way in a non-technical language for you to appropriate these concepts.

Well but to address these issues we must start at the origin of everything, the software architecture.

At the beginning when software development started everything was darkness, as something new it is normal that as the techniques and complexity of programming and algorithms advanced, problems of construction, scalability, maintenance began to be found, and back in the 60s concepts such as modularity, inheritance, encapsulation began to be touched, but it was finally in the 90s where the term architecture was used in contrast to the word design, evoking notions of abstraction and standards, then the light at the end of the tunnel began to be created.

What is software architecture?

We can define it in one word, decisions, and they are the design decisions that are made to meet the quality attributes when we have a problem to solve through software solutions, and these decisions, good or bad, model the structure at the level macro of the parts of that system and that modeling is done through software architecture patterns.

What is the patterns?

There are two types of patterns in the software world, software architecture patterns and software design patterns.

What are software architecture patterns?

They are archetypes (structures) that tell us how the parts of a software system relate/interact at the macro level, and some of there are:

Client - server, Microkernel, Dashboard, Peer to peer (P2P), Events broker pattern (Agent), Events bus pattern, Model view controller (MVC), N-Tires, Multilayer, Microservices, and others.

I leave you the task to read about them.

What are software design patterns?

They are base templates that have already been tested to solve common problems encountered in the software development process. They are classified into three groups (creative, structural, behavioral) and there are many, but here are just a few.
The creative group models the creation of concrete and abstract objects.
In the structural group, objects are modeled to form larger structures and complement their functionality.
And the behavioral group models how to interact and responsibilities in groups of objects.

Factory, Abstract factory, Strategy, Façade, Composite, Builder, Singleton, Data transfer object (DTO) and many others.

I leave you the task to read about them.

To learn about patterns, you ca go to:
Patterns

Now, what is abstraction?

In simple words abstraction can be defined as the separation of what and how, that is, separating what something does from how it does it.

So, the what is the action (Interface, Abstract class), this action receives or not input parameters and gives us a result.
The how is what is done (behavior) with those parameters and its internal objects to return the result, that is the concrete Class or implementation.

// Artifact in Application Layer
// This is the what, the compromise or contract
interface ILogProvider {
  logEvent(event: EventLog): Promise<void>;
  logError(error: ErrorLog): Promise<void>;
}
// Or like abstract class
abstract class LogProviderContract {
  abstract logEvent(event: EventLog): Promise<void>;
  abstract logError(error: ErrorLog): Promise<void>;
}

// Artifact in Adapters Layer
// And this is the how, the concrete Class or implementation
class LogProvider implements ILogProvider {
  constructor(private readonly logger: Logger) {}

  async logEvent(event: EventLog): Promise<void> {
    return this.logger.info(event);
  }

  async logError(error: ErrorLog): Promise<void> {
    return this.logger.error(error);
  }
}

The architecture of ports and adapters is based on this concept and what we must be clear is that a port is an interface or contract which must be in the application layer while the adapter is the concrete class that implements that interface/contract (secondary adapter in this case*), and it is also good to know that there are two types of adapters, the primary or driving adapters which are entry points to your application, for example a controller, and the secondary or driven adapters that must implement a port (interface - contract) and are injected to the application layer to perform functions such as access to data and services.

So, having understood what abstraction is, we can then review the following concepts.

What is the inversion of control (IoC)?

Basically it is to delegate, to delegate control of certain aspects of an application to a third party.
This third party is usually a framework or service, and can control from the lifecycle of objects (DIj) to that of the application itself, it can also control events and invoke application actions to those events (UI), it can also control data persistence and service providers.

What is dependency inversion (DIv)?

DIv basically is abstraction and since we already know that it is abstraction, then it is time to talk about its main function, and this function is to decouple the layers of your software solution.

This is one of the SOLID (DIvP) principles and landing its compendiums to a non-technical language we can say that:

Important classes should not depend on less important classes, both should depend on abstractions.
The what should not depend on the how, the how should depend on the what.

What is dependency injection (DIj)?

It is about separating the construction/creation (instances) from the execution context where the object interacts.

It is to delegate the creation of objects to a third party, in this case to a dependency injection container (DIjC) with the intention of decoupling the core of our application from the outside world, that of "trivial" things.

Now, you can learn more about this topics in the next resource:
Dependency inversion and injection

Question?

Is posible to use Dependency Injection without using Dependency Inversion?

The short answer is a partial Yes, but it is not recommended because in strongly typed languages it will generate a coupling between objects of different layers and performing end to end tests in certain cases will be very complex, however, in languages like JavaScript this is very common and it is considered good practice because this language has no interfaces or abstract classes* (Specifications before ES6), and not having defined types, it is better to use an injected module through a method to import it directly into the dependent module, therefore the mock of that injected artifact will be easily emulated.

What is Clean Architecture (CA)?

It can be defined as a framework or set of best practices aimed at facilitating the construction, testability and maintenance of a software product.

The term was coined by Robert C. Martin and in this compendium he took part of other architectural concepts "Tiers and Layers, Onion, Hexagonal (Ports and Adapters)" that have as main objective the abstraction, structuring the code through layers and isolating the inner world (application and business logic) from "trivial" things like the outside world.

The entities are the domain or business logic, the use cases are the application logic that orchestrates the domain artifacts, the adapters are the entry and exit points of your application, and the external world infrastructure are the connections, services and frameworks that enable the entry and exit points to enter and send the data being processed.

In a software solution these layers look more or less like the directories in the previous image.

Clean Architecture basic rules

Coupling is only allowed between a layer and its inner neighboring layer, except for the domain layer, it can be everywhere and at best abstracted to layers more external to the adapters layer. *
An inner layer must not depend on (be coupled to) an outer layer.

* Part of this is negotiated with the technical team.

How to do Clean Architecture and not fail in the attempt?

At first doing CA can be very complicated if you don't have enough experience, but like many things in life if you have a map or a practical and illustrative guide the mission becomes much easier because it shows you step by step the details that you must take into account to achieve your purpose.

For this reason we have created a diagram and its equivalence in code to help you in the task of abstracting the layers of your software solutions.

Magical formula

In code, it looks something like this:

// Application layer
interface IChatProvider {
  send(recipient: string, text: string): Promise<void>;
  read(): Promise<Message[]>;
}

// Adapter layer
interface IChatClient {
  send(message: Message): Promise<boolean>;
  read(recipient: string): Promise<Message[]>;
}

class ChatProvider implements IChatProvider {
  #address: string;
  #chatClient: IChatClient;
  #messages: Message[] = [];

  async send(recipient: string, text: string): Promise<boolean> {
    // implementation
  }
  async read(): Promise<Message[]> {
    // implementation
  }
}

// Infrastructure layer
class ChatConnection {
  #connected: boolean = false;
  #chatIO: ChatIO;

  connect(host: string, port: number): boolean {
    // implementation
  }
  disconnect(): boolean {
    // implementation
  }
}

class ChatClient implements IChatClient {
  #connection: ChatConnection;

  async send(message: Message): Promise<boolean> {
    // implementation
  }
  async read(recipient: string): Promise<Message[]> {
    // implementation
  }
}

Well, this is all I have to share in this article and I hope I have contributed to your knowledge by explaining these concepts in simpler terms because handling them in such technical terms can be a bit complicated to understand these concepts.

If you find any inaccuracies I appreciate the feedback. :)

Now, the next step for you is learn about Clean Architecture in the next resource, good luck!!
Clean Architecture using NodeJs and TypeScript

NodeJs - Dependency injection, make it easy

Vıɔk A Hıƃnıʇɐ C. — Sun, 29 Aug 2021 19:58:58 +0000

If when you are working with #NodeJs and #TypeScript you have not experienced mutation problems is a sign that you are doing things right or maybe you do not know what you are doing and in the latter case you have been playing with luck, good luck of course.

Based on the previous premise it becomes necessary a correct handling of the import of the modules that your application will use to create the pipeline where the requests will enter your application, and for this there are three ways, or at least I know three ways and each one brings with it its implications.

We have the following options:

Import module as a default instance (Singleton)
Import the types and create instances (transient) in the context where they will be used, usually a PrimaryAdapter or in simple words the entry point of that execution.
Create an IoC (Inversion of control) as a Dependency Container Service.

Option 1:

It is the simplest way to do it, but it is the least indicated because if you do not make a good implementation, you will probably have Mutations problems, a headache when working with JavaScript.

In some directory you will have something like this:

import { awesomeProvider, amazingProvider } from "../../providers/container";
import { AwesomeUseCase } from "../../../../application/modules/oneModule/useCases/awesome";
import { AmazingUseCase } from "../../../../application/modules/twoModule/useCases/amazing";

const awesomeUseCase = new AwesomeUseCase(awesomeProvider);
const amazingUseCase = new AmazingUseCase(amazingProvider);

export { awesomeUseCase, amazingUseCase };

And in your controller some like as follows:

import BaseController, { Request, Response, NextFunction } from "../base/Base.controller";
import { amazingUseCase, awesomeUseCase } from "./container/index";

class YourController extends BaseController {
  constructor() {
    super();
    this.initializeRoutes();
  }

  amazing = async (req: Request, res: Response, next: NextFunction): Promise<void> => {
    try {
      this.handleResult(res, await amazingUseCase.execute());
    } catch (error) {
      return next(error);
    }
  };

  awesome = async (req: Request, res: Response, next: NextFunction): Promise<void> => {
    try {
      this.handleResult(res, await awesomeUseCase.execute());
    } catch (error) {
      return next(error);
    }
  };

  protected initializeRoutes(): void {
    this.router.get("v1/amazing", this.amazing);
    this.router.get("v1/awesome", this.awesome);
  }
}

export default new YourController();

The problem with the previous implementation is that if the modules you export have global variables and in the case that two concurrent requests arrive at the same entry point, you will most likely have mutations, why?, because that's how JavaScript works.

Option 2:

This way is the most indicated, but you would dirty a lot your Adapter or entry point (Controller) with imports of all kinds, because most likely your module requires the injection of other dependencies and you would have to do a management of those instances, something cumbersome, and yes, I know you are probably thinking that you would create an index file and there you would do all that heavy work for the resources of the main instance, but it is still dirty, let's see:

import BaseController, { Request, Response, NextFunction } from "../base/Base.controller";
import { awesomeProvider, amazingProvider } from "../providers/container";
import { AwesomeUseCase } from "../../../application/modules/oneModule/useCases/awesome";
import { AmazingUseCase } from "../../../application/modules/twoModule/useCases/amazing";

class YourController extends BaseController {
  constructor() {
    super();
    this.initializeRoutes();
  }

  amazing = async (req: Request, res: Response, next: NextFunction): Promise<void> => {
    try {
      const amazingUseCase = new AmazingUseCase(amazingProvider);
      this.handleResult(res, await amazingUseCase.execute());
    } catch (error) {
      return next(error);
    }
  };

/* other entry points */

  protected initializeRoutes(): void {
    this.router.get("v1/amazing", this.amazing);
    this.router.get("v1/awesome", this.awesome);
  }
}

export default new YourController();

And depending on the amount of modules you use, this can grow in ways you can't even imagine, and that's where I'm going with the next point I want to share with you.

Option 3:

This way is one of the ContainerPatterns and basically is a Container like the IoC services or frameworks but more versatile, since you can handle from inverted dependencies or concrete classes that don't have defined contracts, so without further ado (Shit) let's go to the code.

Everything starts from a Class called Container
and a contract as a dictionary of type IContainerDictionary where we will relate our dependencies, whether Class with or without contracts (Interface) defined, and as we can see we have a get method that receives a type which will serve to manage it.

import { ApplicationError } from "../../application/shared/errors/ApplicationError";
import resources, { resourceKeys } from "../../application/shared/locals/messages";
import applicationStatus from "../../application/shared/status/applicationStatus";

export class Container {
  constructor(private readonly container: IContainerDictionary) {}

  get<T>(className: string): T {
    if (!this.container[className]) {
      throw new ApplicationError(
        resources.getWithParams(resourceKeys.DEPENDENCY_NOT_FOUNT, { className }),
        applicationStatus.INTERNAL_ERROR,
      );
    }

    return this.container[className]() as T;
  }
}

export interface IContainerDictionary {
  [className: string]: NewableFunction;
}

The Container Class should be part of the Adapters Layer of your solution, it should have nothing to do neither with the Application and/or Domain layer of your solution speaking in terms of a Clean Architecture based solution, even in a N Layers.

To use this pattern we go to our Adapters layer, where is our entry point, usually a Controller, there we create a directory called container and in this a file index, and there we would have something like the following code:

import { Container, IContainerDictionary } from "../../../../dic/Container";
import { AwesomeUseCase } from "../../../../application/modules/one/useCases/awesome";
import { AmazingUseCase } from "../../../../application/modules/two/useCases/amazing";
import { awesomeProvider, amazingProvider } from "../../../providers/container/index";

const dictionary: IContainerDictionary = {};
dictionary[AwesomeUseCase.name] = () => new AwesomeUseCase(awesomeProvider);
dictionary[AmazingUseCase.name] = () => new AmazingUseCase(amazingProvider);

export { AwesomeUseCase, AmazingUseCase };
export default new Container(dictionary);

And once we have our container then we can make use of it in our controllers as follows:

import BaseController, { Request, Response, NextFunction } from "../base/Base.controller";
import container, { AmazingUseCase, AwesomeUseCase } from "./container/index";

class YourController extends BaseController {
  constructor() {
    super();
    this.initializeRoutes();
  }

  amazing = async (req: Request, res: Response, next: NextFunction): Promise<void> => {
    try {
      this.handleResult(res, await container.get<AmazingUseCase>(AmazingUseCase.name).execute());
    } catch (error) {
      return next(error);
    }
  };

  awesome = async (req: Request, res: Response, next: NextFunction): Promise<void> => {
    try {
      this.handleResult(res, await container.get<AwesomeUseCase>(AwesomeUseCase.name).execute());
    } catch (error) {
      return next(error);
    }
  };

  protected initializeRoutes(): void {
    this.router.get("v1/amazing", this.amazing);
    this.router.get("v1/awesome", this.awesome);
  }
}

export default new YourController();

Now, how this works:
The key to everything is in the anonymous functions that we create in the dependencies dictionary, since when the get method of the Container is invoked, what we do is to execute this anonymous function so that it returns us the corresponding new instance (transient), something simple but powerful because it also optimizes the memory management of our applications, since there are no instances of any type of dependencies until the moment a request enters our entry point, and once the request has finished, the resources will be released because the execution context in the Call stack will have ended.

It's worth noting that there are packages that do this, some of them are inversify, awilix, typedi, among others NPM packages and now we have this feature as a NPM package in the next link:
dic-tsk

This article is the explanation of a thread I launched a few days ago on twitter (@vickodev) Spanish-tw-thread and while I was writing them it occurred to me that we can increase the possibilities of the container but that will be in another possible post.

I hope the reading of this post has been enriching for the continuous learning path that requires to be dev. :)

NodeTSkeleton, a Clean Architecture template project for NodeJS

Vıɔk A Hıƃnıʇɐ C. — Sat, 08 Aug 2020 19:29:23 +0000

NodeTskeleton is a Clean Architecture based template project for NodeJs using TypeScript to implement with any web server framework or even any user interface.

The main philosophy of NodeTskeleton is that your solution (domain and application, “business logic”) should be independent of the framework you use, therefore your code should NOT BE COUPLED to a specific framework or library, it should work in any framework.

The design of NodeTskeleton is based in Clean Architecture, an architecture that allows you to decouple the dependencies of your solution, even without the need to think about the type of database, providers or services, the framework, libraries or any other dependencies.

NodeTskeleton has the minimum tools necessary for you to develop the domain of your application, you can even decide not to use its included tools (you can remove them), and use the libraries or packages of your choice.

Now it has CLI functions 📟

Now you can setup it very easy. For do it you only have to run the next command in a root directory in your terminal and run-tsk will do it all for you behind the scenes:

In the next command change my-awesome-project for your own project name

$ npx run-tsk setup project-name=my-awesome-project
$ cd my-awesome-project
$ npm run dev

With the previous and with the next feature you can easily use TSKeleton, and even create a use cases in a matter of seconds and then add your business logic, yes, it's that simple.

$ run-tsk help

run-tsk CLI available commands:
  > validate
    - The previous command will validate if the current directory is a root TSK project.

  > setup project-name=<project-name-value>
    - The previous command will setup the TSKProject ready for you to use it.
    - Example: run-tsk setup project-name=<your-awesome-project-name>

  > add-use-case api-name=<apiName> use-case=<useCaseName> endpoint=<endpoint> http-method=<METHOD>
    - The previous command will create a new UseCase into the project. Arguments can be sent in any order.
    - Example: run-tsk add-use-case api-name=auth use-case=Logout endpoint=/v1/auth/logout http-method=GET
    Aliases: add-uc

  > alias arg=<argName>
    - The previous command will show available aliases for the sended argument name.
    - Example: run-tsk alias arg=api-name

Philosophy 🧘🏽

Applications are generally developed to be used by people, so people should be the focus of them.

For this reason user stories are written, stories that give us information about the type of user (role), procedures that the user performs in a part of the application (module), important information that serves to structure the solution of our application, and in practice, how is this?

The user stories must be in the src/application path of our solution, there we create a directory that we will call modules and inside this, we create a directory for the task role, for example (customer, operator, seller, admin, ...) and inside the role we create a directory of the corresponding use case module, for example (product, order, account, sales, ...), and in practice that looks more or less like this:

Observations 👀

If your application has no roles, then there's no mess, it's just modules. ;)
But taking into consideration that if the roles are not yet defined in your application, the best option would be to follow a dynamic role strategy based on permissions and each use case within the application (or use case group) would be a specific permission that would feed the strategy of dynamic roles.
Note that you can repeat modules between roles, because a module can be used by different roles, because if they are different roles then the use cases should also be different, otherwise those users would have the same role.
This strategy makes the project easy to navigate, easy to change, scale and maintain, which boils down to good mental health, besides you will be able to integrate new developers to your projects in a faster way.

Included tools 🧰

NodeTskeleton includes some tools in the src/application/shared path which are described below:

Errors

Is a tool for separating controlled from uncontrolled errors and allows you to launch application errors according to your business rules, example:

/*
** context: it's the context where the error will be launched.
*/
export class ApplicationError extends Error {
  constructor(
    readonly context: string,
    readonly message: string,
    readonly errorCode: number | string,
    readonly stack?: string,
  ) {
    super(message);
    this.name = `${context.replace(/\s/g, StringUtil.EMPTY)}_${ApplicationError.name}`;
    this.errorCode = errorCode;
    this.stack = stack;
  }
  // ...
}

Is important to note that the name of the CONTEXT is concatenated with the name of the ApplicationError class in order to better identification of the controlled errors.
It's very useful for observability tools in order to filter out real errors from those we are controlling.

The straightforward way to use it is as follows:

throw new ApplicationError(
  this.CONTEXT,
  resources.get(resourceKeys.ERROR_TO_CREATE_SOMETHING),
  applicationStatusCode.BAD_REQUEST,
  JSON.stringify(error),
);

Or if the pointer of your program is in the scope of your UseCase, you can use the error control function in the BaseUseCase class:

The dirty way:

if (!someCondition) { // Or any validation result
  result.setError(
    this.resources.get(this.resourceKeys.PROCESSING_DATA_CLIENT_ERROR),
    this.applicationStatus.INTERNAL_SERVER_ERROR,
  );
  this.handleResultError(result);
}

The clean way one:

// In the UseCase context in Execute method
const user = await this.getUser(result, userId);
if (result.hasError()) return result;

// In the UseCase context in out of Execute method
private async getUser(result: IResult, userId: string): Promise<User> {
  const user = await this.userRepository.getById(userId):
  if (!user) {
    result.setError(
      this.resources.get(this.resourceKeys.USER_CAN_NOT_BE_CREATED),
      this.applicationStatus.INTERNAL_CONFLICT,
    );
  }

  return user;
}

The clean way two:

// In the UseCase context in Execute method
const { value: userExists } = await result.execute(
  this.userExists(user.email?.value as string),
);
if (userExists) return result;

// In the UseCase context in out of Execute method
private async userExists(email: string): ResultExecutionPromise<boolean> {
  const userExists = await this.userRepository.getByEmail(email);
  if (userExists) {
    return {
      error: this.appMessages.getWithParams(
        this.appMessages.keys.USER_WITH_EMAIL_ALREADY_EXISTS,
        {
          email,
        },
      ),
      statusCode: this.applicationStatus.INVALID_INPUT,
      value: true,
    };
  }

  return {
    value: false,
  };
}

The function of this class will be reflected in your error handler as it will let you know when an exception was thrown by your system or by an uncontrolled error, as shown below:

  handle: ErrorHandler = (
    err: ApplicationError,
    req: Request,
    res: Response,
    next: NextFunction,
  ) => {
  const result = new Result();
  if (err?.name.includes(ApplicationError.name)) {
    console.log("Controlled application error", err.message);
  } else {
    console.log("No controlled application error", err);
  }
};

Which use? Feel free, it's about colors and flavours, in fact you can developed your own strategy, but if you are going to prefer to use the The clean way one keep present the next recommendations:

Never, but never, use setData or setMessage methods of the result inside functions out of the UseCase Execute method context, only here (Inside the UseCase Execute method) this functions can be call.
You only must use methods to manage errors in result objects outside of the UseCase Execute method context.

Why?, it´s related to side effects, I normally use the The clean way one and I have never had a problem related to that, because I have been careful about that.

Locals (resources)

It is a basic internationalization tool that will allow you to manage and administer the local messages of your application, even with enriched messages, for example:

import resources, { resourceKeys } from "../locals/index";

const simpleMessage = resources.get(resourceKeys.ITEM_PRODUCT_DOES_NOT_EXIST);

const enrichedMessage = resources.getWithParams(resourceKeys.SOME_PARAMETERS_ARE_MISSING, {
    missingParams: keysNotFound.join(", "),
});

// The contents of the local files are as follows:
/* 
// en: 
export default {
    ...
    SOME_PARAMETERS_ARE_MISSING: "Some parameters are missing: {{missingParams}}.",
    ITEM_PRODUCT_DOES_NOT_EXIST: "The item product does not exist.",
    YOUR_OWN_NEED: "You are the user {{name}}, your last name is {{lastName}} and your age is {{age}}.",
    ...
}
// es: 
export default {
    ...
    SOME_PARAMETERS_ARE_MISSING: "Faltan algunos parámetros: {{missingParams}}.",
    ITEM_PRODUCT_DOES_NOT_EXIST: "El item del producto no existe.",
    YOUR_OWN_NEED: "Usted es el usuario {{name}}, su apellido es {{lastName}} y su edad es {{age}}.",
    ...
}
...
*/

// You can add enriched messages according to your own needs, for example:
const yourEnrichedMessage = resources.getWithParams(resourceKeys.YOUR_OWN_NEED, {
    name: firstName, lastName, age: userAge
});
//

For use it in any UseCase you can do something like:

result.setError(
    this.appMessages.get(this.appMessages.keys.PROCESSING_DATA_CLIENT_ERROR), // Or this.appMessages.getWithParams(...)...
    this.applicationStatus.INTERNAL_SERVER_ERROR,
);

And you can add all the parameters you need with as many messages in your application as required.

The resource files can be local files in JSON format or you can get them from an external service.

Mapper

The mapper is a tool that will allow us to change the entities to the DTOs within our application, including entity changes between the data model and the domain and vice versa.

This tool maps objects or arrays of objects, for example:

// For object
const textFeelingDto = this.mapper.mapObject<TextFeeling, TextFeelingDto>(
    textFeeling,
    new TextFeelingDto(),
);

// For array objects
const productsDto: ProductDto[] = this.mapper.mapArray<Product, ProductDto>(
    products,
    () => this.mapper.activator(ProductDto),
);

Activator is the function responsible for returning a new instance for each call, otherwise you would have an array with the same object repeated N times.

Result

export class GetProductUseCase extends BaseUseCase<string> { // Or BaseUseCase<{ idMask: string}>
    constructor(private productQueryService: IProductQueryService) {
        super();
    }

    async execute(idMask: string): Promise<IResult<ProductDto>> { // If object input type is (params: { idMask: string}) so you can access to it like params.idMask
        // We create the instance of our type of result at the beginning of the use case.
        const result = new Result<ProductDto>();
        // With the resulting object we can control validations within other functions.
        if (!this.validator.isValidEntry(result, { productMaskId: idMask })) {
            return result;
        }
        const product: Product = await this.productQueryService.getByMaskId(idMask);
        if (!product) {
            // The result object helps us with the error response and the code.
            result.setError(
                this.appMessages.get(this.appMessages.keys.PRODUCT_DOES_NOT_EXIST),
                this.applicationStatus.NOT_FOUND,
            );
            return result;
        }
        const productDto = this.mapper.mapObject<Product, ProductDto>(product, new ProductDto());
        // The result object also helps you with the response data.
        result.setData(productDto, this.applicationStatus.SUCCESS);
        // And finally you give it back.
        return result;
    }
}

The result object may or may not have a type of response, it fits your needs, and the result instance without type cannot be assigned data.

const resultWithType = new Result<ProductDto>();
// or
const resultWithoutType = new Result();

The result object can help you in unit tests as shown below:

it("should return a 400 error if quantity is null or zero", async () => {
    itemDto.quantity = null;
    const result = await addUseCase.execute({ userUid, itemDto });
    expect(result.success).toBeFalsy();
    expect(result.error).toBe(
        appMessages.getWithParams(appMessages.keys.SOME_PARAMETERS_ARE_MISSING, {
            missingParams: "quantity",
        }),
    );
    expect(result.statusCode).toBe(resultCodes.BAD_REQUEST);
});

UseCase

The UseCase is a base class for extending use cases and if you were a retailer you could see it in action in the above explanation of the Result tool.

Its main function is to avoid you having to write the same code in every use case you have to build because it contains the instances of the common tools you will use in the case implementations.

The tools extended by this class are: the mapper, the validator, the message resources and their keys, and the result codes.

import messageResources, { Resources } from "../locals/messages/index";
import { ILogProvider } from "../log/providerContracts/ILogProvider";
export { IResult, Result, IResultT, ResultT } from "result-tsk";
import applicationStatus from "../status/applicationStatus";
import wordResources from "../locals/words/index";
import { Validator } from "validator-tsk";
import mapper, { IMap } from "mapper-tsk";
import { Throw } from "../errors/Throw";
import { IResult } from "result-tsk";
export { Validator, Resources };

export abstract class BaseUseCase<T> {
  mapper: IMap;
  validator: Validator;
  appMessages: Resources;
  appWords: Resources;
  applicationStatus = applicationStatus;

  constructor(public readonly CONTEXT: string, public readonly logProvider: ILogProvider) {
    this.mapper = mapper;
    this.appMessages = messageResources;
    this.appWords = wordResources;
    this.validator = new Validator(
      messageResources,
      messageResources.keys.SOME_PARAMETERS_ARE_MISSING,
      applicationStatus.INVALID_INPUT,
    );
  }

  handleResultError(result: IResult): void {
    Throw.when(this.CONTEXT, !!result?.error, result.error, result.statusCode);
  }

  abstract execute(args?: T): Promise<IResult>;
}

Type T in BaseUseCase<T> is a way for the optimal control of the input parameters of your UseCase unit code.

So, you can use it like the next examples:

// UseCase with input params
export class LoginUseCase
  extends BaseUseCase<{ email: string; passwordB64: string }>
{
  constructor(logProvider: ILogProvider, private readonly authProvider: IAuthProvider) {
    super(LoginUseCase.name, logProvider);
  }

  async execute(params: { email: string; passwordB64: string }): Promise<IResultT<TokenDto>> {
        // Your UseCase implementation
    }
}

// UseCase without input params
export class ListUsersUseCase extends BaseUseCase<undefined>
{
  constructor(logProvider: ILogProvider, private readonly userProvider: IUserProvider) {
    super(LoginUseCase.name, logProvider);
  }

  async execute(): Promise<IResultT<User[]>> {
        // Your UseCase implementation
    }
}

Or you can use the libraries from NPM directly.

Validator

The validator is a very basic but dynamic tool and with it you will be able to validate any type of object and/or parameters that your use case requires as input, and with it you will be able to return enriched messages to the client regarding the errors or necessary parameters not identified in the input requirements, for example:

/*...*/
async execute(userUid: string, itemDto: CarItemDto): Promise<IResult<CarItemDto>> {
    const result = new Result<CarItemDto>();
    if (
        !this.validator.IsValidEntry(result, {
            User_Identifier: userUid,
            Car_Item: itemDto,
            Order_Id: itemDto?.orderId,
            Product_Detail_Id: itemDto?.productDetailId,
            Quantity: itemDto?.quantity,
        })
    ) {
        /* 
        The error message on the result object will include a base message and will add to 
        it all the parameter names that were passed on the object that do not have a valid value.
        */
        return result;
    }
    /*...*/
    return result;
}
/*...*/

Validations functions (New feature 🤩)

The validation functions extend the isValidEntry method to inject small functions created for your own needs.

The philosophy of this tool is that it adapts to your own needs and not that you adapt to it.

To do this the isValidEntry function input value key pair also accepts array of small functions that must perform a specific task with the parameter to be validated.

Observation

If you are going to use the validation functions feature, you must send as a parameter an array even if it is only a function.

Important note

The validation functions should return NULL if the parameter for validate is valid and a string message indicating the reason why the parameter is not valid.

// Validator functions created to meet your own needs
function validateEmail(email: string): string {
  if (/^\w+([\.-]?\w+)*@\w+([\.-]?\w+)*(\.\w{2,3})+$/.test(email)) {
    return null;
  }
  return resources.getWithParams(resourceKeys.NOT_VALID_EMAIL, { email });
}

function greaterThan(numberName: string, base: number, evaluate: number): string {
  if (evaluate && evaluate > base) {
    return null;
  }
  return resources.getWithParams(resourceKeys.NUMBER_GREATER_THAN, {
    name: numberName,
    baseNumber: base.toString(),
  });
}

function evenNumber(numberName: string, evaluate: number): string {
  if (evaluate && evaluate % 2 === 0) {
    return null;
  }
  return resources.getWithParams(resourceKeys.MUST_BE_EVEN_NUMBER, {
    numberName,
  });
}


// Entry in any use case
const person = new Person("Jhon", "Doe", "myemail@orion.com", 21);
/*...*/
const result = new Result();
if (!validator.isValidEntry(result, {
    Name: person.name,
    Last_Name: person.lastName,
    Email: [() => validateEmail(person.email)],
    Age: [
        () => greaterThan("Age", 25, person.age),
        () => evenNumber("Age", person.age),
    ],
})) {
    return result;
}
/*...*/
// result.error would have the following message
// "Some parameters are missing or not valid: The number Age must be greater than 25, The Age parameter should be even."

Dependency injection strategy 📦

For dependency injection, no external libraries are used. Instead, a container dictionary strategy is used in which instances and their dependencies are created and then resolved from container class.

This strategy is only needed in the adapter layer dependencies for controllers like services and providers, and also for the objects used in the use case tests, for example:

// In the path src/adapters/controllers/textFeeling there is a folder called container and the index file have the following code lines:
import { GetHighestFeelingSentenceUseCase } from "../../../../application/modules/feeling/useCases/getHighest";
import { GetLowestFeelingSentenceUseCase } from "../../../../application/modules/feeling/useCases/getLowest";
import { GetFeelingTextUseCase } from "../../../../application/modules/feeling/useCases/getFeeling";
import { Container, IContainerDictionary } from "../../../shared/Container";
import { textFeelingService } from "../../../providers/container/index";

const dictionary = new ContainerDictionary();
dictionary.addScoped(GetHighestFeelingSentenceUseCase.name, () => new GetHighestFeelingSentenceUseCase(textFeelingService));
dictionary.addScoped(GetLowestFeelingSentenceUseCase.name, () => new GetLowestFeelingSentenceUseCase(textFeelingService));
dictionary.addScoped(GetFeelingTextUseCase.name, () => new GetFeelingTextUseCase(textFeelingService));

// This class instance contains the UseCases needed for your controller
export default new Container(dictionary); // *Way One*
// You can also export separate instances if required, like this:
const anotherUseCaseOrService = new AnotherUseCaseOrService();
export { anotherUseCaseOrService }; // *Way Two*
// You can combine the two strategies (Way One and Way Two) according to your needs

Another way to export dependencies is to simply create instances of the respective classes (only recommended with provider and repository services).

// The same way in src/adapters/providers there is the container folder
import TextFeelingService from "../../../application/modules/feeling/serviceContracts/textFeeling/TextFeelingService";
import TextFeelingProvider from "../../providers/feeling/TextFeelingProvider";
import { HealthProvider } from "../health/HealthProvider";

const textFeelingProvider = new TextFeelingProvider();
const textFeelingService = new TextFeelingService(textFeelingProvider);

const healthProvider = new HealthProvider();

export { healthProvider, textFeelingService };
// And your repositories (folder src/adapters/repositories) must have the same strategy

For ioc our container strategy manage the instances of the UseCases for the specific controller and here the necessary dependencies for the operation of those UseCases are injected, then they are exported and into the controller they are imported and used from our container as following:

// For ExpressJs
import { GetFeelingTextUseCase } from "../../../application/modules/feeling/useCases/getFeeling";
import { Request, Response, NextFunction } from "../../../infrastructure/server/CoreModules";
import { TextDto } from "../../../application/modules/feeling/dtos/TextReq.dto";
import BaseController from "../BaseController";
import container, {
  anotherUseCaseOrService,
} from "./container/index";

class TextFeelingController extends BaseController { 
      constructor(serviceContainer: IServiceContainer) {
        super(serviceContainer);
      }
    /*...*/
    // *Way One*
    getFeelingText = async (req: Request, res: Response, next: NextFunction): Promise<void> => {
        try {
            const textDto: TextDto = req.body;
            this.handleResult(res, await container.get<GetFeelingTextUseCase>(GetFeelingTextUseCase.name).execute(textDto));
        } catch (error) {
            next(error);
        }
    };

    // *Way Two*
    getFeelingText = async (req: Request, res: Response, next: NextFunction): Promise<void> => {
        try {
            const textDto: TextDto = req.body;
            this.handleResult(res, await getFeelingTextUseCase.execute(textDto));
        } catch (error) {
            next(error);
        }
    };
    /*...*/
}

The Way One delivers a different instance for each UseCase call.

The Way Two delivers the same instance (only one instance) for each useCase call, which can lead to the most common problem, mutations.

As you can see this makes it easy to manage the injection of dependencies without the need to use sophisticated libraries that add more complexity to our applications.

But if you prefer or definitely your project need a library, you can use something like awilix or inversifyJs.

Using NodeTskeleton 👾

In this template is included the example code base for KoaJs and ExpressJs, but if you have a web framework of your preference you must configure those described below according to the framework.

Using with KoaJs 🦋

Go to repo for KoaJs in this Link

And then, continue with the installation step described in the instructions from original project on github.

Controllers

The location of the controllers must be in the adapters directory, there you can place them by responsibility in separate directories.

The controllers should be exported as default modules to make the handling of these in the index file of our application easier.

// Controller example with export default
import BaseController, { Context } from "../BaseController";
import { TextDto } from "../../../application/modules/feeling/dtos/TextReq.dto";
import container, {
  anotherUseCaseOrService,
} from "./container/index";

class TextFeelingController extends BaseController {
    constructor(serviceContainer: IServiceContainer) {
            super(serviceContainer);
        }
    /*...*/
}

const instance = new TextFeelingController(container);
// You can see the default export
export default instance;

Example of the handling of the controllers in the index file of our application:

/*...*/
// Region controllers
import productController from "./adapters/controllers/product/Product.controller";
import shoppingCarController from "./adapters/controllers/shoppingCart/ShoppingCar.controller";
import categoryController from "./adapters/controllers/category/CategoryController";
/*...*/
// End controllers

const controllers: BaseController[] = [
    productController,
    shoppingCarController,
    categoryController,
    /*...*/
];

const app = new AppWrapper(controllers);
/*...*/

Routes

The strategy is to manage the routes within the controller, this allows us a better management of these, in addition to a greater capacity for maintenance and control according to the responsibilities of the controller.

/*...*/
initializeRoutes(router: IRouterType) {
        this.reouter = router;
    this.router.post("/v1/cars", authorization(), this.Create);
    this.router.get("/v1/cars/:idMask", authorization(), this.Get);
    this.router.post("/v1/cars/:idMask", authorization(), this.Buy);
    this.router.post("/v1/cars/:idMask/items", authorization(), this.Add);
    this.router.put("/v1/cars/:idMask/items", authorization(), this.Remove);
    this.router.delete("/v1/cars/:idMask", authorization(), this.Empty);
    /*...*/
}
/*...*/

Root path

If you need to manage a root path in your application then this part is configured in App, the infrastructure server module that loads the controllers as well:

/*...*/
private loadControllers(controllers: BaseController[]) {
    controllers.forEach((controller) => {
        // This is the line and the parameter comes from `config`.
        controller.router.prefix(config.server.Root);
                controller.initializeRoutes(router);
        this.app.use(controller.router.routes());
        this.app.use(controller.router.allowedMethods());
    });
}
/*...*/

Using with ExpressJs 🐛

Clone this repo project or use it as template from github, and then, continue with the installation step described in this guide.

And then, continue with the installation step described in this manual.

Controllers

The location of the controllers must be in the adapters directory, there you can place them by responsibility in separate directories.

The controllers should be exported as default modules to make the handling of these in the index file of our application easier.

// Controller example with default export
import BaseController, { Request, Response, NextFunction } from "../BaseController";
import { TextDto } from "../../../application/modules/feeling/dtos/TextReq.dto";
import container, {
  anotherUseCaseOrService,
} from "./container/index";

class TextFeelingController extends BaseController {
    constructor(serviceContainer: IServiceContainer) {
            super(serviceContainer);
        }
    /*...*/
}

const instance = new TextFeelingController(container);
// You can see the default export
export default instance;
// Or just use export default new TextFeelingController();

Example of the handling of the controllers in the index file of our application:

/*...*/
// Region controllers
import productController from "./adapters/controllers/product/Product.controller";
import shoppingCarController from "./adapters/controllers/shoppingCart/ShoppingCar.controller";
import categoryController from "./adapters/controllers/category/CategoryController";
/*...*/
// End controllers

const controllers: BaseController[] = [
    productController,
    shoppingCarController,
    categoryController,
    /*...*/
];

const app = new AppWrapper(controllers);
/*...*/

Routes

/*...*/
initializeRoutes(router: IRouterType) {
        this.router = router();
    this.router.post("/v1/cars", authorization(), this.Create);
    this.router.get("/v1/cars/:idMask", authorization(), this.Get);
    this.router.post("/v1/cars/:idMask", authorization(), this.Buy);
    this.router.post("/v1/cars/:idMask/items", authorization(), this.Add);
    this.router.put("/v1/cars/:idMask/items", authorization(), this.Remove);
    this.router.delete("/v1/cars/:idMask", authorization(), this.Empty);
    /*...*/
}
/*...*/

Root path

If you need to manage a root path in your application then this part is configured in App, the infrastructure server module that loads the controllers as well:

/*...*/
private loadControllers(controllers: BaseController[]): void {
    controllers.forEach((controller) => {
        // This is the line and the parameter comes from `config`.
                controller.initializeRoutes(Router);
        this.app.use(config.server.Root, controller.router);
    });
}
/*...*/

Using with another web server framework 👽

You must implement the configuration made with ExpressJs or KoaJs with the framework of your choice and install all the dependencies and devDependencies for your framework, You must also modify the Server module, Middleware in infrastructure directory and the BaseController and Controllers in adapters directory.

And then, continue with the step installation.

Infrastructure 🏗️

The infrastructure includes a customizable HttpClient with its response model in src/infrastructure/httpClient/TResponse.ts for error control, and at the application level a class strategy src/application/shared/result/... is included as a standardized response model.

Installation 🔥

You must first clone the repo.

Then, we must install the dependencies, run:

npm install

Second, we must update the dependencies, run:

npm update

Third, run project in hot reload mode (Without debug, for it go to Debug instructions)

npm run dev

npm run build
node dist/index

Finally, in any web browser go to:

localhost:3003/api/ping

And you can use PostMan as follow:

Try import this request. So, click to Import > Select Raw text, and paste the next code:

curl --location --request POST 'localhost:3003/api/v1/users/login' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "harvic3@protonmail.com",
    "password": "Tm9kZVRza2VsZXRvbio4"
}'

The password is equivalent for "NodeTskeleton*8" in Base64 format.

Application debugger 🔬

If you are using VS Code the easiest way to debug the solution is to follow these instructions:

First go to package.json file.

Second, into package.json file locate the debug command just above the scripts section and click on it.

Third, choose the dev script when the execution options appear.

So, wait a moment and then you will see something like this on the console.

$ npm run dev
Debugger attached.
Waiting for the debugger to disconnect...
Debugger attached.

> nodetskeleton@1.0.0 dev
> ts-node-dev --respawn -- src/index.ts

Debugger attached.
[INFO] 22:52:29 ts-node-dev ver. 1.1.8 (using ts-node ver. 9.1.1, typescript ver. 4.4.3)
Debugger attached.
Running in dev mode
AuthController was loaded
HealthController was loaded
Server running on localhost:3003/api

To stop the debug just press Ctrl C and close the console that was opened to run the debug script.

This method will allow you to develop and have the solution be attentive to your changes (hot reload) without the need to restart the service, VS Code does it for you automatically.

Test your Clean Architecture 🥁

Something important is to know if we really did the job of building our clean architecture well, and this can be found very easily by following these steps:

Make sure you don't have any pending changes in your application to upload to your repository, otherwise upload them if you do.
Identify and remove adapters and infrastructure directories from your solution, as well as the index.ts file.
Execute the test command npm t or npm run test and the build command tsc or npm run build too, and everything should run smoothly, otherwise you violated the principle of dependency inversion or due to bad practice, application layers were coupled that should not be coupled.
Run the git checkout . command to get everything back to normal.
Most importantly, no domain entity can make use of an application service and less of a provider service (repository or provider), the application services use the entities, the flow goes from the most external part of the application to the most internal part of it.

Coupling 🧲

For the purpose of giving clarity to the following statement we will define coupling as the action of dependence, that is to say that X depends on Y to function.

Coupling is not bad if it is well managed, but in a software solution there should not be coupling of the domain and application layers with any other, but there can be coupling of the infrastructure layer or the adapters layer with the application and/or domain layer, or coupling of the infrastructure layer with the adapters layer and vice versa.

Clustering the App (Node Cluster)

NodeJs solutions run on a single thread, so it is important not to run CPU-intensive tasks, however NodeJs in Cluster Mode can run on several cores, so if you want to get the most out of your solution running on a multi-core machine, this is probably a good option, but if your machine has no more than one core, this will not help.

So, for Cluster de App, replace src/index.ts code for the next code example.

Observation 👀

For some reason that I don't understand yet, the dynamic loading of modules presents problems with Node in Cluster Mode, so if you plan to use cluster mode, you must inject the controllers to the AppWrapper class instance as shown in the following code sample, otherwise if you are not going to use the cluster mode then you can skip the import of the controllers and let the loading be done dynamically by the AppWrapper internal class method.

// Node App in Cluster mode
import { cpus } from "os";
import "express-async-errors";
import * as cluster from "cluster";
import config from "./infrastructure/config";
import AppWrapper from "./infrastructure/app/AppWrapper";
import { HttpServer } from "./infrastructure/app/server/HttpServer";
import errorHandlerMiddleware from "./infrastructure/middleware/error";

// Controllers
import BaseController from "./adapters/controllers/base/Base.controller";
import healthController from "./adapters/controllers/health/Health.controller";
import authController from "./adapters/controllers/auth/Auth.controller";
// End Controllers

const controllers: BaseController[] = [healthController, authController];

function startApp(): void {
  const appWrapper = new AppWrapper(controllers);
  const server = new HttpServer(appWrapper);
  server.start();

  process.on("uncaughtException", (error: NodeJS.UncaughtExceptionListener) => {
    errorHandlerMiddleware.manageNodeException("UncaughtException", error);
  });

  process.on("unhandledRejection", (reason: NodeJS.UnhandledRejectionListener) => {
    errorHandlerMiddleware.manageNodeException("UnhandledRejection", reason);
  });
}

if (cluster.isMaster) {
  const totalCPUs = cpus().length;
  console.log(`Total CPUs are ${totalCPUs}`);
  console.log(`Master process ${process.pid} is running`);

  for (let i = 0; i < totalCPUs; i++) {
    cluster.fork(config.Environment);
  }

  cluster.on("exit", (worker: cluster.Worker, code: number, signal: string) => {
    console.log(`Worker ${worker.process.pid} stopped with code ${code} and signal ${signal}`);
    cluster.fork();
  });
} else {
  startApp();
}

// Node App without Cluster mode and controllers dynamic load.
import "express-async-errors";
import AppWrapper from "./infrastructure/app/AppWrapper";
import { HttpServer } from "./infrastructure/app/server/HttpServer";
import errorHandlerMiddleware from "./infrastructure/middleware/error";

const appWrapper = new AppWrapper();
const server = new HttpServer(appWrapper);
server.start();

process.on("uncaughtException", (error: NodeJS.UncaughtExceptionListener) => {
  errorHandlerMiddleware.manageNodeException("UncaughtException", error);
});

process.on("unhandledRejection", (reason: NodeJS.UnhandledRejectionListener) => {
  errorHandlerMiddleware.manageNodeException("UnhandledRejection", reason);
});

// Node App without Cluster mode with controllers load by constructor.
import "express-async-errors";
import AppWrapper from "./infrastructure/app/AppWrapper";
import { HttpServer } from "./infrastructure/app/server/HttpServer";
import errorHandlerMiddleware from "./infrastructure/middleware/error";

// Controllers
import BaseController from "./adapters/controllers/base/Base.controller";
import healthController from "./adapters/controllers/health/Health.controller";
import authController from "./adapters/controllers/auth/Auth.controller";
// End Controllers

const controllers: BaseController[] = [healthController, authController];

const appWrapper = new AppWrapper(controllers);
const server = new HttpServer(appWrapper);
server.start();

process.on("uncaughtException", (error: NodeJS.UncaughtExceptionListener) => {
  errorHandlerMiddleware.manageNodeException("UncaughtException", error);
});

process.on("unhandledRejection", (reason: NodeJS.UnhandledRejectionListener) => {
  errorHandlerMiddleware.manageNodeException("UnhandledRejection", reason);
});

Strict mode

TypeScript's strict mode is quite useful because it helps you maintain the type safety of your application making the development stage of your solution more controlled and thus avoiding the possible errors that not having this option enabled can bring.

This option is enabled by default in NodeTskeleton and is managed in the tsconfig.json file of your solution, but if you are testing and don't want to have headaches you can disable it.

  "strict": true,

Multi service monorepo

With this simple option you can develop a single code base and by means of the configuration file through the ENVs (environment variables) decide which service context to put online, so with the execution of different PipeLines.

Note that the system take the ServiceContext Server parameter in the config file from value of your .env file as follows:

// infrastructure/config/index
const serviceContext = process.env.SERVICE_CONTEXT || ServiceContext.NODE_TS_SKELETON;
...
Controllers: {
  ContextPaths: [
    // Health Controller should always be included, and others by default according to your needs.
    Normalize.pathFromOS(
      Normalize.absolutePath(__dirname, "../../adapters/controllers/health/*.controller.??"), 
    ),
    Normalize.pathFromOS(
      Normalize.absolutePath(
        __dirname,
        `../../adapters/controllers/${serviceContext}/*.controller.??`,
      ),
    ),
  ],
  // If the SERVICE_CONTEXT parameter is not set in the environment variables file, then the application will load by default all controllers that exist in the home directory.
  DefaultPath: [
    Normalize.pathFromOS(
      Normalize.absolutePath(__dirname, "../../adapters/controllers/**/*.controller.??"),
    ),
  ],
  Ignore: [Normalize.pathFromOS("**/base")],
},
Server: {
  ...
  ServiceContext: {
    // This is the flag that tells the application whether or not to load the drivers per service context.
    LoadWithContext: !!process.env.SERVICE_CONTEXT,
    Context: serviceContext,
  },
}

Note that by default all solution Controllers are set to the NodeTskeleton context which is the default value DefaultPath, but you are free to create as many contexts as your solution needs and load your Controllers on the context that you set in SERVICE_CONTEXT env.
The HealthController must always words for any context ContextPaths or for NodeTskeleton context, it cannot change because you need a health check point for each exposed service.

For example, the application have the SECURITY context and you can get it as follow:

// In your ENV file set context as users, like this:
NODE_ENV=development
SERVICE_CONTEXT=users
SERVER_ROOT=/api

So the path into ContextPaths settings that contains ${serviceContext} constant will have the following value:
../../adapters/controllers/users/*.controller.??
Then in the AppWrapper class, the system will load the controllers that must be exposed according to the service context.

The ServiceContext file is located in the infrastructure server directory:

// NodeTskeleton is the only context created, but you can create more o change this.
export enum ServiceContext {
  NODE_TS_SKELETON = "NodeTskeleton",
  SECURITY = "auth",
  USERS = "users",
}

How it working?

So, how can you put the multi-service mode to work?

It is important to note (understand) that the service contexts must be the names of the directories you will have inside the controllers directory, and you can add as many controllers as you need to each context, for example, in this application we have two contexts, users (USERS) and auth (SECURITY).

adapters
  controllers 
    auth // Context for SECURITY (auth)
      Auth.controller.ts
    users // Context for USERS (users)
      Users.controller.ts
    otherContext // And other service contexts according to your needs
      ...
application
...

All the above works for dynamic loading of controllers, therefore, if you are going to work the solution in CLUSTER mode you must inject the controllers by constructor as indicated in the cluster mode explanation and you must assign the context to each controller as shown in the following example:

// For example, the application have the SECURITY context and the Authentication Controller responds to this context as well:
class AuthController extends BaseController {
  constructor() {
    super(ServiceContext.SECURITY);
  }
  ...
}

So, for this feature the project has a basic api-gateway to route an entry point to the different ports exposed by each service (context).

You should note that you need, Docker installed on your machine and once you have this ready, then you should do the following:

First, open your console a go to the root directory of NodeTskeleton project.

Second, execute the next sequence of commands:

Build the tskeleton image

docker build . -t tskeleton-image

Build the tsk gateway image

cd tsk-gateway
docker build . -t tsk-gateway-image

Run docker-compose for launch our solution

docker-compose up --build

And latter you can use Postman or web browser for use the exposed endpoints of two services based in NodeTskeleton project

Security service

Health

curl --location --request GET 'localhost:8080/security/api/ping'

Login

curl --location --request POST 'localhost:8080/security/api/v1/auth/login' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "nodetskeleton@email.com",
    "password": "Tm9kZVRza2VsZXRvbio4"
}'

Users service

Health

curl --location --request GET 'localhost:8080/management/api/ping'

Register a new user

curl --location --request POST 'localhost:8080/management/api/v1/users/sign-up' \
--header 'Accept-Language: es' \
--header 'Authorization: Bearer jwt' \
--header 'Content-Type: application/json' \
--data-raw '{
    "firstName": "Nikola",
    "lastName": "Tesla",
    "gender": "Male",
    "password": "Tm9kZVRza2VsZXRvbio4",
    "email": "nodetskeleton@conemail.com"
}'

Considerations and recommendations

Database tables or collection names
It is recommended to use prefixes in the table or collection names because in microservice context you need to replicate data and you may have collisions in the local environment, for example, for the SECURITY service context you can use sec_users for the users table or collection and in the same way for the USERS service context you can use usr_users.
The idea is that you use an abbreviation of the service context as a prefix to the name of your tables or collections.
Database connections
In release and production environments you can use the same database connection configuration section of the config file to connect to your different databases in each of the service contexts even under the same technology (NoSQL, SQL or another one) and this can be achieved through the ENVs configuration of each service.
But at local level (development) you can use the same database according to the technology because by using prefixes in the tables and collections you will not have collisions and you can simplify and facilitate the development and the use of resources.
You must take into account that you cannot create relationships between tables or collections that are in different service contexts because this will not work in a productive environment since the databases will be different.

Conclusions (Personal) 💩

The clean architecture allows us to develop the use cases and the domain (business logic) of an application without worrying about the type of database, web server framework, protocols, services, providers, among other things that can be trivial and that the same application during the development will tell us what could be the best choice for the infrastructure and adapters of our application.
The clean architecture, the hexagonal architecture, the onion architecture and the ports and adapters architecture in the background can be the same, the final purpose is to decouple the business layer of our application from the outside world, basically it leads us to think about designing our solutions from the inside to outside and not from the outside to inside.
When we develop with clean architecture we can more easily change any "external dependency" of our application without major concerns, obviously there are some that will require more effort than others, for example migrating from a NoSql schema to a SQL schema where probably the queries will be affected, however our business logic can remain intact and work for both models.
The advantages that clean architecture offers us are very significant; it is one of the best practices for making scalable software that works for your business and not for your preferred framework.
Clean architecture is basically based on the famous and well-known five SOLID principles that we had not mentioned until this moment and that we very little internalized.

And then, Visit the project and give me a star.