Pular para o conteúdo principal

Action Engine

O que é Action Engine​

Action Engine é uma infraestrutura compartilhada para executar ações de negócio por meio de um contrato tipado.

DYONA define QUAL ação executar e COM QUAL contexto.
A aplicação consumidora decide COMO executá-la.

Action Engine não conhece fetch nem Axios, URLs, endpoints, JWT nem autenticação, backend nem regras de negócio. Essas decisões permanecem na aplicação consumidora.

DyonaAction​

type DyonaAction = {
  id: string;
  label: string;
  icon?: string;
  scope: 'global' | 'record';
  requiresParameters?: boolean;
};
  • global é executada sem exigir um record selecionado.
  • record é executada sobre um record e exige context.record.
  • requiresParameters indica que um objeto de parâmetros deve ser fornecido antes da execução. Isso é desenvolvido em Action Dialog.

DyonaActionContext​

type DyonaActionContext = {
  sourceId?: string;
  record?: Record<string, unknown>;
  values?: Record<string, unknown>;
  parameters?: Record<string, unknown>;
};

O contexto carrega as informações de que a aplicação precisa para executar uma ação. Uma ação record exige context.record; sourceId, values e parameters são contexto opcional fornecido por quem chama.

Executar uma ação​

Este exemplo completo usa uma ação de record Aprovar pedido. O executor apenas simula lógica da aplicação: não inventa backend nem endpoint.

import {
  executeDyonaAction,
  type DyonaActionExecutor,
} from '@typhonsoftware/dyona-form';

const action = {
  id: 'approve-order',
  label: 'Aprovar pedido',
  scope: 'record',
} as const;

const context = {
  sourceId: 'orders',
  record: {id: 1024, status: 'pending'},
};

const executor: DyonaActionExecutor = async ({context}) => {
  // A lógica de negócio da aplicação fica aqui.
  return {
    success: true,
    message: 'Pedido aprovado',
    data: {
      id: context.record?.id,
    },
  };
};

const result = await executeDyonaAction(action, context, executor);

Fluxo de execução​

DyonaAction
    +
DyonaActionContext
    ↓
executeDyonaAction()
    ↓
DyonaActionExecutor
    ↓
DyonaActionResult

Ações globais​

Uma ação global usa o mesmo contrato, mas não exige um record.

const globalAction = {
  id: 'generate-order-summary',
  label: 'Gerar resumo de pedidos',
  scope: 'global',
} as const;

const globalExecutor: DyonaActionExecutor = async () => ({
  success: true,
  message: 'Resumo de pedidos gerado',
  data: {totalOrders: 42},
});

await executeDyonaAction(
  globalAction,
  {sourceId: 'orders'},
  globalExecutor,
);

DyonaActionResult​

Em nível introdutório, um resultado de ação pode incluir:

  • success: se a ação teve êxito.
  • message: uma mensagem de resultado para a aplicação apresentar.
  • fieldErrors: mensagens de backend por campo, indexadas pelo nome do campo.
  • data: dados retornados específicos da aplicação.
  • refresh: destinos que podem precisar ser atualizados.

refresh e fieldErrors são explicados com mais detalhes em Action Result + Refresh. Quando este resultado é retornado por onSubmit ou um onAction customizado de DyonaForm, DyonaForm também apresenta o feedback correspondente de sucesso, erro geral e erro de campo.

Por que isso importa​

Os componentes atuais e futuros do DYONA podem reutilizar o mesmo contrato de ações sem se acoplarem a um backend. Cada aplicação consumidora mantém seu transporte, autenticação e lógica de negócio, compartilhando um limite de execução consistente.

Continue aprendendo​