@jysperu/schema-correo

Esquemas para correos electrónicos con soporte para Mongoose, JSON Schema y Joi.

🚀 Características

• 📧 Validación de correos electrónicos
• 🌍 Formato estándar RFC 5322 completo
• 🔧 Extracción automática de usuario y dominio
• 🏷️ Clasificaciones del uso de correo (Trabajo, Personal, etc.)
• ✅ Estados de validación y verificación

📦 Instalación

npm install @jysperu/schema-correo

⚡ Inicio Rápido

import { MongoSchemaCorreo, JsonSchemaCorreo, JoiSchemaCorreo, parseCorreo } from "@jysperu/schema-correo";
import { ICorreo, ClasificacionCorreo } from "@jysperu/schema-correo";

// Mongoose
const PersonaSchema = new Schema({
  correos: [MongoSchemaCorreo],
});

// Joi Validation
const { error, value } = JoiSchemaCorreo.validate({
  correo: "[email protected]",
  tipo: "Personal",
  valido: true,
});

// JSON Schema
const validate = ajv.compile(JsonSchemaCorreo);
const isValid = validate(correoData);

// Función utilitaria para parsear correos
const correoParseado = parseCorreo("[email protected]", { tipo: "Personal" });
// Resultado: { correo: "[email protected]", usuario: "usuario", dominio: "dominio.com", tipo: "Personal" }

📚 Esquemas Disponibles

1. 🍃 Mongoose Schema

import { MongoSchemaCorreo, ICorreo } from "@jysperu/schema-correo";
import { Schema, model, Document } from "mongoose";

interface IPersona extends Document {
  nombres: string;
  correos: ICorreo[];
}

const PersonaSchema = new Schema<IPersona>({
  nombres: { type: String, required: true },
  correos: [MongoSchemaCorreo], // Array de correos
});

const PersonaModel = model<IPersona>("Persona", PersonaSchema);

2. 📋 JSON Schema

import { JsonSchemaCorreo } from "@jysperu/schema-correo";
import Ajv from "ajv";

const ajv = new Ajv();
const validate = ajv.compile(JsonSchemaCorreo);

const correo = {
  correo: "[email protected]",
  tipo: "Personal",
  nombre: "Juan Pérez",
  valido: true,
};

const valid = validate(correo);
if (!valid) console.log(validate.errors);

3. ✅ Joi Schema

import { JoiSchemaCorreo } from "@jysperu/schema-correo";

// Validación individual
const { error, value } = JoiSchemaCorreo.validate({
  correo: "[email protected]",
  tipo: "Personal",
  nombre: "Ana García",
  valido: true,
});

if (error) {
  error.details.forEach((err) => console.log(`❌ ${err.path}: ${err.message}`));
}

// Para arrays de correos
import Joi from "@jysperu/joi-spanish";

const personaSchema = Joi.object({
  nombres: Joi.string().required(),
  correos: Joi.array().items(JoiSchemaCorreo).default([]),
});

🛠️ Casos de Uso Avanzados

Crear persona con múltiples correos

import { MongoSchemaCorreo, ICorreo, ClasificacionCorreo } from "@jysperu/schema-correo";

const persona = new PersonaModel({
  nombres: "Ana García",
  correos: [
    {
      correo: "[email protected]",
      tipo: ClasificacionCorreo.TRABAJO,
      nombre: "Ana García",
      usuario: "ana.garcia",
      dominio: "empresa.com",
      valido: true,
      verificado: true,
    },
    {
      correo: "[email protected]",
      tipo: ClasificacionCorreo.PERSONAL,
      nombre: "Ana García",
      usuario: "ana.personal",
      dominio: "gmail.com",
      valido: true,
    },
  ],
});

await persona.save();

Operaciones con correos

// Buscar correos verificados
const correosVerificados = persona.correos.filter((correo) => correo.verificado);

// Encontrar correos de trabajo
const correosDetrabajo = persona.correos.filter((correo) => correo.tipo === ClasificacionCorreo.TRABAJO);

// Agregar nuevo correo
persona.correos.push({
  correo: "[email protected]",
  tipo: "Backup",
  usuario: "ana.backup",
  dominio: "hotmail.com",
  valido: true,
});

await persona.save();

Usar la función parseCorreo

import { parseCorreo } from "@jysperu/schema-correo";

// Uso básico - extrae automáticamente usuario y dominio
const correo1 = parseCorreo("[email protected]");
console.log(correo1);
// { correo: "[email protected]", usuario: "usuario", dominio: "ejemplo.com" }

// Con configuración adicional
const correo2 = parseCorreo("[email protected]", {
  tipo: "Trabajo",
  nombre: "Ana García",
  valido: true
});
console.log(correo2);
// {
//   correo: "[email protected]",
//   usuario: "ana.garcia",
//   dominio: "empresa.com",
//   tipo: "Trabajo",
//   nombre: "Ana García",
//   valido: true
// }

