Melhores Práticas de TypeScript com DBOS

Guia para construir aplicações TypeScript confiáveis e tolerantes a falhas com fluxos de trabalho duráveis do DBOS.

Quando Usar

Consulte estas diretrizes quando:

• Adicionar DBOS a código TypeScript existente
• Criar fluxos de trabalho e etapas
• Usar filas para controle de concorrência
• Implementar comunicação de fluxo de trabalho (eventos, mensagens, streams)
• Configurar e iniciar aplicações DBOS
• Usar DBOSClient de aplicações externas
• Testar aplicações DBOS

Categorias de Regras por Prioridade

Regras Críticas

Instalação

Sempre instale a versão mais recente do DBOS:

npm install @dbos-inc/dbos-sdk@latest

Configuração e Lançamento do DBOS

Uma aplicação DBOS DEVE configurar e lançar o DBOS antes de executar quaisquer fluxos de trabalho:

import { DBOS } from "@dbos-inc/dbos-sdk";

async function main() {
  DBOS.setConfig({
    name: "my-app",
    systemDatabaseUrl: process.env.DBOS_SYSTEM_DATABASE_URL,
  });
  await DBOS.launch();
  await myWorkflow();
}

main().catch(console.log);

Estrutura de Fluxo de Trabalho e Etapa

Fluxos de trabalho são compostos por etapas. Qualquer função que execute operações complexas ou acesse serviços externos deve ser executada como uma etapa usando DBOS.runStep:

import { DBOS } from "@dbos-inc/dbos-sdk";

async function fetchData() {
  return await fetch("https://api.example.com").then(r => r.json());
}

async function myWorkflowFn() {
  const result = await DBOS.runStep(fetchData, { name: "fetchData" });
  return result;
}
const myWorkflow = DBOS.registerWorkflow(myWorkflowFn);

Restrições Chave

• NÃO chame, inicie ou enfileire fluxos de trabalho de dentro de etapas
• NÃO use threads ou concorrência não controlada para iniciar fluxos de trabalho - use DBOS.startWorkflow ou filas
• Fluxos de trabalho DEVEM ser determinísticos - operações não determinísticas vão para as etapas
• NÃO modifique variáveis globais de fluxos de trabalho ou etapas

Como Usar

Leia os arquivos de regras individuais para explicações detalhadas e exemplos:

references/lifecycle-config.md
references/workflow-determinism.md
references/queue-concurrency.md

Referências

• https://docs.dbos.dev/
• https://github.com/dbos-inc/dbos-transact-ts

Limitações

• Use esta habilidade apenas quando a tarefa corresponder claramente ao escopo descrito acima.
• Não trate a saída como substituta para validação específica do ambiente, testes ou revisão de especialistas.
• Pare e peça esclarecimentos se as entradas necessárias, permissões, limites de segurança ou critérios de sucesso estiverem ausentes.