n8n-nodes-message-stack

Este es un nodo personalizado (custom node) para n8n que permite almacenar y gestionar mensajes en una cola/pila con funcionalidad de delay para acumular y procesar mensajes.

Características

• 📥 Push: Agregar mensajes a la pila
• 📤 Pop: Sacar mensajes de la pila
• 👁️ Peek: Ver mensajes sin removerlos
• 🚀 Flush: Procesar todos los mensajes acumulados
• 📊 Get Size: Obtener el número de mensajes en la pila
• 🗑️ Clear: Limpiar la pila
• ⏱️ Push with Delay: Acumular mensajes con tiempo de espera antes de procesarlos
• ⚡ Push, Wait and Flush: Todo en uno - Agrega, espera y devuelve mensajes en un solo nodo (NUEVO!)

¿Por qué usar este nodo?

Este nodo reemplaza la necesidad de usar múltiples nodos (Redis + Wait + Redis) para acumular mensajes antes de procesarlos. Es ideal para:

• Agrupar mensajes que llegan en ráfagas antes de procesarlos juntos
• Reducir la cantidad de llamadas a APIs externas agrupando requests
• Implementar rate limiting acumulando mensajes
• Crear buffers de mensajes para procesamiento batch

Instalación

Instalación en n8n Cloud o Self-hosted

1. Ve a Settings > Community Nodes
2. Selecciona Install
3. Ingresa n8n-nodes-message-stack
4. Acepta los riesgos y haz clic en Install

Instalación Manual

Si tienes una instalación local de n8n:

npm install n8n-nodes-message-stack

Uso

Ejemplo 1: Acumular Mensajes con Delay (TODO EN UNO - Método Más Simple) 🌟

Este es el caso de uso principal: acumular mensajes que llegan y procesarlos después de un tiempo, todo en un solo nodo.

Flujo de trabajo simplificado:

Webhook/Trigger → Message Stack (Push, Wait and Flush) → Process Messages

¡Solo necesitas 1 nodo! En lugar de usar Redis + Wait + Redis o múltiples nodos Message Stack.

Configuración:

1. Agrega el nodo Message Stack
2. Selecciona la operación Push, Wait and Flush
3. Configura:
   • Stack Name: my-messages
   • Delay (Seconds): 10 (tiempo de acumulación)
   • Return Format: Individual Items (cada mensaje como item separado)

¡Eso es todo! El nodo automáticamente:

1. Agregará el mensaje entrante a la pila
2. Esperará 10 segundos
3. Devolverá TODOS los mensajes acumulados durante esa espera
4. Limpiará la pila

Ventajas:

• ✅ Un solo nodo en lugar de 3-4 nodos
• ✅ No necesitas configurar Wait o Schedule
• ✅ No necesitas mantener sincronizados múltiples nodos
• ✅ Configuración más simple y clara

Ejemplo 1b: Método Tradicional (Múltiples Nodos)

Si prefieres tener control separado de cada paso:

Webhook/Trigger → Message Stack (Push with Delay) → Wait/Schedule → Message Stack (Flush) → Process Messages

Paso 1: Configurar el nodo para acumular mensajes

1. Agrega el nodo Message Stack
2. Selecciona la operación Push with Delay
3. Configura:
   • Stack Name: my-messages
   • Delay (Seconds): 10
   • Auto Flush on Delay: false

Paso 2: Esperar el tiempo configurado

1. Agrega un nodo Wait o Schedule

Paso 3: Procesar los mensajes acumulados

1. Agrega otro nodo Message Stack
2. Selecciona la operación Flush
3. Configura:
   • Stack Name: my-messages
   • Return Format: Individual Items

Ejemplo 2: Cola Simple (Push/Pop)

Para usar como una cola FIFO tradicional:

Producer → Message Stack (Push) → Consumer → Message Stack (Pop)

Ejemplo 3: Ver Mensajes sin Consumirlos

Message Stack (Peek) → Process/Display

Útil para monitorear qué hay en la cola sin remover mensajes.

Ejemplo 4: Verificar el Tamaño de la Cola

Message Stack (Get Size) → IF Node → (Si hay mensajes) → Message Stack (Flush)

Operaciones Disponibles

Push

Agrega mensajes a la pila. Todos los items de entrada se agregan a la pila.

Parámetros:

• Stack Name: Nombre de la pila (permite múltiples pilas independientes)

Output:

{
  "success": true,
  "operation": "push",
  "stackName": "my-stack",
  "messagesPushed": 5,
  "totalMessages": 10
}

Push with Delay

Agrega mensajes y configura un delay para procesamiento acumulado.

Parámetros:

• Stack Name: Nombre de la pila
• Delay (Seconds): Tiempo de espera para acumulación
• Auto Flush on Delay: Si debe hacer flush automático (actualmente solo informativo)

Output:

{
  "success": true,
  "operation": "pushWithDelay",
  "stackName": "my-stack",
  "messagesPushed": 3,
  "totalMessages": 8,
  "delaySeconds": 10,
  "autoFlush": true,
  "willFlushAt": "2024-01-15T10:30:00.000Z"
}

