@hemia/logger/README.md

Logger estructurado con soporte para trazabilidad, MongoDB y DI con tsyringe.

# @hemia/logger

Logger estructurado y extensible para aplicaciones Node.js, diseñado para trabajar con MongoDB y trazabilidad contextual. Soporta niveles de log, decoradores, almacenamiento flexible, y se integra con el sistema Hemia.

---

## Instalación

```bash
npm install @hemia/logger
```

---

## Características

* ✅ Niveles de log (`info`, `error`, `warning`, `debug`, `custom`)
* ✅ Almacenamiento flexible vía `NoSQLRepository`
* ✅ Soporte para `traceId`, contexto de ejecución y stack trace
* ✅ Integración con `mongoose`, `tsyringe` y `reflect-metadata`

---

## Ejemplo básico de uso

```ts
import { Logger } from '@hemia/logger';
import { container } from 'tsyringe';

const logger = container.resolve(Logger);

await logger.info('Usuario autenticado', 'trace-id-123', { userId: 'abc123' });
await logger.error('Error de base de datos', 'trace-id-456', { errorCode: 'DB_CONN' });
```

---

## API

### `log(level, message, traceId, additionalData?)`

Registra un log con nivel personalizado.

### `info(message, traceId, additionalData?)`

Nivel de información.

### `error(message, traceId, additionalData?)`

Nivel de error.

### `warning(message, traceId, additionalData?)`

Nivel de advertencia.

### `debug(message, traceId, additionalData?)`

Nivel de depuración.

### `find(filter, options?)`

Consulta logs por filtros.

### `findOne(filter)` / `getById(id)`

Consulta individual por filtro o ID.

### `update(filter, data)` / `delete(filter)`

Actualización o eliminación de logs.

---

## Esquema de logs (`ILogModel`)

El logger utiliza el siguiente esquema para guardar logs en MongoDB:

```ts
{
  projectId: string;
  traceId: string;
  logLevel: 'INFO' | 'ERROR' | 'DEBUG' | 'WARNING';
  timestamp: string;
  message: string;
  application?: { name: string; version: string };
  environment?: { name: string };
  requestContext?: { method: string; url: string; headers: object; body: any };
  responseContext?: { statusCode: number; body: any };
  context?: { operation: string; memoryUsage: any };
  stackTrace?: { stage: string; message: string; timestamp: number }[];
  host?: { hostname: string; ip: string; platform: string };
  errorCode?: string;
  duration?: number;
}
```

---

## Requisitos

* MongoDB como almacenamiento principal
* `@hemia/db-manager` como dependencia
* `tsyringe` para inyección de dependencias
* `reflect-metadata` habilitado en `tsconfig.json`

---

## Licencia

MIT

---

## Autor

Hemia Technologies