npm package: @jamx-framework/core
Description: JAMX Framework â€” Core IoC Container and Utilities
Author: Stiven-21
Latest version: 1.0.0

# @jamjx-framework/core

## Descripción
Núcleo de JAMX Framework: contenedor de Inversión de Control (IoC), utilidades básicas, decoradores, bootstrap y sistemas de plugins. Este paquete provee la infraestructura fundamental que permite la modularidad, la inyección de dependencias y la arquitectura de extensibilidad de JAMX. Es el pilar sobre el cual se construyen todos los demás módulos del framework.

## Cómo funciona
El núcleo de JAMX está diseñado alrededor de tres conceptos clave:

1. **Container**: Sistema de registro y resolución de dependencias con soporte para scopes (`singleton`, `transient`, `scoped`) y detección de dependencias circulares.
2. **Decorators**: `@injectable()`, `@inject()` y `@module()` que permiten marcar clases y métodos para que el contenedor los gestione automáticamente.
3. **Bootstrap**: Función `bootstrap()` que inicia la aplicación, carga configuración, inicializa módulos y arranca servidores de manera ordenada.

Además, el núcleo incluye utilidades para:
- Generación de documentación (`DocGenerator`)
- Manejo de excepciones (`HttpException` y subclasses)
- Registro de plugins (`PluginRegistry`)
- Tipos y utilidades comunes (`Result`, `PaginationOptions`, `Brand`, etc.)

## Componentes principales
- **src/container/container.ts**: Clase `Container` que gestiona el registro y resolución de dependencias.
- **src/container/decorators.ts**: Decoradores `@injectable()` y `@inject()` para marcar clases y parámetros.
- **src/container/tokens.ts**: Definiciones de `Token`, `InjectionToken` y `tokenKey()` para identificar dependencias.
- **src/bootstrap/app.ts**: Función `bootstrap()` que orquesta el arranque de la aplicación.
- **src/docs/doc-generator.ts**: Clase `DocGenerator` para generar documentación en Markdown y OpenAPI.
- **src/exceptions/http.ts**: Jerarquía de excepciones HTTP (`BadRequestException`, `UnauthorizedException`, etc.).
- **src/module/module.ts**: Decorador `@module()` para definir módulos y sus dependencias.
- **src/plugins/registry.ts**: `PluginRegistry` para gestionar plugins con dependencias y ciclo de vida.
- **src/types/common.ts**: Tipos compartidos como `Result`, `PaginationOptions`, `Brand`, etc.
- **src/index.ts**: Punto de exportación que reúne todos los componentes del núcleo.

## Uso básico
```typescript
import { Container, token, injectable, inject } from '@jamx-framework/core';

// Definir tokens
const DB_TOKEN = token<Database>('Database');

// Clase inyectable
@injectable()
class Database {
  constructor(@inject(DB_TOKEN) private driver: DatabaseDriver) {}
}

// Registrar en el contenedor global
Container.registerClass(Database);

// Resolver dependencias
const db = Container.resolve(Database);
```

### Registro de servicios
```typescript
// Registrar una clase como singleton
Container.registerClass(UserRepository);

// Registrar un valor directo
const CONFIG_TOKEN = token<Config>('Config');
Container.register(COFIG_TOKEN, { useValue: myConfig });

// Registrar una fábrica
Container.registerClass(Logger, [Database], 'singleton');
```

### Inyección de dependencias
```typescript
@injectable()
class UsersService {
  constructor(@inject(UserRepository) private repo: UserRepository) {}

  async findAll() {
    return this.repo.findAll();
  }
}

// Al resolver UsersService, el contenedor inyecta automáticamente UserRepository
const service = Container.resolve(UsersService);
```

### Módulos
```typescript
@module({
  imports: [DatabaseModule],
  providers: [UsersService],
  controllers: [UsersController],
  exports: [UsersService],
})
class UsersModule {}
```

### Bootstrap
```typescript
import { bootstrap } from '@jamx-framework/core';

const app = await bootstrap({
  root: process.cwd(),
  hooks: {
    afterStart: ({ baseUrl }) => console.log(`Server ready at ${baseUrl}`),
  },
});

app.stop(); // Graceful shutdown
```

## Ejemplos
### Registro y resolución con scopes
```typescript
// Singleton (por defecto)
Container.registerClass(UserService);

// Transient (nueva instancia cada resolución)
Container.register(UserService, { scope: 'transient' });

// Scoped (una instancia por scope)
const scopeId = Container.beginScope();
const instance1 = Container.resolve(UserService, scopeId);
const instance2 = Container.resolve(UserService, scopeId);
expect(instance1).toBe(instance2);
Container.endScope(scopeId);
```

