Referência de Funções CEL

Referência completa de todas as funções integradas disponíveis nas expressões CEL do AutoTalk. As funções estão organizadas por categoria.

---

Core

get(obj, path, default?)

Acessa com segurança uma propriedade aninhada através de um caminho pontilhado.

get(client, "address.city")                  // "São Paulo"
get(client, "address.zip", "00000-000")      // retorna o padrão se ausente
get(null, "name")                            // null
get(step(0), "data.results.0.title")         // caminho profundo com índice de array

Param	Tipo	Descrição
obj	any	Objeto a acessar (seguro para null)
path	string	Caminho pontilhado (ex: "a.b.c")
default	any	Valor retornado se o caminho estiver ausente (padrão: null)

has(obj, path?)

Verifica se um valor ou caminho aninhado existe e não é null/undefined.

has(client, "email")        // true se client.email estiver definido
has(myVar)                  // true se myVar não for null/undefined
has(obj, "a.b.c")           // true se o caminho completo resolver para não-null

coalesce(...vals)

Retorna o primeiro valor não-null e não-undefined. Variádica (aceita 2+ argumentos).

coalesce(client.nickname, client.name, "Guest")   // o primeiro não-null vence
coalesce(0, 42)                                    // 0 (não é null!)
coalesce(false, true)                              // false (não é null!)
coalesce("", "fallback")                           // "" (não é null!)

Semântica de verificação de null

coalesce() ignora apenas null e undefined. Valores como 0, false e "" são válidos e retornados.

now()

Retorna a data/hora atual.

now()                                    // data/hora atual
format_datetime(now(), "YYYY-MM-DD")     // "2024-01-15"

present(val)

Verifica se um valor está significativamente presente. Retorna false para null, undefined, strings vazias/somente espaços e arrays vazios. Números e booleanos são sempre considerados presentes.

present(client.email)         // true se for string não vazia
present("")                   // false
present("   ")                // false (somente espaços)
present(0)                    // true
present([])                   // false
present([1, 2])               // true

Substitui padrões verbosos

present(x) substitui o padrão comum size(trim(coalesce(x, ""))) > 0.

blank(val)

Inverso de present(). Retorna true para null, undefined, strings vazias/somente espaços e arrays vazios.

blank(client.email)           // true se for null ou vazio
blank("hello")                // false
blank(0)                      // false

---

Utilitários

pluck(arr, path)

Extrai uma propriedade de cada objeto em um array.

pluck(clients, "name")                     // ["Alice", "Bob", "Carol"]
pluck(tools, "tool.function.name")         // caminho profundo suportado

slice(arr, start, end?)

Fatia um array com segurança. Retorna [] para entradas que não são arrays. Suporta índices negativos.

slice(results, 0, 5)         // primeiros 5 itens
slice(results, -3)            // últimos 3 itens
slice(results, 1, -1)         // todos exceto o primeiro e o último
slice(null, 0, 2)             // [] (seguro para não-arrays)

defaults(obj, fallbacks)

Mescla valores de fallback em um objeto para chaves que são null/undefined. Mesclagem superficial.

defaults(response, {"status": "unknown", "retryable": false})
// Preenche status e retryable somente se forem null/undefined em response

Semântica de verificação de null

Assim como coalesce(), apenas valores null/undefined são substituídos. 0, false e "" são mantidos.

url_params(base, params)

Constrói uma URL com parâmetros de query. Ignora valores null e vazios. Codifica automaticamente.

url_params("https://api.example.com/search", {"q": query, "page": 1, "lang": null})
// "https://api.example.com/search?q=hello&page=1" (lang ignorado)

truncate(str, maxLen, suffix?)

Trunca uma string até um comprimento máximo com um sufixo opcional.

truncate("Hello World", 5)              // "Hello"
truncate("Hello World", 8, "...")        // "Hello..."
truncate(null, 10)                       // "" (seguro para null)
truncate("Hi", 100)                      // "Hi" (sem necessidade de truncar)

