sdkgen

Correção no CI.

Funcionalidades:

• Adicionado extra no Android (Kotlin). Ver #738.
• Adicionado suporte ao Flutter 3.3. Ver #741.
• Adicionado extras no Android (Kotlin). Ver #738.
• apiTestWrapper pode agora receber o contexto inicial.
• Suporte ao Node.js 14 removido.

Correções:

• Proibe valores repetidos nos enums. Ver #742.
• Obter nome do erro apropriadamente em JavaScript minificado. Ver #746.
• Documentação OpenAPI/Swagger segue mais corretamente a definição dos endpoints REST
• Corrige a codificação de data no JavaScript. Ver #749.
• Diversas outras pequenas correções.
• Atualizações de dependências.

Funcionalidades:

• Adicionado o tipo decimal para armazenar números monetários com precisão de casas decimais. Ver #724.
• Adicionado interceptadores de requisições no target Flutter. Ver #725.
• Suporte ao Node.js 18. Removido suporte ao Node.js 12 e 17. Versões 14, 16 e 18 são suportadas. Ver #703.
• Adicionado suporte ao Flutter 3 e removido suporte ao Flutter 2. Ver #704.
• Permite customizar o fingerprint do dispositivo no target Android. Ver #734.
• Suporte a compilar múltiplos arquivos em um único comando. Ver #690.
• Atualização de dependências.

Correções:

• Corrigido suporte a executar em serviços Serverless.
• Adicionado suporte ao tipo json em requisições REST com Swagger.
• Outras correções. Ver #684, #689.
• Correção na ordem dos argumentos na path de uma requisição REST. Ver #713.
• Ajustes no gerador do Flutter para produzir código livre de alertas. Ver #726, #733.

• Suporte a utilizar o sdkgen em serviços Serverless (como Google Cloud Functions ou AWS Lambda), ou junto a servidores Node.js existentes, como o Express.js. Para tal basta criar uma instância do SdkgenHttpServer como usual, e então registrar a propriedade handleRequest como função para receber requisições HTTP. Ver detalhes na documentação. Ver #678.
• Adicionado ctx.response.headers e ctx.response.statusCode para permitir modificar os headers e o status code da resposta de qualquer requisição, especialmente útil para requisições REST. Ver #676.
• Correções na validação de tipos quando mais de um tipo possui o mesmo nome em locais diferentes. Ver #672.
• Segundo argumento do SdkgenHttpServer agora é opcional quando o ExtraContext não é utilizado, simplificando o código quando injeção de dependência não é necessário.
• Adicionado suporte ao ES2022 com TypeScript. Ver #682.
• Melhoria no diálogo de "Sobre" do playground. Ver #683.
• Atualização de dependências.

As contribuições de 2 pessoas tornaram essa nova versão possível: @dgadelha e @lbguilherme.

Nenhuma alteração. Corrige a publicação do pacote fsharp-generator.

