@sgs-workflow/shared

Paquete compartido de utilidades, tipos y middleware para las APIs de SGS Workflow.

Descripción

Este paquete contiene código compartido que es utilizado por múltiples APIs del ecosistema SGS Workflow:

• server - API principal de workflow
• files-server - API de gestión de archivos
• security-api - API de autenticación y autorización

Estructura

shared/
├── utils/           # Utilidades compartidas
│   ├── db-actions.ts          # Acciones CRUD de base de datos
│   ├── filter-processor.ts    # Procesador de filtros
│   ├── filter-parser.ts       # Parser de filtros
│   └── condition-processor.ts # Procesador de condiciones
├── types/           # Tipos TypeScript compartidos
│   ├── auth.types.ts          # Tipos de autenticación
│   ├── db-actions.types.ts    # Tipos de acciones DB
│   ├── instances.types.ts     # Tipos de instancias
│   └── index.ts               # Exportaciones (incluye HttpStatus enum)
├── middleware/      # Middleware compartido
│   ├── error-handler.ts       # Manejador de errores (incluye AppError, asyncHandler)
│   └── index.ts               # Exportaciones
├── response/        # Helpers de respuesta
│   ├── api-response.ts        # Formato de respuestas API
│   └── index.ts               # Exportaciones
└── package.json     # Configuración del paquete

Instalación

Este paquete es interno del monorepo y se instala automáticamente con pnpm workspaces:

cd migration/backend
pnpm install

Uso

En server, files-server o security-api

// Importar utilidades de DB
import { list, data, publish, remove } from '@sgs-workflow/shared/utils/db-actions';

// Importar tipos
import type { ListParams, ListResponse } from '@sgs-workflow/shared/types/db-actions.types';
import type { UserSession, Instance } from '@sgs-workflow/shared/types/instances.types';

// Importar middleware
import { errorHandler } from '@sgs-workflow/shared/middleware/error-handler';

// Importar response helpers
import { ApiResponseHelper, sendResponse } from '@sgs-workflow/shared/response/api-response';

APIs Disponibles

Utils

db-actions.ts

Operaciones CRUD para Sequelize:

// Listar con paginación
const result = await list(model, {
  start: 0,
  limit: 20,
  where: { status: 'active' },
  order: 'id',
  asc: 'DESC'
}, '/endpoint');

// Obtener por ID
const item = await data(model, { id: 1 }, '/endpoint');

// Crear o actualizar
const saved = await publish(model, { id: 1, name: 'Updated' }, '/endpoint');

// Eliminar
const deleted = await remove(model, { id: 1 }, '/endpoint');

filter-processor.ts

Procesa filtros complejos para queries:

const filters = processFilters(model, {
  name: { _like: '%test%' },
  status: { _in: ['active', 'pending'] },
  createdAt: { _gte: '2024-01-01' }
});

condition-processor.ts

Procesa condiciones con operadores de Sequelize:

const condition = processCondition({
  field: 'age',
  operator: '_gte',
  value: 18
});

Types

instances.types.ts

Tipos para workflow instances:

• Instance - Instancia de workflow
• ListInstancesParams - Parámetros de listado
• UserSession - Sesión de usuario
• ViewType - Tipos de vista
• etc.

db-actions.types.ts

Tipos para acciones de DB:

• ListParams - Parámetros de listado
• ListResponse - Respuesta de listado
• DataResponse - Respuesta de data
• PublishResponse - Respuesta de publicación

Middleware

error-handler.ts

Middleware de manejo de errores con clases y utilidades:

import { errorHandler, notFoundHandler, AppError, asyncHandler } from '@sgs-workflow/shared/middleware';
import { HttpStatus } from '@sgs-workflow/shared/types';

// Registrar middleware
app.use(notFoundHandler);
app.use(errorHandler);

// Usar AppError para errores controlados
throw new AppError('User not found', HttpStatus.NOT_FOUND);
throw new AppError('Invalid input', HttpStatus.BAD_REQUEST, true, { field: 'email' });

// Usar asyncHandler para envolver rutas async
router.get('/users', asyncHandler(async (req, res) => {
  const users = await userService.getAll();
  res.json(ApiResponseHelper.success(users).body);
}));

Types

HttpStatus enum

Códigos HTTP estándar:

import { HttpStatus } from '@sgs-workflow/shared/types';

HttpStatus.OK                    // 200
HttpStatus.CREATED               // 201
HttpStatus.BAD_REQUEST           // 400
HttpStatus.UNAUTHORIZED          // 401
HttpStatus.FORBIDDEN             // 403
HttpStatus.NOT_FOUND             // 404
HttpStatus.INTERNAL_SERVER_ERROR // 500
HttpStatus.SERVICE_UNAVAILABLE   // 503

Response

api-response.ts

Helpers para formatear respuestas:

// Success response
const response = ApiResponseHelper.success({ data: items });
sendResponse(res, response);

// Error responses
const notFound = ApiResponseHelper.notFound('Item not found');
const badRequest = ApiResponseHelper.badRequest('Invalid input');
const unauthorized = ApiResponseHelper.unauthorized('Invalid token');
const internalError = ApiResponseHelper.internalError(error);

Desarrollo

Type Checking

cd shared
pnpm type-check

Agregar Nueva Utilidad

1. Crear archivo en el directorio apropiado
2. Exportar en index.ts
3. Documentar en este README

Agregar Nuevo Tipo

1. Crear archivo en types/
2. Exportar en types/index.ts
3. Documentar la interfaz

Versionamiento

Este paquete usa versionamiento semántico:

• 1.0.1 - Actualización de dependencias y mejoras
• 1.0.0 - Versión inicial con funcionalidades base

Licencia

UNLICENSED - Uso interno