🍄 Pitufo

Cron scheduler ligero, robusto y sin dependencias para Node.js.
Olvídate de configuraciones complejas. Pitufo hace que programar tareas sea un juego de niños.

✨ Características

• Cero Dependencias: Mantiene tu node_modules ligero como una pluma.
• Sintaxis Simplificada: Sistema de 4 campos intuitivo (segundo minuto hora día).
• Operadores Potentes: Soporte completo para intervalos (*/n) y rangos (n-m).
• Persistencia Opcional: Guarda tareas en disco para sobrevivir a reinicios.
• API Minimalista: Funciones simples y claras para controlar todo.
• 100% Testeado: Suite completa de tests profesionales con Jest.

🚀 Instalación

npm install pitufo

📚 Uso Rápido

Tareas en Memoria (Simples)

import { cron, start, stop } from 'pitufo'

// Tarea recurrente: Cada 10 segundos
cron('*/10 * * *', () => {
    console.log('🔄 Ejecutando cada 10 segundos...')
})

// Tarea específica: A las 12:00 todos los días
cron('0 0 12 *', () => {
    console.log('🌞 ¡Es mediodía!')
})

// Rango: Cada segundo entre el segundo 0 y el 30
cron('0-30 * * *', () => {
    console.log('⏱️ Primera mitad del minuto')
})

// Iniciar el motor
start()

// Detener cuando sea necesario
// stop()

Tareas Persistentes (Avanzado)

Las tareas persistentes se guardan en pitufo.json y sobreviven a reinicios del servidor.

import { addJob, removeJob, register, start } from 'pitufo'

// 1. Registrar handlers para acciones
register('send-email', async (params) => {
    console.log(`📧 Enviando email a ${params.to}`)
    // Tu lógica de envío de email aquí
})

register('backup-db', async (params) => {
    console.log(`💾 Haciendo backup de ${params.database}`)
    // Tu lógica de backup aquí
})

// 2. Agregar tareas persistentes
const emailJobId = addJob({
    expr: '0 0 9 *', // Todos los días a las 9:00
    action: 'send-email',
    params: { to: '[email protected]', subject: 'Daily Report' },
})

const backupJobId = addJob({
    expr: '0 0 2 *', // Todos los días a las 2:00 AM
    action: 'backup-db',
    params: { database: 'production' },
})

// 3. Iniciar el scheduler
start()

// 4. Remover tareas cuando sea necesario
// removeJob(emailJobId)

📖 Guía de Sintaxis

Pitufo utiliza una sintaxis optimizada de 4 campos:

segundo minuto hora día

Campos

| Posición | Campo | Valores | Descripción | | :------: | :---------- | :------ | :----------------------------- | | 1 | Segundo | 0-59 | El segundo exacto. | | 2 | Minuto | 0-59 | El minuto exacto. | | 3 | Hora | 0-23 | La hora del día (formato 24h). | | 4 | Día | 1-31 | El día del mes. |

Operadores

| Operador | Ejemplo | Descripción | | :------: | :------------ | :---------------------------------------------------------------------- | | * | * * * * | Siempre. Coincide con cualquier valor. | | */n | */5 * * * | Intervalo. Se ejecuta cada n unidades (ej: cada 5 segundos). | | n-m | 10-20 * * * | Rango. Se ejecuta en todos los valores entre n y m (inclusive). | | n | 30 * * * | Valor Exacto. Se ejecuta solo cuando el valor coincide exactamente. |

Ejemplos de Expresiones

'* * * *' // Cada segundo
'*/30 * * *' // Cada 30 segundos
'0 */5 * *' // Cada 5 minutos (en el segundo 0)
'0 0 * *' // Cada hora en punto
'0 0 9-17 *' // Cada hora de 9 AM a 5 PM
'0 30 14 1' // A las 2:30 PM el día 1 de cada mes

🛠️ API Reference

Tareas en Memoria

cron(expresion, callback)

Registra una nueva tarea en memoria (no persiste entre reinicios).

• expresion string: La cadena de configuración (ej: "*/5 * * *").
• callback function: La función que se ejecutará cuando coincida el tiempo.

cron('*/10 * * *', () => {
    console.log('Ejecutando cada 10 segundos')
})

Tareas Persistentes

register(actionType, handler)

Registra un handler para un tipo de acción específico.

• actionType string: Nombre único de la acción.
• handler function(params): Función async que se ejecutará. Recibe params como argumento.

register('my-action', async (params) => {
    console.log('Ejecutando acción con:', params)
})

addJob(config)

Agrega una tarea persistente que se guarda en pitufo.json.

• config object:
  • expr string: Expresión cron (requerido).
  • action string: Tipo de acción registrada (requerido).
  • params object: Parámetros para el handler (opcional).
  • id string: ID personalizado (opcional, se genera automáticamente si no se proporciona).

Retorna: string - El ID del job creado.

const jobId = addJob({
    expr: '0 0 12 *',
    action: 'send-notification',
    params: { message: 'Hora de almorzar!' },
})

removeJob(id)

Elimina una tarea persistente por su ID.

• id string: El ID del job a eliminar.

removeJob(jobId)

Control del Scheduler

start()

Inicia el bucle del planificador. Pitufo comenzará a verificar las tareas cada segundo.

Nota: Si llamas a start() múltiples veces, solo la primera tendrá efecto.

start()

stop()

Detiene el planificador inmediatamente. Ninguna tarea se ejecutará hasta que vuelvas a llamar a start().

stop()

📁 Persistencia

Las tareas creadas con addJob() se guardan automáticamente en un archivo pitufo.json en el directorio de trabajo actual:

{
    "jobs": [
        {
            "id": "abc-123",
            "expr": "0 0 9 *",
            "action": "send-email",
            "params": { "to": "[email protected]" },
            "active": true
        }
    ]
}

Al reiniciar tu aplicación, Pitufo cargará automáticamente estas tareas y las programará de nuevo.

🧪 Testing

El proyecto incluye una suite completa de tests profesionales:

# Ejecutar tests
npm test

# Ejecutar linter
npm run lint

# Formatear código
npm run format

# Build
npm run build

📦 Publicación

El paquete está configurado para publicar solo los archivos esenciales:

• dist/ - Código compilado (ESM y CJS)
• README.md - Documentación
• LICENSE - Licencia MIT

Los archivos de desarrollo (src/, __tests__/, etc.) no se incluyen en el paquete npm.

🤝 Contribuyendo

¡Las contribuciones son bienvenidas! Si encuentras un error o tienes una idea para mejorar Pitufo:

1. Haz fork del repositorio
2. Crea una rama para tu feature (git checkout -b feature/amazing-feature)
3. Haz commit de tus cambios (git commit -m 'Add amazing feature')
4. Push a la rama (git push origin feature/amazing-feature)
5. Abre un Pull Request

Por favor, asegúrate de que los tests pasen antes de enviar tu PR:

npm test

📄 Licencia

Este proyecto está bajo la licencia MIT. Consulta el archivo LICENSE para más detalles.