@tuain/error-manager

Gestor de errores de la plataforma Tuain.

SOFTWARE PROPIETARIO. Copyright (c) 2022-2026 Imix Latam / TUAIN. Todos los derechos reservados. Este paquete no es software libre ni de código abierto. Su uso está sujeto a la licencia del archivo LICENSE: licencia de uso no exclusiva, no transferible y revocable, sin derecho a modificar, redistribuir, sublicenciar, descompilar ni aplicar ingeniería inversa.

El acceso público en el registro de npm no otorga licencia de uso. Que npm install funcione sin token no convierte a este paquete en permisivo: el derecho de uso proviene únicamente del contrato escrito con el Titular.

Qué es

Cada módulo de un servicio declara su catálogo de errores como [código, mensaje, httpStatus]. El gestor los registra, les asigna código de módulo y construye el objeto de error que el servicio devuelve. También permite publicar el catálogo a la gestión central de errores y recibir de vuelta los mensajes editados o traducidos, sin desplegar el servicio.

Se distribuye como un único bundle CommonJS minificado (dist/index.js) con sus definiciones de tipos (dist/index.d.ts). El código fuente no se publica.

Instalación

Acceso público: no se necesita token de lectura ni .npmrc.

npm install @tuain/error-manager

const ErrorManager = require('@tuain/error-manager');

Requiere Node 18 o superior.

Uso

const ErrorManager = require('@tuain/error-manager');

const errMgr = new ErrorManager({ name: 'miServicio', defaultLanguage: 'es' }, logger);

// Cada módulo declara su catálogo, agrupado por contexto
errMgr.addModuleSet('cuentas', {
  consulta: {
    noEncontrada: ['01', 'Cuenta no encontrada', 404],
    sinPrivilegios: ['02', 'Sin privilegios sobre la cuenta', 403],
  },
  escritura: {
    saldoInsuficiente: ['01', 'Saldo insuficiente', 409],
  },
});

// Y se consume por ruta modulo.contexto.error
const error = errMgr.get('cuentas.consulta.noEncontrada', `Cuenta ${id} no existe`);
// → { moduleName, moduleCode, contextName, errorName, errorCode, errorMessage, errorDetail, statusCode }

El httpStatus es opcional: si no se declara, se completa con '200'.

Dos códigos iguales en el mismo contexto se rechazan; en contextos distintos son válidos, porque la identidad del error es la ruta completa.

Gestión central de los mensajes

const dictionary = errMgr.getDictionary(); // catálogo como lista, para publicarlo
errMgr.replaceErrorMessages(recibido); // aplica los mensajes que vuelven

errMgr.on('newModule', (moduleName) => {
  // se dispara al registrar un catálogo, para publicarlo en caliente
});

replaceErrorMessages ignora las entradas que el catálogo local no conoce —desincronización esperable entre versiones desplegadas— y devuelve un objeto de error solo si el diccionario es inválido.

Ojo si vienes de [email protected]: en esa versión replaceErrorMessages no aplicaba nada. Al actualizar, los mensajes gestionados centralmente empiezan a reemplazar a los del código. Ver el CHANGELOG.

Errores fuera del catálogo

errMgr.generic('cuentas.consulta.imprevisto', 'Mensaje puntual', detalle);

Un detalle que conviene saber

addModuleSet reemplaza en el objeto que recibe cada declaración por el objeto de error ya procesado. Si el catálogo vive en un módulo compartido y dos gestores lo registran, el segundo lo recibe ya mutado; la librería lo detecta y lo respeta, pero conviene no depender de que la declaración siga siendo un arreglo después de registrarla.

Esa mutación es lo que hace funcionar get(modErrs.contexto.error), así que registrar el mismo nombre de módulo dos veces con juegos de declaraciones distintos —lo que ocurre cuando un módulo se re-requiere, típico con proxyquire en pruebas— tiene un matiz: el registro se rechaza, porque dos catálogos bajo el mismo nombre es un error, pero desde la 1.0.1 las declaraciones recibidas sí se resuelven contra el catálogo vigente y quedan utilizables. Antes quedaban crudas y get() devolvía un objeto degradado sin errorCode, con lo que el resultado dependía del orden de carga. Las entradas que el catálogo vigente no declara se dejan intactas y la divergencia se registra en bitácora.

Licencia de ejecución

Desde la 1.0.0 el paquete incluye el mecanismo de verificación de licencia, inerte en esta versión: no verifica nada y no cambia el comportamiento. Cuando el Titular lo active, la licencia se entrega en la variable de entorno TUAIN_ERRORS_LICENSE, o por opciones al construir:

new ErrorManager({ name: 'miServicio', license: token }, logger);

Soporte

Titular: Imix Latam / TUAIN — [email protected]