Push, Wait and Flush ⚡ (NUEVO!)

¡Operación todo-en-uno! Agrega mensajes a la pila, espera el tiempo configurado, y luego devuelve todos los mensajes acumulados. Reemplaza la necesidad de usar múltiples nodos.

Parámetros:

• Stack Name: Nombre de la pila
• Delay (Seconds): Tiempo de espera para acumulación
• Return Format:
  • Individual Items: Cada mensaje como item separado
  • Array: Todos los mensajes en un array

Comportamiento:

1. Agrega el mensaje entrante a la pila
2. Espera el tiempo configurado (el workflow se pausa)
3. Durante la espera, otros mensajes que lleguen a la misma pila también se acumulan
4. Al terminar el delay, devuelve TODOS los mensajes acumulados
5. Limpia la pila

Output (Individual): Devuelve los mensajes originales como items separados.

Output (Array):

{
  "messages": [...],
  "count": 15,
  "stackName": "my-stack",
  "operation": "pushWaitFlush",
  "messagesPushed": 1,
  "messagesReturned": 15,
  "delaySeconds": 10,
  "actualWaitTimeSeconds": 10.003
}

Nota Importante: Este nodo bloquea la ejecución durante el delay. Esto es ideal para webhooks o triggers que quieren acumular mensajes antes de procesarlos. Todos los mensajes que lleguen durante el delay se acumularán y devolverán juntos.

Pop

Remueve y devuelve mensajes de la pila (FIFO - First In, First Out).

Parámetros:

• Stack Name: Nombre de la pila
• Max Messages: Número máximo de mensajes a retornar (0 = todos)
• Return Format:
  • Individual Items: Cada mensaje como item separado
  • Array: Todos los mensajes en un array

Output (Individual): Devuelve los mensajes originales como items separados.

Output (Array):

{
  "messages": [...],
  "count": 5,
  "stackName": "my-stack"
}

Peek

Ver mensajes sin removerlos de la pila.

Parámetros: Mismos que Pop.

Flush

Devuelve todos los mensajes y limpia la pila.

Parámetros:

• Stack Name: Nombre de la pila
• Return Format: Individual o Array

Get Size

Obtiene información sobre el tamaño de la pila.

Output:

{
  "success": true,
  "operation": "size",
  "stackName": "my-stack",
  "size": 15,
  "lastActivity": "2024-01-15T10:25:00.000Z",
  "hasPendingTimeout": true
}

Clear

Elimina todos los mensajes de la pila.

Output:

{
  "success": true,
  "operation": "clear",
  "stackName": "my-stack",
  "messagesCleared": 10
}

Casos de Uso Avanzados

Agrupar Llamadas a API

Webhook (muchos eventos)
  → Message Stack (Push with Delay: 30s)
  → Schedule (cada 30s)
  → Message Stack (Flush)
  → API Call (procesa todos juntos)

Rate Limiting

Trigger
  → Message Stack (Push)
  → Schedule (cada 1 minuto)
  → Message Stack (Pop: max 100)
  → Process

Buffer de Mensajes con Condición

Message Stack (Push)
  → Schedule (cada 10s)
  → Message Stack (Get Size)
  → IF (size >= 50 o timeout)
  → Message Stack (Flush)
  → Process Batch

Notas Importantes

1. Almacenamiento en Memoria: Los mensajes se almacenan en memoria. Si reinicias n8n, perderás los mensajes acumulados.

2. Múltiples Stacks: Puedes tener múltiples pilas independientes usando diferentes nombres en Stack Name.

3. Timeouts: Los timeouts son informativos. Debes configurar tu flujo para ejecutar el flush cuando sea necesario.

4. Performance: Para grandes volúmenes de mensajes (>1000), considera usar Redis o una base de datos.

Desarrollo

Compilar el nodo

npm install
npm run build

Desarrollo con watch mode

npm run dev

Lint

npm run lint
npm run lintfix

Publicación (Para Maintainers)

Este paquete se publica automáticamente a npm usando GitHub Actions.

Guía completa de publicación: Ver PUBLISHING.md

Resumen rápido:

1. Actualiza la versión:

   npm version minor  # o patch/major

2. Crea y pushea el tag:

   git push origin main --tags

3. GitHub Actions publicará automáticamente a npm

Requisito: Configurar el secreto NPM_TOKEN en GitHub Settings (ver PUBLISHING.md)

Recursos

• Documentación oficial de n8n
• Crear nodos personalizados

Licencia

MIT

Autor

svy11211

Contribuciones

Las contribuciones son bienvenidas! Por favor abre un issue o pull request en GitHub.

Changelog

1.1.0

• NUEVO: Operación "Push, Wait and Flush" - Todo en uno para acumular, esperar y devolver mensajes en un solo nodo
• Mejora en la usabilidad: Ya no necesitas usar múltiples nodos para acumular mensajes
• Documentación mejorada con ejemplos más claros

1.0.0

• Release inicial
• Operaciones: Push, Pop, Peek, Flush, Get Size, Clear
• Push with Delay para acumulación de mensajes
• Soporte para múltiples stacks nombrados