### Uso de decoradores
```typescript
// Clase inyectable con dependencias
@injectable()
class AuthService {
  constructor(@inject(PasswordHasher) private hasher: PasswordHasher) {}
}

// Parámetro inyectable
class LoginController {
  constructor(@inject(AuthService) private auth: AuthService) {}

  async login(email: string, password: string) {
    const hashed = await this.auth.hasher.verify(password, storedHash);
    if (!hashed) throw new UnauthorizedException('Invalid credentials');
    return { token: await this.auth.createToken({ email }) };
  }
}
```

### Bootstrap con hooks
```typescript
import { bootstrap } from '@jamx-framework/core';

await bootstrap({
  silent: false,
  hooks: {
    beforeConfig: () => console.log('Cargando configuración...'),
    afterConfig: (config) => console.log(`Modo: ${config.env}`),
    afterStart: ({ baseUrl }) => console.log(`🚀 Servidor escuchando en ${baseUrl}`),
    onShutdown: async () => {
      await someCleanupTask();
      console.log('🔌 Conexiones cerradas');
    },
  },
});
```

## Flujo interno
1. **Inicialización del Container**: Se crea una instancia global de `Container`.
2. **Registro de dependencias**: Los módulos y decoradores registran providers (`ClassProvider`, `ValueProvider`, `FactoryProvider`).
3. **Resolución**: Cuando se llama a `Container.resolve()`, se crea la instancia resolviendo dependencias recursivamente.
4. **Manejo de scopes**: Los scopes permiten instancias aisladas para requests HTTP o transacciones.
5. **Detección de ciclos**: Se lanza `CircularDependencyError` si se detecta un ciclo de dependencias.
6. **Bootstrap**: La función `bootstrap()` carga configuración, inicializa módulos y arranca servidores mediante hooks.
7. **Plugins**: `PluginRegistry` gestiona plugins con dependencias y permite ordenar su ejecución mediante topological sort.
8. **Documentación**: `DocGenerator` puede generar documentación a partir de endpoints registrados.

## Plugin Development
Para crear un plugin personalizado:

1. Implementa una clase que exponga `meta` (nombre, dependencias) y métodos `setup(ctx)` y `teardown?(ctx)`.
2. Regístralo en `PluginRegistry`.
3. Asegúrate de que `setup()` reciba el contexto adecuado (por ejemplo, `Container`).

Ejemplo mínimo:
```typescript
import type { Plugin, PluginContext } from '@jamx-framework/core';

export class LoggingPlugin implements Plugin<PluginContext> {
  meta = { name: 'logging' };

  async setup(ctx: PluginContext) {
    console.log('[Plugin] Logging initialized');
  }
}

// Registro
Container.registerPlugin(LoggingPlugin);
```

## Testing
El proyecto incluye tests unitarios en `packages/core/tests/unit/`. Para ejecutarlos:

```bash
pnpm test
# o
npm run test
```

Los tests cubren:
- Registro y resolución de dependencias
- Manejo de scopes y ciclos
- Decoradores `@injectable()` y `@inject()`
- Funcionalidad de `bootstrap()` con hooks
- Integración con `PluginRegistry`

## Compatibility
- Compatible con Node.js 18+ y TypeScript 5.x
- Funciona en Windows, macOS y Linux
- No tiene dependencias de runtime; solo devDependencies para testing
- Diseñado para ser usado como base de cualquier aplicación JAMX

## Configuration Options
El núcleo no requiere configuración explícita. Sin embargo, puedes personalizar el comportamiento mediante:

1. **Hooks en bootstrap**: Personaliza el ciclo de vida de la aplicación.
2. **Middlewares**: Añade lógica antes/durante/después de los handlers.
3. **Transformación de tokens**: Modifica cómo se identifican las dependencias.

## CLI Integration
Este paquete se integra automáticamente con el CLI de JAMX:
- `jamx build`: Compila el código fuente a `dist/`.
- `jamx dev`: Inicia un entorno de desarrollo que simula el bootstrap.
- `jamx check`: Verifica que el proyecto tenga la configuración mínima (`jamx.config.ts`).

## License
MIT © Stiven-21

This core package provides the foundational building blocks for building modular, type-safe applications with JAMX Framework, enabling developers to manage dependencies cleanly, extend functionality through plugins, and bootstrap applications with a consistent lifecycle.