Lançamento do novo SDK Node.js v3: aprimorado e fácil de usar

Mikael Finstad

Desenvolvedor · Noruega · Mostrar biografia

Já se passaram quase sete anos desde que anunciamos pela primeira vez nosso SDK Node.js. Desde então, o SDK evoluiu drasticamente, mas a linguagem JavaScript como um todo também evoluiu. Hoje em dia, os desenvolvedores adoram a simplicidade dos novos recursos que o JavaScript moderno oferece, como Promises ou as funções await e async. Para acompanhar os padrões, reescrevemos o SDK para usar esses novos recursos por padrão. Com essa reconstrução mais recente, precisamos lançar uma nova versão principal com mudanças incompatíveis, mas esperamos que você concorde que valeu a pena! Você ainda pode usar callbacks, mas precisaria aplicar o callbackify⁠ aos métodos por conta própria.

Novos recursos

• Nova API de Promise, mais fácil de usar
• Permite fazer upload de Streams, strings e mais
• Definições de TypeScript
• Tratamento de erros e lógica de novas tentativas aprimorados
• Código assíncrono interno mais fácil de depurar e ler
• Diversas correções de bugs e melhorias⁠

Como esta versão contém mudanças incompatíveis na API, aproveitamos a oportunidade para também fazer uma grande refatoração e estabilização do nosso SDK. Tentamos manter a API parecida com a da versão anterior, mas há algumas mudanças das quais você precisa estar ciente.

Mudanças incompatíveis

• Todos os métodos que antes aceitavam callback agora retornam uma promise e não aceitam callback.

• Requer Node v10 ou mais recente.

• replayAssembly(opts) mudou para replayAssembly(assemblyId, params) (antes, assemblyId era uma chave dentro de opts):

  -replayAssembly(opts, callback)
  +await replayAssembly(assemblyId, params)
  

• replayAssemblyNotification(opts) mudou para replayAssemblyNotification(assemblyId, params) (antes, assemblyId era uma chave dentro de opts):

  -replayAssemblyNotification(opts, callback)
  +await replayAssemblyNotification(assemblyId, params)
  

• deleteAssembly foi renomeado para cancelAssembly para refletir a terminologia da API subjacente.

• A opção não documentada fields (diretamente em createAssembly(opts)) foi removida. Em vez disso, use a chave fields dentro de params.

• Os callbacks de progresso de createAssembly foram alterados:

  // Before:
  createAssembly({
    params: { ... },
    fields: { field1: 'val' },
  }, callback, progressCb)
  
  // Now:
  await createAssembly({
    params: {
      fields: { field1: 'val' },
    },
    onUploadProgress,
    onAssemblyProgress,
  })
  

  Veja também o readme⁠.

• O tempo limite padrão das requisições aumentou de 5 para 60 segundos.

• waitForCompletion agora retorna o resultado da Assembly em vez de lançar um erro desconhecido se result.ok for ASSEMBLY_CANCELED ou REQUEST_ABORTED.

• Em constructor, as opções useSsl e service foram substituídas por endpoint:

  // Before:
  useSsl: true,
  service: 'api2.transloadit.com'
  
  // Now:
  endpoint: 'https://api2.transloadit.com'
  

createAssembly declarativo

addFile e addStream foram removidos e agora fazem parte de createAssembly:

// Before:
transloadit.addFile('file1', '/path/to/file')
// Add other files as needed.
transloadit.createAssembly({ /* additional options */ })

// Now:
transloadit.createAssembly({
  files: {
    file1: '/path/to/file',
    // Other named files.
  },
  // Additional options.
})

// Before:
transloadit.addStream('file2', process.stdin)
// Add other streams as needed.
transloadit.createAssembly({ /* additional options */ })

// Now:
transloadit.createAssembly({
  uploads: {
    file2: process.stdin,
    // Other named streams.
  },
  // Additional options.
})

Lógica de novas tentativas automáticas

• RATE_LIMIT_REACHED agora faz novas tentativas automáticas apenas cinco vezes. A lógica anterior de novas tentativas era agressiva demais: ela tentava novamente em quase todos os erros, até nos irrecuperáveis, por exemplo, INVALID_FILE_META_DATA.
• Não fará mais novas tentativas automáticas se assembly_url == null ou assembly_ssl_url == null. Em vez disso, lançará um Transloadit.InconsistentResponseError.

Erros

Os erros lançados pelo SDK mudaram:

• Quando um código de resposta HTTP de falha é recebido, o erro agora será um objeto Transloadit.HTTPError (antes era um objeto Error comum) com uma propriedade adicional transloaditErrorCode (quando relevante).
• As mensagens de erro foram aprimoradas.
• Em Error, a propriedade error foi renomeada para transloaditErrorCode.
• Em Error, a propriedade assembly_id foi renomeada para assemblyId.
• Todas as outras propriedades da resposta JSON da Transloadit não são mais adicionadas diretamente ao objeto Error, mas podem ser encontradas em HTTPError.response?.body, por exemplo, catch (err) { err.response?.body?.assembly_id }. Observe que err.response será undefined para erros que não vêm do servidor.
• Agora também aguarda o status ASSEMBLY_REPLAYING em waitForCompletion.
• Assemblies com status de erro (assembly.error, mas que retornam HTTP 200) também resultarão no lançamento de um erro ao chamar replayAssembly, para manter a consistência com createAssembly.
• Quando result.ok estiver indefinido, um Unkown error para createTemplate e editTemplate não é mais lançado.
• Respostas HTTP 404 do servidor agora lançam um Transloadit.HTTPError (antes, um 404 retornava um resultado bem-sucedido).

Isso é tudo, pessoal!

Confira a documentação⁠ e os exemplos⁠ para começar a usar nosso novo e aprimorado SDK Node.js v3! Esperamos que você aproveite bem este anúncio e mal podemos esperar para ver como ele ajuda seus projetos. E, como sempre, se você tiver algum feedback, fale com a gente!