DSL Tasks

DSL — Tasks

El sistema de tasks permite definir bloques reutilizables de lógica dentro del DSL YAML y ejecutarlos desde cualquier parte del flow.

Una task es, conceptualmente:

• Un nombre
• Un conjunto opcional de parámetros de entrada (params)
• Un conjunto opcional de valores de retorno (returns)
• Un flow (lista de nodos) que se ejecuta cuando la task es invocada

Para invocar una task se usa el nodo task dentro de flow.nodes, y para devolver resultados se usa el nodo return.

Ver también:

• Flow (nodos) (nodos task y return)
• DSL Reference (sección event.tasks)
• Comandos (catálogo: /cee tasks export)

---

Fuentes de tasks

CEE soporta dos orígenes de tasks:

1) Tasks dentro del evento (event.tasks)

Se definen dentro del YAML del evento. Solo están disponibles para ese evento.

event:
  id: "mi_evento"
  tasks:
    add:
      params:
        a: number
        b: number
      returns:
        sum: number
      flow:
        nodes:
          - return:
              sum: "= a + b"

2) Tasks globales (plugins/CustomEventEngine/tasks/*.yml)

CEE carga tasks globales desde archivos .yml en la carpeta del plugin:

• Ruta: plugins/CustomEventEngine/tasks/
• Estructura del archivo: una sección raíz tasks: con entradas por nombre.

Ejemplo plugins/CustomEventEngine/tasks/math.yml:

tasks:
  add:
    params:
      a: number
      b: number
    returns:
      sum: number
    flow:
      nodes:
        - return:
            sum: "= a + b"

Disponibilidad:

• Las tasks globales están disponibles para todos los eventos.
• Si un evento define una task con el mismo nombre que una global, la del evento tiene prioridad para ese evento.

---

Estructura de una task

description (opcional)

Texto libre para describir la intención de la task.

params (opcional)

Mapa paramName -> definición.

Formas soportadas:

1. Forma corta (solo tipo):

params:
  playerName: string
  amount: number

2. Forma completa:

params:
  amount:
    type: number
    required: true
    default: 1

Campos:

• type: string | number | boolean | array | object
• required: true|false (default: true)
• default: valor por defecto si el caller no lo provee (opcional)

Notas:

• Si required: true y no hay default, el caller debe proveer el parámetro en task.with.
• El valor de default se resuelve en runtime (acepta variables/expresiones, ver Variables).

returns (opcional)

Mapa returnName -> definición.

Formas soportadas:

1. Forma corta (solo tipo):

returns:
  sum: number
  ok: boolean

2. Forma completa:

returns:
  sum:
    type: number

Campos:

• type: string | number | boolean | array | object

flow / nodes

El cuerpo de la task es un flow estándar.

Se puede declarar como:

flow:
  nodes: [ ... ]

o, como atajo:

nodes: [ ... ]

Dentro del flow se pueden usar acciones, bucles, async, llamadas a otras tasks y return.

---

Invocación: nodo task

El nodo task se declara dentro de flow.nodes.

Forma corta

- task: "add"

Forma completa

- task:
    name: "add"
    with:
      a: 2
      b: 3
    into:
      sum: "result"
    max_depth: 64

Campos:

• name: nombre de la task (string).
• with: mapa de argumentos paramName -> value.
  • Los valores se resuelven en runtime, admitiendo:
    • Literales
    • {var} / ${var}
    • Expresiones MVEL con prefijo =
• into: mapa returnName -> variableDestino.
  • Si se declara, los retornos se escriben en variables cuando la task finaliza.
• max_depth: límite de profundidad de llamadas anidadas (default: 64).
  • Protege contra recursión infinita o composición excesiva.
• override: definición inline de una task para esta llamada (ver sección “Override”).

---

Retorno: nodo return

return finaliza la ejecución de la task actual y devuelve valores al caller.

- return:
    sum: "= a + b"
    ok: true

Comportamiento:

• Los valores del return se resuelven en runtime (variables/expresiones).
• Se aplica el mapeo task.into (si existe): cada returnName se copia a su variableDestino.
• Si la task termina sin ejecutar return, se considera retorno vacío (no escribe nada en into).

---

Override (redefinición por llamada)

override permite redefinir una task solo para un punto de llamada.

Esto es útil para variar comportamiento sin tocar la task global/base, o para especializar una task dentro de un flujo puntual.

Ejemplo:

- task:
    name: "base"
    with: { x: 1 }
    into: { out: "value" }
    override:
      description: "Versión local de base"
      params: { x: number }
      returns: { out: number }
      nodes:
        - return:
            out: "= x + 5"

Notas:

• El override puede incluir params, returns, flow/nodes.
• Durante la validación de carga, el override se valida como una task (nombres, params y retornos).

---

Composición y tareas anidadas

Una task puede llamar a otras tasks (y así componer lógica compleja).

Ejemplo:

event:
  tasks:
    add:
      params: { a: number, b: number }
      returns: { sum: number }
      nodes:
        - return: { sum: "= a + b" }
    add3:
      params: { x: number }
      returns: { sum: number }
      nodes:
        - task:
            name: "add"
            with: { a: "= x", b: 3 }
            into: { sum: "tmp" }
        - return:
            sum: "= tmp"

Control de recursión:

• En cada llamada se evalúa max_depth.
• Si se excede, el runtime se cancela con error.

---

Scope de variables durante una task

Cuando una task se invoca:

• Sus parámetros (params) se inyectan como variables en el contexto antes de ejecutar su flow.
• Al finalizar (por return o fin del flow), el runtime restaura el estado previo de esas variables.

Efecto práctico:

• Los parámetros actúan como un “scope” local de la task, evitando dejar basura en variables del evento.
• El mapeo into es el mecanismo recomendado para “sacar” resultados de una task.

---

Validación en carga (errores comunes)

CEE valida en el parseo/carga:

• Llamadas a tasks inexistentes.
• Parámetros desconocidos en with.
• Faltantes de parámetros requeridos (sin default).
• Retornos desconocidos en into.
• Variables destino vacías en into.
• max_depth inválido (< 1).

Si hay errores, el evento (o la task global) no se carga y se registran los motivos en consola.

---

Catálogo automático

Puedes exportar un catálogo de tasks (globales y por evento) a disco:

• Comando: /cee tasks export
• Archivo generado: plugins/CustomEventEngine/task-catalog.yml

Ver: Comandos.