JavaScript
Explica cómo crear subclases de Error con name, code, cause y datos estructurados para representar fallos técnicos o del dominio sin depender del mensaje.
Un error personalizado representa un fallo con significado propio dentro de una aplicación o dominio.
class ProductNotFoundError extends Error {
constructor(productId, options = {}) {
super(
`Product ${productId} was not found`,
options,
);
this.name = "ProductNotFoundError";
this.code = "PRODUCT_NOT_FOUND";
this.productId = productId;
}
}class ValidationError extends Error {
constructor(message, options = {}) {
super(message, options);
this.name = "ValidationError";
}
}Uso:
throw new ValidationError(
"Email is invalid",
);Comprobación:
error instanceof ValidationError;
error instanceof Error;Ambas expresiones son true dentro del mismo realm.
Una subclase no obtiene automáticamente un name específico en todas las formas esperadas.
class ValidationError extends Error {}
new ValidationError("Invalid").name;
// Normalmente "Error".Establecerlo mejora el diagnóstico:
this.name = "ValidationError";No lo uses como único identificador estable; también es una propiedad modificable.
class InsufficientStockError extends Error {
constructor({
productId,
requested,
available,
cause,
}) {
super(
"There is not enough stock",
{ cause },
);
this.name = "InsufficientStockError";
this.code = "INSUFFICIENT_STOCK";
this.productId = productId;
this.requested = requested;
this.available = available;
}
}El mensaje ayuda al humano. Las propiedades permiten decisiones y registros precisos.
if (error instanceof InsufficientStockError) {
showStockMessage({
requested: error.requested,
available: error.available,
});
}class RepositoryUnavailableError extends Error {
constructor(message, options = {}) {
super(message, options);
this.name = "RepositoryUnavailableError";
this.code = "REPOSITORY_UNAVAILABLE";
}
}try {
await database.query(sql);
} catch (cause) {
throw new RepositoryUnavailableError(
"Products cannot be loaded",
{ cause },
);
}La capa traduce un detalle de infraestructura y conserva el origen.
Menos estructurado:
throw new Error(
`Cannot load products: ${cause.message}`,
);Esto pierde el objeto original, su tipo, stack y propiedades.
Más claro:
throw new Error(
"Cannot load products",
{ cause },
);El sistema de logging puede recorrer la cadena cuando sea necesario.
this.code = "PRODUCT_NOT_FOUND";Un código es útil cuando:
No generes decisiones comparando frases humanas.
class DomainError extends Error {}
class OrderError extends DomainError {}
class InvalidOrderStateError extends OrderError {}Una jerarquía puede permitir manejo por nivel:
if (error instanceof DomainError) {
// Fallo esperado del dominio.
}Pero demasiadas clases generan complejidad sin beneficio.
Crea una clase cuando aporta al menos una de estas cosas:
No crees una clase nueva solo para cambiar una frase.
class ValidationError extends Error {
constructor(issues, options = {}) {
super(
"The input contains invalid fields",
options,
);
this.name = "ValidationError";
this.code = "VALIDATION_FAILED";
this.issues = issues;
}
}throw new ValidationError([
{
field: "email",
code: "INVALID_EMAIL",
},
{
field: "age",
code: "OUT_OF_RANGE",
},
]);El mensaje general permanece estable y cada issue describe un problema concreto.
Cuando varios errores independientes deben conservarse:
const errors = [];
for (const notifier of notifiers) {
try {
await notifier.send(message);
} catch (error) {
errors.push(error);
}
}
if (errors.length > 0) {
throw new AggregateError(
errors,
"Some notifications failed",
);
}No lo uses cuando solo existe una causa lineal; para eso cause expresa mejor la cadena.
cause → un error provocó otro
AggregateError → varios errores forman un resultado conjuntoJSON.stringify(
new Error("Failed"),
);
// Normalmente "{}".Muchas propiedades estándar de Error no son enumerables.
En una frontera API, crea una representación explícita.
function toPublicError(error) {
return {
code: error.code ?? "INTERNAL_ERROR",
message: publicMessageFor(error),
};
}No serialices automáticamente stack, cause o propiedades internas hacia clientes.
class ValidationError extends Error {
constructor(issues) {
super("Validation failed");
this.name = "ValidationError";
this.code = "VALIDATION_FAILED";
this.issues = issues;
}
toJSON() {
return {
name: this.name,
code: this.code,
message: this.message,
issues: this.issues,
};
}
}Puede ser útil en un contrato controlado. Aun así, decide qué datos pueden salir de la aplicación; no expongas todo por comodidad.
Un error creado dentro de un iframe puede pertenecer a otro constructor global.
error instanceof Error;Puede no comportarse como esperas al cruzar realms.
Para contratos entre ventanas, workers, servicios o JSON, utiliza datos explícitos:
{
code: "PRODUCT_NOT_FOUND",
message: "Product not found"
}Las instancias son útiles dentro del mismo proceso; los datos son más portables entre fronteras.
El stack se relaciona con el momento de creación del Error.
const error = new Error("Failed");Crear el error cerca del problema suele dar una traza más útil que retornar un código y construir un Error muchas capas después.
Error interno:
new RepositoryUnavailableError(
"Product query failed after connection timeout",
);Mensaje público:
No pudimos cargar los productos. Inténtalo nuevamente.No tienen que ser iguales. El mensaje técnico ayuda a diagnosticar; la interfaz protege detalles y orienta al usuario.
class InvalidOrderStateError extends Error {
constructor({
orderId,
currentStatus,
expectedStatus,
cause,
}) {
super(
`Order ${orderId} must be ${expectedStatus}`,
{ cause },
);
this.name = "InvalidOrderStateError";
this.code = "INVALID_ORDER_STATE";
this.orderId = orderId;
this.currentStatus = currentStatus;
this.expectedStatus = expectedStatus;
}
}if (order.status !== "pending") {
throw new InvalidOrderStateError({
orderId: order.id,
currentStatus: order.status,
expectedStatus: "pending",
});
}El error conserva información suficiente para UI, logs y pruebas sin depender del texto.
name, code y datos estructurados cumplen funciones diferentes.cause conserva una cadena de causalidad.¿Cuál es la diferencia entre estas dos relaciones?
new Error("Cannot load config", { cause });
new AggregateError(errors, "Several tasks failed");cause representa una cadena donde un fallo originó otro. AggregateError reúne varios fallos que forman parte del mismo resultado conjunto.
Validación de datos explica cómo impedir que información externa inválida entre al núcleo de la aplicación.