Shared utilities, types, and middleware for SGS Workflow APIs
npm install @sgs-workflow/sharedPaquete compartido de utilidades, tipos y middleware para las APIs de SGS Workflow.
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
```
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
Este paquete es interno del monorepo y se instala automáticamente con pnpm workspaces:
`bash`
cd migration/backend
pnpm install
`typescript
// 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';
`
#### db-actions.ts
Operaciones CRUD para Sequelize:
`typescript
// 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:
`typescript`
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:
`typescript`
const condition = processCondition({
field: 'age',
operator: '_gte',
value: 18
});
#### instances.types.ts
Tipos para workflow instances:
- Instance - Instancia de workflowListInstancesParams
- - Parámetros de listadoUserSession
- - Sesión de usuarioViewType
- - Tipos de vista
- etc.
#### db-actions.types.ts
Tipos para acciones de DB:
- ListParams - Parámetros de listadoListResponse
- - Respuesta de listadoDataResponse
- - Respuesta de dataPublishResponse
- - Respuesta de publicación
#### error-handler.ts
Middleware de manejo de errores con clases y utilidades:
`typescript
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);
}));
`
#### HttpStatus enum
Códigos HTTP estándar:
`typescript
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
`
#### api-response.ts
Helpers para formatear respuestas:
`typescript
// 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);
`
`bash`
cd shared
pnpm type-check
1. Crear archivo en el directorio apropiado
2. Exportar en index.ts
3. Documentar en este README
1. Crear archivo en types/types/index.ts
2. Exportar en
3. Documentar la interfaz
Este paquete usa versionamiento semántico:
- 1.0.1 - Actualización de dependencias y mejoras1.0.0` - Versión inicial con funcionalidades base
-
UNLICENSED - Uso interno