Cogfy Data Exchange

Uma biblioteca TypeScript para definição e execução de fluxos de navegação fortemente tipados.

Visão Geral

O cogfy-data-exchange permite definir fluxos (flows) baseados em telas (screens) com:

• Tipagem forte em tempo de compilação
• Controle de navegação entre telas
• Inferência automática de dados de entrada e saída
• Engine simples para execução (createFlow)

A ideia central é transformar um JSON de fluxo em uma máquina de estados tipada.

Conceitos

Flow

Um flow descreve:

• routing_model: quais telas podem navegar para quais
• screens: quais dados cada tela recebe/retorna

const flow = {
  routing_model: {
    SCREEN_A: ['SCREEN_B', 'SCREEN_C'],
    SCREEN_B: ['SCREEN_D'],
    SCREEN_C: ['SCREEN_D'],
    SCREEN_D: []
  },
  screens: [
    { id: 'SCREEN_A', data: { name: { type: 'string' } } },
    { id: 'SCREEN_B', data: { age: { type: 'number' } } },
    { id: 'SCREEN_C', data: { isActive: { type: 'boolean' } } },
    {
      id: 'SCREEN_D',
      data: {
        profile: {
          type: 'object',
          properties: {
            name: { type: 'string' },
            age: { type: 'number' }
          }
        }
      }
    }
  ]
} as const

Convenção de nomenclatura do trigger

Os triggers de navegação devem seguir a convenção screen.{SCREEN_ID}. Por exemplo, para SCREEN_A, o trigger seria screen.SCREEN_A.

Uso

1. Criar o flow

import { createFlow } from 'cogfy-data-exchange'

2. Definir handlers

const engine = createFlow(flow, {
  SCREEN_A: async (data) => {
    // data: { name: string }

    return {
      screen: 'SCREEN_B',
      data: { age: 30 }
    }
  },

  SCREEN_B: async (data) => {
    return {
      screen: 'SCREEN_D',
      data: {
        profile: { name: 'John', age: 20 }
      }
    }
  },

  SCREEN_C: async (data) => {
    return {
      screen: 'SCREEN_D',
      data: {
        profile: { name: 'Jane', age: 25 }
      }
    }
  },

  SCREEN_D: async () => {
    throw new Error('Fim do fluxo')
  }
})

3. Executar o flow

const result = await engine.dispatch('screen.SCREEN_A', { name: 'John' })

// result:
// {
//   screen: 'SCREEN_B' | 'SCREEN_C'
//   data: ...
// }

Inferência de Tipos

A biblioteca infere automaticamente os seguintes aspectos:

Entrada do handler

SCREEN_A → { name: string }

Próximas telas possíveis

SCREEN_A → 'SCREEN_B' | 'SCREEN_C'

Dados da próxima tela

SCREEN_B → { age: number }

Garantias de Tipo

A biblioteca garante em tempo de compilação:

• Navegação restrita às telas válidas definidas no routing_model
• Formato correto do campo data em cada transição
• Implementação obrigatória de todos os handlers
• Tipos sempre sincronizados com a definição do flow

Exemplos Inválidos

Navegação inválida

// Erro de tipo: SCREEN_D não é uma transição permitida a partir de SCREEN_A
return {
  screen: 'SCREEN_D',
  data: {}
}

Data inválido

// Erro de tipo: age deve ser do tipo number
return {
  screen: 'SCREEN_B',
  data: { age: 'wrong' }
}