// Crear múltiples correos parseados
const correos = [
  "[email protected]",
  "[email protected]",
  "[email protected]"
].map(email => parseCorreo(email, { valido: true }));

console.log(correos);

📊 Esquema de Datos

✅ Campo Obligatorio

| Campo | Tipo | Validación | Descripción | | ------- | -------- | ------------------------------- | ---------------------------------- | | correo | String | Required, trim, formato email | Dirección de correo electrónico |

⚙️ Campos Opcionales

| Campo | Tipo | Validación/Enum | Defecto | Descripción | | ------------ | --------- | ------------------------ | ---------- | ------------------------------------- | | tipo | String | Min 1 char, personalizable | "Personal" | Clasificación (Trabajo/Personal) | | nombre | String | Max 100 chars | - | Nombre de la persona | | usuario | String | Max 64 chars, lowercase | - | Parte antes del @ (usuario) | | dominio | String | Max 255 chars, lowercase | - | Parte después del @ (dominio) | | valido | Boolean | true/false | false | Formato de correo válido | | verificado | Boolean | true/false | false | Correo verificado por el usuario |

🏷️ Clasificaciones Personales

enum ClasificacionCorreo {
  TRABAJO = "Trabajo",   // 🏢 Correo laboral
  PERSONAL = "Personal", // 👤 Correo personal
}

💡 Ejemplos de Datos

📧 Correo Personal (Completo)

const correoCompleto: ICorreo = {
  correo: "[email protected]",
  tipo: "Personal",
  nombre: "Ana García",
  usuario: "ana.garcia",
  dominio: "gmail.com",
  valido: true,
  verificado: true,
};

🏢 Correo de Trabajo

const correoTrabajo: ICorreo = {
  correo: "[email protected]",
  tipo: "Trabajo",
  nombre: "Juan Pérez",
  usuario: "jperez",
  dominio: "empresa.com.pe",
  valido: true,
  verificado: false,
};

🔄 Correo Temporal

const correoTemporal: ICorreo = {
  correo: "[email protected]",
  tipo: "Temporal",
  nombre: "Usuario Temporal",
  usuario: "temp.user",
  dominio: "10minutemail.com",
  valido: true,
  verificado: false,
};

🏫 Correo Educativo

const correoEducativo: ICorreo = {
  correo: "[email protected]",
  tipo: "Educativo",
  nombre: "Estudiante Universitario",
  usuario: "estudiante",
  dominio: "universidad.edu",
  valido: true,
  verificado: true,
};

🔧 Configuración del Esquema

// Configuración Mongoose
{
  strict: false,        // Permite campos adicionales
  timestamps: true,     // createdAt, updatedAt automáticos
  _id: true             // Cada correo tiene su propio ID
}

// Configuración Joi
{
  stripUnknown: false,  // Mantiene campos extra
  allowUnknown: true,   // Permite propiedades no definidas
  convert: true,        // Conversión automática de tipos
  abortEarly: false     // Muestra todos los errores
}

📋 JSON Schema Standalone

El archivo correo.schema.json se genera automáticamente en cada build:

# Usar correo.schema.json directamente
curl -O https://gitlab.com/tiny.node/schema/correo/-/raw/main/dist/correo.schema.json

# Validar con cualquier validador JSON Schema
cat data.json | ajv validate -s correo.schema.json

🧪 Testing y Validación

// Test básico con Joi
import { JoiSchemaCorreo } from "@jysperu/schema-correo";

const testCases = [
  { correo: "[email protected]", valid: true },
  { correo: "", valid: false }, // Vacío
  { correo: "correo-invalido", valid: false }, // Sin @
  { correo: "test@", valid: false }, // Sin dominio
];

testCases.forEach((test) => {
  const result = JoiSchemaCorreo.validate(test);
  console.log(`${test.correo}: ${result.error ? "❌" : "✅"}`);
});

📦 Build y Distribución

# Construir el proyecto
npm run build

# Genera automáticamente:
# └── dist/
#     ├── correo.es.js       # ESM
#     ├── correo.cjs.js      # CommonJS
#     ├── correo.umd.js      # UMD
#     ├── *.d.ts             # TypeScript definitions
#     └── correo.schema.json # JSON Schema

🔗 Enlaces y Recursos

• 📘 Repositorio: GitLab - schema-correo
• 🐛 Issues: Reportar problemas
• 📦 npm: @jysperu/schema-correo
• 📚 Documentación Joi: @jysperu/joi-spanish
• 🏢 JYS Perú: www.jys.pe

📄 Licencia

MIT License - Consulta el archivo LICENSE para detalles completos.

MIT License - Copyright (c) 2025 JYS Perú

Desarrollado con ❤️ por JYS Perú