Param	Tipo	Descrição
str	any	Valor a truncar (convertido para string, null retorna "")
maxLen	number	Comprimento máximo do resultado (incluindo o sufixo)
suffix	string	Adicionado quando truncado (padrão: "")

dica

O sufixo é incluído dentro de maxLen: truncate("Hello World", 8, "...") retorna "Hello..." (8 caracteres).

tpl(template, vars)

Interpolação simples de string. Substitui marcadores {key} por valores de um objeto.

tpl("Hello {name}!", {"name": "Alice"})                    // "Hello Alice!"
tpl("*{title}*\n{domain}\n{url}", article)                 // texto formatado do artigo
tpl("{address.city}, {address.country}", client)            // suporte a caminho pontilhado
tpl("Hi {name}", {"name": null})                           // "Hi " (null → vazio)

Param	Tipo	Descrição
template	string	String de template com marcadores {key}
vars	object	Objeto com valores para interpolar

join_present(separator, ...values)

Junta valores com um separador, ignorando valores em branco. Usa as mesmas regras de present(): null, strings vazias/somente espaços e arrays vazios são ignorados. 0 e false são mantidos.

join_present(", ", "Alice", "Bob", "Carol")       // "Alice, Bob, Carol"
join_present(" - ", title, null, author)           // "Title - Author" (null ignorado)
join_present(" ", "Hello", "", "World")            // "Hello World" (vazio ignorado)
join_present(" | ", 0, false, "text")              // "0 | false | text" (0/false mantidos)

Substitui concatenação condicional

join_present(" - ", prefix, text) substitui o padrão (present(prefix) ? prefix + " - " : "") + text.

encode_uri(str)

Codifica uma string para URL.

encode_uri("hello world")    // "hello%20world"

format_currency(n, currency, locale?)

Formata um número como moeda.

format_currency(1234.5, "USD", "en-US")    // "$1,234.50"
format_currency(99.9, "BRL", "pt-BR")      // "R$ 99,90"

---

String

CEL inclui funções de string integradas. A maioria funciona tanto no estilo receptor quanto no estilo função:

"hello".contains("ell")      // true (estilo receptor)
contains("hello", "ell")     // true (estilo função)

Função	Descrição	Exemplo
contains(str, sub)	Verifica se a string contém a substring	"hello".contains("ell")
startsWith(str, prefix)	Verifica prefixo	"hello".startsWith("he")
endsWith(str, suffix)	Verifica sufixo	"hello".endsWith("lo")
split(str, sep)	Divide em array	split("a,b,c", ",") → ["a","b","c"]
lowerAscii(str)	Minúsculas	lowerAscii("HELLO") → "hello"
upperAscii(str)	Maiúsculas	upperAscii("hello") → "HELLO"
trim(str)	Remove espaços	trim(" hi ") → "hi"
substring(str, start, end?)	Extrai substring	substring("hello", 1, 4) → "ell"
replace(str, old, new)	Substitui ocorrências	replace("aab", "a", "x") → "xxb"
indexOf(str, sub)	Primeiro índice da substring	indexOf("hello", "l") → 2
lastIndexOf(str, sub)	Último índice da substring	lastIndexOf("hello", "l") → 3
charAt(str, index)	Caractere no índice	charAt("hello", 0) → "h"
join(list, sep?)	Junta array em string	join(["a","b"], ",") → "a,b"

---

Math