• Correção no uso do playground em produção.
• Correção no tratamento da marcação !secret utilizada em conjunto com a anotação @rest (#659).
• Atualização de dependências.

As contribuições de 4 pessoas tornaram essa nova versão possível: @dgadelha, @GuiBernal, @joshuapassos, e @lbguilherme.

Chegamos aqui com o sdkgen 2.0.0, após quase 1 ano de desenvolvimento, trazendo muitas melhorias e novidades, com poucas mudanças que podem impactar projetos. A expectativa é que a atualização possa ser aplicada na maioria dos projetos sem nenhuma mudança de código. É sempre recomendado que o servidor atualize primeiro, antes dos clientes. Vamos ao que temos de novidades:

Suporte ao Flutter 2 (sound null safety e Flutter Web)

O Flutter 2 foi lançado junto ao Dart 1.12 e trouxeram o suporte opcional a tipos nuláveis, uma evolução significativa. Uma boa parte do ecossistema já fez a migração e o sdkgen agora está construído da mesma maneira. Tanto o código gerado em Dart quanto o pacote sdkgen_runtime utilizam tipos nuláveis. Em complemento, Flutter Web é suportado, assim como o Flutter para Android e iOS, oferecendo as mesmas funcionalidades.

Um detalhe que facilita o uso nesta versão é que anteriormente o SDK tinha que ser inicializado dentro de um widget passando acesso ao BuildContext. Isso não é mais necessário e pode ser utilizado em qualquer lugar da aplicação, independente da UI.

Cliente nativo em iOS (experimental)

Um novo cliente nativo para iOS foi adicionado, junto ao gerador de código em Swift. Ele pode ser utilizado com o target swift_ios ou rxswift_ios no gerador. Nesta versão esse target já é funcional e suporta todos os recursos, no entanto ainda não foi testado o suficiente em produção. Em caso de problemas, por favor reporte. Com teste suficiente acontecendo, poderemos marcar como estável em uma das próximas versões.

Servidor em F# (experimental)

O suporte original para rodar sdkgen em .NET foi construído com base no .NET Core utilizando C#. Toda essa base foi reconstruída para dar espaço a uma nova versão em F#, muito mais moderna e possibilitando ser utilizada tanto em projetos F# quanto em C#. A implementação de métodos é fácil e direta, assim como acontece em Node.js, mantendo a mesma simplicidade. Atualmente os recursos base do sdkgen são suportados, mas alguns opcionais não são suportados por este target, como suporte a REST e a compatibilidade com versões legadas. Está sendo lançado como experimental pois ainda não foi testado o suficiente em produção. A expectativa é lançar como versão estável e completa no futuro próximo.

Novo Playground

O sdkgen possui um playgroud embutido desde a versão 1.0.0, possibilitando inspecionar uma API, conhecer as funções disponíveis e invocar elas com dados para testar. Agora estamos incluindo um novo playground, com suporte a:

• Explorar as funções existentes, junto com a documentação do que fazem e os tipos que recebem ou retornam.
• Ver como a função deve ser chamada nas linguagens suportadas pelo sdkgen.
• Chamar as funções, escrevendo os argumentos que deseja passar.
• Gerar e baixar o código gerado em todos os targets suportados sem precisar instalar nada.
• Utilizar o editor avançado, em que é possível escrever lógica em JavaScript chamando uma ou mais funções para executar diretamente em seu navegador.

O novo playground pode ser utilizado inclusive com API's que ainda não foram atualizadas para o sdkgen 2.0.0.

Acesse em: https://sdkgen.github.io/playground/ ou na rota /playground da sua API. É necessário que introspection esteja habilitado.

União de Tipos (experimental)

Em muitos casos é necessário que uma propriedade possa receber mais de um tipo de dado a depender da situação, por exemplo quando uma lista de eventos é retornada. Até então não havia uma boa forma de representar esses casos, mas agora o sdkgen suporta agregar dados adicionais no enum. Um exemplo de como isso pode ser utilizado:

type Event enum {
  info(msg: string)
  transaction(id: uuid, value: money, date: datetime, description: string)
  refund(id: uuid)
  ping
}

fn getEvents(): Event[]

Neste exemplo um Event pode ser qualquer um dos 4 tipos possíveis, a depender de qual seja, ele virá acompanhado de alguns dados adicionais. Com isso é possível expressar cenários muito mais complexos de API's, sem precisar fazer rodeios.

Atualmente esse modelo funciona em Node.js e na Web com TypeScript, mas ainda não está habilitado nos demais targets, por conta disso está marcado como experimental. Esperamos passar a fornecer em todas as linguagens no futuro.

Tipos Recursivos

Outro caso difícil de expressar é quando tipos precisam ser arbitrariamente recursivos. Por exemplo, observe o caso de comentários em uma postagem, sendo que um comentário pode ter outros comentários dentro. Agora é possível declarar assim:

type Post {
  body: string
  authorId: uuid
  comments: Comment[]
}

type Comment {
  body: string
  authorId: uuid
  comments: Comment[]
}

Neste caso comentários podem conter comentários quantas vezes for necessário, usando um array vazio para representar um comentário que não tem outros comentários dentro. Tipos recursivos podem ser utilizados junto a união de tipos também.

Esperamos com isso aumentar a expressividade da descrição da API, representando cenários reais e evitando que o tipo json precise ser utilizado.

Outras alterações

Todos os recursos marcados como depreciados nas versões anteriores foram removidos. Se eram utilizados no seu projeto, precisará atualizar.

Além disso foram aplicadas várias correções e melhorias internas, deixando o projeto mais estável como um todo.

Agradecimentos

As contribuições de 13 pessoas tornaram esse lançamento possível: @ahardmann, @danielpsantiago, @daniloapr, @davidcpires, @dgadelha, @elcioabrahao, @hofstede-matheus, @josecleiton, @joshuapassos, @lbguilherme, @manoellribeiro, @vhfmag, e @Yansb

• Correção do swagger, regressão causado na versão 1.5.0.
• Suporte ao tipo bigint no Playground e no Swagger.

Same as 1.6.0.

• Atualização de dependências.
• Suporte ao .NET 6.0.
• Agora é possivel o cliente enviar parâmetros extras em requisições. #378
• Novo hook no browser-client para intercepção de erros #428
• Torna os HTTP Headers case insensitive
• Remove console.error que estava aparecendo no runtime. #556

Correções:

• Correção no carregamento do /playground por conta de regressão causada pela versão 1.5.4 (#184).

Correções:

• Correção no recebimento de objetos retornados pela API no browser-runtime (#181).
• Correção no tratamento de rotas REST para que caso mais de uma rota encaixe com uma requisição, aquela que contém a maior quantidade de caracteres que não fazem parte dos argumentos seja escolhida (#179).
• Mudança no tratamento de rotas REST de forma que argumentos do tipo string dentra da path não possam mais conter o caracter / (#179).
• Validação de datas no browser-runtime e node-runtime de forma que uma data inválida não seja aceita (#180).
• Atualização de dependências.

Correção:

• Ajustado o tipo TypeDescription utilizado para tipagem dos clientes em Node e Web com respeito ao enums.

Esta release não inclui nenhuma alteração no comportamento durante execução.

Correção:

• O tipo de retorno das funções encode e decode do @sdkgen/node-runtime estava sendo incorretamente inferido quando o tipo possuia um enum. Essa tipagem foi corrigida.

Esta release não inclui nenhuma alteração no comportamento durante execução.

Nenhuma mudança.

Middlewares

Agora é possível adicionar múltiplos middlewares na configuração de uma API, possibilitando tomar ações a depender dos argumentos ou do retorno.

api.use(async (ctx, next) => {
  // Faça qualquer coisa com o `ctx` aqui.
  // O nome da função é `ctx.request.name` e os argumentos `ctx.request.args`.
  const reply = await next();
  // Faça qualquer coisa com a resposta aqui.
  return reply;
});

Os hooks anteriores de onRequestStart e onRequestEnd continuam funcionando, mas estão agora depreciados.

Você pode, por exemplo:

• Salvar os dados da requisição e resposta em um log;
• Medir estatísticas das requisições;
• Controlar rate limit;
• Bloquear ou redirecionar chamadas a depender da função e dos argumentos;
• Implementar cache;
• Implementar re-tentativa a depender de algum erro específico (chamando next mais de uma vez);
• Modificar o erro retornado (try/catch em volta do next).

Ver #161.

Outras mudanças

• Suporte ao Node.js 15 (#115).
• Configuração do eslint renovada e tipagem mais forte em todos os pacotes TypeScript (#166).
• Licença do projeto modificada para MIT (#167).
• Atualização de dependências.

Correções

• Correção no runtime do Flutter ao lançar erros do tipo SdkgenErrorWithData (#175).

Correções

• Gerador de código do Flutter com erros que contém dados (SdkgenErrorWithData) agora produzem código válido (#171).
• Gerador de código do Android agora utiliza SupervisorJob (#168).

Correções

• SdkgenErrorWithData não será mais importado pelo código gerado sem necessidade, evitando problemas com linter (#141).
• Correção na uso do WebpackManifestPlugin no playground.
• Correção no syntax highlighting no Visual Studio Code para error (#152).
• Correção no processamento do tipo money no Flutter (#153).
• Código duplicado removido (#155).
• Correção ao gerar classes de erro no Flutter (#160).
• Correção no processamento do tipo json no Flutter (#159).
• Atualização de dependências.

Correções

• Correção de regressão na versão 1.4.0 em que o brower-runtime não retornava o conteúdo da resposta em caso de sucesso.
• Suporte ao tipo primitivo email no Swagger gerado para funções @rest (#140).
• Correção de exemplo na documentação (#137).