@chejende/clean-arch 1.0.0 → 1.0.1

package/README.md

@@ -1,28 +1,474 @@
-# Getting Started With Schematics
+# @chejende/clean-arch
 
-This repository is a basic Schematic implementation that serves as a starting point to create and publish Schematics to NPM.
+Angular schematic para generar features con Clean Architecture (Hexagonal-inspired) de forma consistente, rapida y mantenible.
 
-### Testing
+This package provides an Angular schematic to scaffold features using a Clean Architecture (Hexagonal-inspired) structure that is consistent, fast, and maintainable.
 
-To test locally, install `@angular-devkit/schematics-cli` globally and use the `schematics` command line tool. That tool acts the same as the `generate` command of the Angular CLI, but also has a debug mode.
+## Tabla de Contenidos / Table of Contents
 
-Check the documentation with
+- [1. ¿Para que sirve? (ES)](#1-para-que-sirve-es)
+- [2. Instalacion (ES)](#2-instalacion-es)
+- [3. Uso rapido (ES)](#3-uso-rapido-es)
+- [4. Arquitectura generada (ES)](#4-arquitectura-generada-es)
+- [5. Ejemplos detallados (ES)](#5-ejemplos-detallados-es)
+- [6. Buenas practicas (ES)](#6-buenas-practicas-es)
+- [7. Publicar en npm (ES)](#7-publicar-en-npm-es)
+- [8. What is this for? (EN)](#8-what-is-this-for-en)
+- [9. Installation (EN)](#9-installation-en)
+- [10. Quick start (EN)](#10-quick-start-en)
+- [11. Generated architecture (EN)](#11-generated-architecture-en)
+- [12. Detailed examples (EN)](#12-detailed-examples-en)
+- [13. Best practices (EN)](#13-best-practices-en)
+- [14. Publish to npm (EN)](#14-publish-to-npm-en)
+
+---
+
+## 1. ¿Para que sirve? (ES)
+
+`@chejende/clean-arch` crea automaticamente el esqueleto de una feature en Angular separando responsabilidades por capas:
+
+- `domain`: reglas y contratos del negocio.
+- `application`: casos de uso, DTOs y providers.
+- `infrastructure`: integraciones tecnicas (API, repositorios concretos, mappers).
+- `presentation`: pagina/componente y store para estado UI.
+
+Objetivo:
+
+- Reducir tiempo de arranque de nuevas funcionalidades.
+- Estandarizar estructura entre equipos.
+- Evitar mezcla de logica de negocio con detalles de framework o transporte.
+
+---
+
+## 2. Instalacion (ES)
+
+### Como dependencia de desarrollo
+
+```bash
+npm install -D @chejende/clean-arch
+```
+
+### Uso sin instalar (one-shot)
+
+```bash
+npx -p @chejende/clean-arch ng g @chejende/clean-arch:feature users
+```
+
+Requisito recomendado: Angular CLI instalado en el proyecto.
+
+---
+
+## 3. Uso rapido (ES)
+
+### Comando principal
+
+```bash
+ng g @chejende/clean-arch:feature --name=users
+```
+
+Tambien funciona con argumento posicional:
+
+```bash
+ng g @chejende/clean-arch:feature users
+```
+
+### Alternativa con `schematics`
+
+```bash
+npx schematics @chejende/clean-arch:feature --name=users
+```
+
+---
+
+## 4. Arquitectura generada (ES)
+
+Para `users`, se genera:
+
+```text
+src/app/features/users/
+	domain/
+		models/users.model.ts
+		repositories/users.repository.ts
+	application/
+		dto/users.dto.ts
+		use-cases/get-users.use-case.ts
+		providers/users.providers.ts
+	infrastructure/
+		services/users-api.service.ts
+		repositories/users.repository.impl.ts
+		mappers/users.mapper.ts
+	presentation/
+		pages/users.page.ts
+		store/users.store.ts
+```
+
+### Flujo de dependencias recomendado
+
+`presentation -> application -> domain`  
+`infrastructure -> domain`
+
+Esto evita acoplar la logica de negocio con Angular, HTTP o detalles de infraestructura.
+
+---
+
+## 5. Ejemplos detallados (ES)
+
+### Ejemplo 1: Feature de autenticacion
+
+```bash
+ng g @chejende/clean-arch:feature auth
+```
+
+Uso recomendado:
+
+- Definir contratos en `domain/repositories/auth.repository.ts`.
+- Implementar consumo HTTP en `infrastructure/services/auth-api.service.ts`.
+- Orquestar flujo en `application/use-cases/get-auth.use-case.ts`.
+- Exponer estado en `presentation/store/auth.store.ts`.
+
+### Ejemplo 2: Feature de productos
 
 ```bash
-schematics --help
+ng g @chejende/clean-arch:feature products
+```
+
+Buenas decisiones comunes:
+
+- `products.dto.ts`: forma de datos de entrada/salida de backend.
+- `products.mapper.ts`: conversion DTO -> Modelo de dominio.
+- `products.repository.impl.ts`: delega en API service y devuelve dominio.
+
+### Ejemplo 3: Feature de ordenes
+
+```bash
+ng g @chejende/clean-arch:feature orders
+```
+
+Caso practico:
+
+- Crear `GetOrdersUseCase` para lectura.
+- Agregar otros casos de uso (`CreateOrderUseCase`, `CancelOrderUseCase`) dentro de `application/use-cases`.
+
+### Ejemplo 4: Registro de providers
+
+En la feature `users`, el schematic crea `USERS_PROVIDERS`. Puedes registrarlo en config de app:
+
+```ts
+import { ApplicationConfig } from '@angular/core';
+import { USERS_PROVIDERS } from './features/users/application/providers/users.providers';
+
+export const appConfig: ApplicationConfig = {
+  providers: [...USERS_PROVIDERS],
+};
+```
+
+### Ejemplo 5: Uso del caso de uso desde presentacion
+
+```ts
+import { Component, inject } from '@angular/core';
+import { UsersRepository } from '../../domain/repositories/users.repository';
+import { GetUsersUseCase } from '../../application/use-cases/get-users.use-case';
+
+@Component({
+  standalone: true,
+  template: `<button (click)="load()">Load users</button>`,
+})
+export class UsersPage {
+  private repo = inject(UsersRepository);
+
+  async load() {
+    const useCase = new GetUsersUseCase(this.repo);
+    const users = await useCase.execute();
+    console.log(users);
+  }
+}
 ```
 
-### Unit Testing
+### Ejemplo 6: Mapper explicito
 
-`npm run test` will run the unit tests, using Jasmine as a runner and test framework.
+```ts
+import { UsersMapper } from './features/users/infrastructure/mappers/users.mapper';
 
-### Publishing
+const dto = { id: '123' };
+const model = UsersMapper.toDomain(dto);
+console.log(model.id);
+```
+
+### Ejemplo 7: Flujo de prueba unitaria por capa
+
+- `domain`: prueba reglas puras sin Angular.
+- `application`: prueba casos de uso con mocks de repositorio.
+- `infrastructure`: prueba adaptadores y mappers.
+- `presentation`: prueba componentes/store con TestBed cuando aplique.
+
+---
+
+## 6. Buenas practicas (ES)
+
+1. Mantener el dominio libre de framework.
+2. Usar interfaces/abstract classes en `domain` para inversion de dependencias.
+3. Mapear DTOs a modelos de dominio en `infrastructure/mappers`.
+4. Evitar llamadas HTTP directas desde `presentation`.
+5. Encapsular logica de negocio en casos de uso (`application/use-cases`).
+6. Registrar providers por feature para modularidad.
+7. Nombrar features en minuscula y en plural cuando representen colecciones (`users`, `products`).
+8. Agregar casos de uso pequenos y orientados a una accion.
+9. Mantener stores enfocados en estado de interfaz, no en reglas de negocio.
+10. Probar cada capa segun su responsabilidad.
 
-To publish, simply do:
+Por que hacerlo asi:
+
+- Mejora testabilidad.
+- Reduce acoplamiento.
+- Facilita cambios de backend/UI sin romper reglas del negocio.
+- Escala mejor en equipos grandes y monorepos.
+
+---
+
+## 7. Publicar en npm (ES)
+
+### Build local
 
 ```bash
 npm run build
+```
+
+### Publicacion
+
+```bash
 npm publish
 ```
 
-That's it!
+Nota: este paquete ya tiene `prepublishOnly`, por lo que `npm publish` ejecuta build antes de publicar.
+
+Checklist previa:
+
+1. Incrementar version en `package.json`.
+2. Verificar que `dist/` se genera correctamente.
+3. Confirmar credenciales con `npm whoami`.
+4. Revisar README (este archivo) porque sera la documentacion en npm.
+5. Publicar con `npm publish --access public` si aplica.
+
+---
+
+## 8. What is this for? (EN)
+
+`@chejende/clean-arch` automatically scaffolds Angular features following Clean Architecture layers:
+
+- `domain`: business contracts and rules.
+- `application`: use cases, DTOs, and providers.
+- `infrastructure`: API services, concrete repositories, and mappers.
+- `presentation`: UI page/component and feature store.
+
+Main goals:
+
+- Speed up feature bootstrap.
+- Keep a consistent architecture across teams.
+- Prevent business logic from being coupled to framework details.
+
+---
+
+## 9. Installation (EN)
+
+### As a dev dependency
+
+```bash
+npm install -D @chejende/clean-arch
+```
+
+### One-shot usage (without installing)
+
+```bash
+npx -p @chejende/clean-arch ng g @chejende/clean-arch:feature users
+```
+
+Recommended prerequisite: Angular CLI available in the target project.
+
+---
+
+## 10. Quick start (EN)
+
+```bash
+ng g @chejende/clean-arch:feature --name=users
+```
+
+Positional argument also works:
+
+```bash
+ng g @chejende/clean-arch:feature users
+```
+
+Alternative with `schematics`:
+
+```bash
+npx schematics @chejende/clean-arch:feature --name=users
+```
+
+---
+
+## 11. Generated architecture (EN)
+
+For `users`, the schematic creates:
+
+```text
+src/app/features/users/
+	domain/
+		models/users.model.ts
+		repositories/users.repository.ts
+	application/
+		dto/users.dto.ts
+		use-cases/get-users.use-case.ts
+		providers/users.providers.ts
+	infrastructure/
+		services/users-api.service.ts
+		repositories/users.repository.impl.ts
+		mappers/users.mapper.ts
+	presentation/
+		pages/users.page.ts
+		store/users.store.ts
+```
+
+Suggested dependency direction:
+
+`presentation -> application -> domain`  
+`infrastructure -> domain`
+
+This keeps the core business model independent from transport and framework details.
+
+---
+
+## 12. Detailed examples (EN)
+
+### Example 1: Authentication feature
+
+```bash
+ng g @chejende/clean-arch:feature auth
+```
+
+Suggested usage:
+
+- Keep repository contracts in `domain/repositories`.
+- Implement HTTP calls in `infrastructure/services`.
+- Orchestrate user flows in `application/use-cases`.
+- Handle view state in `presentation/store`.
+
+### Example 2: Products feature
+
+```bash
+ng g @chejende/clean-arch:feature products
+```
+
+Typical design choices:
+
+- Keep backend shapes in `products.dto.ts`.
+- Convert DTOs to domain models with `products.mapper.ts`.
+- Keep external calls inside `products.repository.impl.ts`.
+
+### Example 3: Orders feature
+
+```bash
+ng g @chejende/clean-arch:feature orders
+```
+
+Practical extension:
+
+- Start with `GetOrdersUseCase`.
+- Add dedicated use cases like `CreateOrderUseCase`, `CancelOrderUseCase`.
+
+### Example 4: Provider registration
+
+```ts
+import { ApplicationConfig } from '@angular/core';
+import { USERS_PROVIDERS } from './features/users/application/providers/users.providers';
+
+export const appConfig: ApplicationConfig = {
+  providers: [...USERS_PROVIDERS],
+};
+```
+
+### Example 5: Calling a use case from presentation
+
+```ts
+import { Component, inject } from '@angular/core';
+import { UsersRepository } from '../../domain/repositories/users.repository';
+import { GetUsersUseCase } from '../../application/use-cases/get-users.use-case';
+
+@Component({
+  standalone: true,
+  template: `<button (click)="load()">Load users</button>`,
+})
+export class UsersPage {
+  private repo = inject(UsersRepository);
+
+  async load() {
+    const useCase = new GetUsersUseCase(this.repo);
+    const users = await useCase.execute();
+    console.log(users);
+  }
+}
+```
+
+### Example 6: Explicit mapper usage
+
+```ts
+import { UsersMapper } from './features/users/infrastructure/mappers/users.mapper';
+
+const dto = { id: '123' };
+const model = UsersMapper.toDomain(dto);
+console.log(model.id);
+```
+
+### Example 7: Layer-based test strategy
+
+- `domain`: pure business tests, no Angular runtime needed.
+- `application`: use cases tested with repository mocks.
+- `infrastructure`: adapter and mapper tests.
+- `presentation`: UI/store tests with Angular testing tools when required.
+
+---
+
+## 13. Best practices (EN)
+
+1. Keep the domain layer framework-agnostic.
+2. Use interfaces/abstract classes in `domain` for dependency inversion.
+3. Map DTOs to domain models in `infrastructure/mappers`.
+4. Avoid direct HTTP calls from the presentation layer.
+5. Put business behavior into `application/use-cases`.
+6. Register providers per feature to preserve modularity.
+7. Use lowercase, meaningful feature names.
+8. Prefer small, single-purpose use cases.
+9. Keep stores focused on UI state.
+10. Test each layer according to its responsibility.
+
+Why this works:
+
+- Better testability.
+- Lower coupling.
+- Easier evolution of backend and UI independently.
+- Better long-term scalability for teams.
+
+---
+
+## 14. Publish to npm (EN)
+
+### Build
+
+```bash
+npm run build
+```
+
+### Publish
+
+```bash
+npm publish
+```
+
+Note: `prepublishOnly` already runs the build process before publishing.
+
+Pre-publish checklist:
+
+1. Bump `version` in `package.json`.
+2. Verify `dist/` output and generated `collection.json`.
+3. Confirm npm auth using `npm whoami`.
+4. Review this README since it is your npm landing documentation.
+5. Publish with `npm publish --access public` when needed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chejende/clean-arch",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Angular Clean Architecture schematics",
   "keywords": [
     "angular",