Função	Descrição	Exemplo
math_add(a, b)	Adição	math_add(5, 3) → 8
math_subtract(a, b)	Subtração	math_subtract(10, 3) → 7
math_multiply(a, b)	Multiplicação	math_multiply(4, 3) → 12
math_divide(a, b)	Divisão	math_divide(10, 3) → 3.333...
math_round(n, decimals?)	Arredondamento	math_round(3.456, 2) → 3.46
math_floor(n)	Piso	math_floor(3.7) → 3
math_ceil(n)	Teto	math_ceil(3.1) → 4
math_abs(n)	Valor absoluto	math_abs(-5) → 5
math_pow(base, exp)	Potência	math_pow(2, 3) → 8
math_sqrt(n)	Raiz quadrada	math_sqrt(16) → 4
math_max(arr)	Máximo	math_max([1,5,3]) → 5
math_min(arr)	Mínimo	math_min([1,5,3]) → 1
math_mean(arr)	Média	math_mean([1,2,3]) → 2
math_median(arr)	Mediana	math_median([1,2,10]) → 2
math_clamp(val, min, max)	Restringe ao intervalo	math_clamp(15, 0, 10) → 10

math_clamp(val, min, max)

Restringe um número dentro de um intervalo.

math_clamp(page, 1, 100)     // garante que page está entre 1 e 100
math_clamp(-5, 0, 10)        // 0 (abaixo do mínimo)
math_clamp(15, 0, 10)        // 10 (acima do máximo)

---

DateTime

Função	Descrição
now()	Data/hora atual
format_datetime(d, fmt, tz?)	Formata uma data/hora. Formatos: "DD/MM/YYYY", "YYYY-MM-DD HH:mm:ss", "HH:mm"
add_datetime(d, n, unit)	Adiciona tempo. Unidades: "years", "months", "days", "hours", "minutes", "seconds"
diff_datetime(d1, d2, unit)	Diferença entre duas datas/horas
zoned_datetime(d, tz)	Converte para fuso horário
is_before(d1, d2)	d1 antes de d2?
is_after(d1, d2)	d1 depois de d2?
is_between(d, start, end)	d entre start e end?

---

JSON

Função	Descrição
json_parse(str)	Converte string JSON em objeto
json_stringify(obj)	Serializa objeto em string JSON

---

BSON / ObjectId

Função	Descrição
object_id()	Gera uma nova string ObjectId
object_id_is_valid(id)	Verifica se a string é um ObjectId válido
object_id_to_string(id)	Converte ObjectId em string

---

Específicas de Workflow

Estas funções estão disponíveis apenas em expressões de workflow e agentes (não em CEL de formulários).

step(N)

Acessa a saída do passo N do workflow (indexado a partir de 0).

step(0)                      // objeto completo de saída do passo
step(0).data                 // payload de dados do passo
step(0).status               // código de status HTTP (para passos HTTP)

step_ok(N)

Verifica se o passo N foi concluído com sucesso. Retorna true quando executionContext.status é "completed" E o status HTTP é 200 (ou null para passos não-HTTP).

// Antes: verboso
get(step(0), "executionContext.status") == "completed" && (get(step(0), "status") == null || get(step(0), "status") == 200)

// Depois: uma chamada de função
step_ok(0)

step_data(N, path?, default?)

Obtém dados do passo N em um caminho pontilhado opcional. Retorna o padrão (ou null) se ausente.

// Antes
get(step(0), "data.title", null)

// Depois
step_data(0, "title")
step_data(0, "results.0.name", "Unknown")
step_data(1, "choices.0.message.content")

step_error(N)

Obtém informações de erro de um passo que falhou. Retorna {code, user_message, retryable} ou null.

// Antes
coalesce(get(step(0), "executionContext.safeError.code"), "UNKNOWN")

// Depois
step_error(0)                          // {code: "TIMEOUT", user_message: "...", retryable: true}
get(step_error(0), "code", "UNKNOWN")  // "TIMEOUT"

step_has_content(N, path)

Verifica se o passo N foi concluído com sucesso E possui dados presentes (não-null, não-vazio) no caminho dado. Combina step_ok(N) && present(step_data(N, path)) em uma única chamada.

// Antes: duas verificações
step_ok(0) && present(step_data(0, "articles"))

// Depois: uma chamada de função
step_has_content(0, "articles")

getContext()

Obtém o objeto de contexto de execução do workflow.

getTool(name)

Obtém o resultado de uma ferramenta a partir do contexto.

getRoot()

Obtém o contexto raiz do workflow.