n8n-nodes-smart-switch

Nó customizado para n8n que funciona como um switch inteligente: avalia condições configuráveis sobre os dados de entrada e roteia cada item para a saída ✅ true ou ❌ false.

Como funciona um Nó n8n (teoria)

Estrutura básica

Um nó n8n é uma classe TypeScript que implementa INodeType. Ela possui dois componentes:

| Parte | Responsabilidade | |---|---| | description | Define como o nó aparece no editor: nome, ícone, campos do usuário, entradas e saídas | | execute() | Lógica que roda quando o nó é acionado no workflow |

export class MeuNo implements INodeType {
  description: INodeTypeDescription = {
    displayName: 'Meu Nó',
    name: 'meuNo',
    inputs: [NodeConnectionType.Main],
    outputs: [NodeConnectionType.Main],
    properties: [ /* campos do usuário */ ],
  };

  async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]> {
    const items = this.getInputData(); // ← dados vindo do nó anterior
    // ... processa ...
    return [items];                    // ← envia para a saída
  }
}

Tipos de campos (properties)

| Tipo | Descrição | |---|---| | string | Texto livre | | number | Número | | boolean | Checkbox (sim/não) | | options | Dropdown com opções fixas | | fixedCollection | Lista de grupos de campos (permite N itens) | | collection | Grupo expansível de configurações avançadas |

Múltiplas saídas

Para ter mais de uma saída (como true/false), basta declarar múltiplos outputs e retornar um array com um array por saída:

outputs: [NodeConnectionType.Main, NodeConnectionType.Main],
outputNames: ['✅ true', '❌ false'],

// No execute():
return [trueItems, falseItems]; // índice 0 → true, índice 1 → false

Smart Switch – Como usar

Instalação

Em n8n self-hosted:

# Na pasta do seu n8n (ou container)
cd ~/.n8n/custom
npm install n8n-nodes-smart-switch
# Reinicie o n8n

Via Docker (docker-compose.yml):

environment:
  - N8N_CUSTOM_EXTENSIONS=/home/node/.n8n/custom
volumes:
  - ./custom-nodes:/home/node/.n8n/custom

Para desenvolvimento local:

git clone https://github.com/seu-usuario/n8n-nodes-smart-switch
cd n8n-nodes-smart-switch
npm install
npm run build
npm link
cd ~/.n8n/custom && npm link n8n-nodes-smart-switch

Configuração do nó

1. Combinar condições com

• AND → todas as condições precisam ser verdadeiras
• OR → basta uma condição ser verdadeira

2. Condições

Adicione quantas condições quiser. Cada uma possui:

| Campo | O que preencher | |---|---| | Campo de Entrada | Nome da chave no JSON (ex: price, user.name) | | Operador | Como comparar (ver tabela abaixo) | | Valor Esperado | O que esperar (não aparece para operadores de tipo/existência) |

Operadores disponíveis

| Operador | Descrição | Exemplo | |---|---|---| | = igual a | Igualdade exata | status = ativo | | ≠ diferente de | Diferença | tipo ≠ admin | | > maior que | Numérico | price > 100 | | >= maior ou igual a | Numérico | age >= 18 | | < menor que | Numérico | score < 50 | | <= menor ou igual a | Numérico | peso <= 70 | | contém (texto) | Substring | email contém @gmail | | não contém (texto) | Substring negado | nome não contém teste | | começa com | Prefixo | codigo começa com BR- | | termina com | Sufixo | arquivo termina com .pdf | | regex | Expressão regular | cpf regex ^\d{11}$ | | existe | Não é null/undefined | endereco existe | | não existe | É null/undefined | deletedAt não existe | | é número | Verificação de tipo | valor é número | | é texto | Verificação de tipo | nome é string | | é booleano | Verificação de tipo | ativo é booleano | | é array | Verificação de tipo | tags é array |

3. Opções Avançadas

| Opção | Descrição | |---|---| | Case-insensitive | Ignora maiúsculas/minúsculas em comparações de texto | | Incluir detalhes da avaliação | Adiciona campo _smartSwitch no JSON de saída com o resultado de cada condição (útil para debug) |

Exemplos de uso

Exemplo 1 – Filtrar pedidos acima de R$200

Campo: total
Operador: >= maior ou igual a
Valor: 200

→ Itens com total >= 200 saem pela saída ✅ true → Demais saem pela saída ❌ false

Exemplo 2 – Verificar se e-mail é do Gmail

Campo: email
Operador: contém (texto)
Valor: @gmail.com

Exemplo 3 – Múltiplas condições (AND)

Condição 1: status = ativo
Condição 2: age >= 18
Condição 3: pais = Brasil
Combinar: AND

→ Apenas quem é ativo, maior de idade E do Brasil passa para ✅ true

Exemplo 4 – Campos aninhados

{ "user": { "address": { "city": "São Paulo" } } }

Campo: user.address.city
Operador: = igual a
Valor: São Paulo

Saída com debug ativado

Quando a opção "Incluir detalhes da avaliação" está ativa, o item de saída recebe um campo extra:

{
  "_smartSwitch": {
    "result": true,
    "combineWith": "AND",
    "conditions": [
      { "field": "total", "operator": "gte", "expected": "200", "actual": 350, "passed": true },
      { "field": "status", "operator": "equal", "expected": "ativo", "actual": "ativo", "passed": true }
    ]
  }
}

Estrutura de arquivos

n8n-nodes-smart-switch/
├── nodes/
│   └── SmartSwitch/
│       └── SmartSwitch.node.ts   ← Código principal do nó
├── dist/                          ← Código compilado (gerado pelo build)
├── package.json
├── tsconfig.json
└── README.md

Publicar na comunidade n8n

npm run build
npm publish --access public

O nó aparecerá automaticamente no marketplace da comunidade n8n após revisão.