Lanzamos el nuevo SDK v3 de Node.js: mejorado y fácil de usar

Mikael Finstad

Desarrollador · Noruega · Mostrar bio

Han pasado casi siete años desde que anunciamos por primera vez EN (English) nuestro SDK de Node.js. Desde entonces, el SDK ha evolucionado drásticamente, y el lenguaje JavaScript en su conjunto también. Hoy en día, a los desarrolladores les encanta la simplicidad de las nuevas funciones que aporta el JavaScript moderno, como las Promises o las funciones await y async. Para mantenernos al día con los estándares, hemos reescrito el SDK para que use esas nuevas funciones de forma predeterminada. Con esta última reconstrucción, eso significó que teníamos que publicar una nueva versión mayor con cambios incompatibles, ¡pero esperamos que estés de acuerdo en que valió la pena! Todavía puedes usar callbacks, pero tendrías que aplicar callbackify⁠ a los métodos tú mismo.

Nuevas funciones

• Nueva API de Promises más fácil de usar
• Permite subir Streams, strings y más
• Definiciones de TypeScript
• Mejor manejo de errores y lógica de reintentos
• Código asíncrono interno más fácil de depurar y leer
• Numerosas correcciones de errores y mejoras⁠

Dado que esta versión contiene cambios incompatibles en la API, hemos aprovechado la oportunidad para hacer también una refactorización y una estabilización importantes de nuestro SDK. Intentamos mantener la API similar a la de la versión anterior, pero hay algunos cambios que debes conocer.

Cambios incompatibles

• Todos los métodos que antes aceptaban un callback ahora devuelven una promesa y no aceptan un callback.

• Requiere Node v10 o posterior.

• replayAssembly(opts) cambió a replayAssembly(assemblyId, params) (antes assemblyId era una clave dentro de opts):

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

• replayAssemblyNotification(opts) cambió a replayAssemblyNotification(assemblyId, params) (antes assemblyId era una clave dentro de opts):

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

• deleteAssembly se renombró a cancelAssembly para reflejar la terminología de la API subyacente.

• Se eliminó la opción no documentada fields (directamente bajo createAssembly(opts)). Usa en su lugar la clave fields dentro de params.

• Se cambiaron los callbacks de progreso de createAssembly:

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

  Además, consulta el readme⁠.

• Se aumentó el tiempo de espera predeterminado de las solicitudes de 5 a 60 segundos.

• Ahora waitForCompletion devuelve el resultado de la Assembly en lugar de lanzar un error desconocido si result.ok es ASSEMBLY_CANCELED o REQUEST_ABORTED.

• Se reemplazaron en constructor las opciones useSsl y service por endpoint:

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

createAssembly declarativo

addFile y addStream se han eliminado y ahora forman 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 reintento automático

• RATE_LIMIT_REACHED ahora solo reintenta automáticamente cinco veces. La lógica de reintentos anterior era demasiado agresiva: reintentaba ante casi todos los errores, incluso los irrecuperables, por ejemplo, INVALID_FILE_META_DATA.
• Ya no reintentará automáticamente si assembly_url == null o assembly_ssl_url == null. En su lugar lanzará un Transloadit.InconsistentResponseError.

Errores

Los errores que lanza el SDK han cambiado:

• Cuando se recibe un código de respuesta HTTP no exitoso, el error ahora será un objeto Transloadit.HTTPError (antes era un objeto Error común) con una propiedad transloaditErrorCode adicional (cuando corresponda).
• Se han mejorado los mensajes de error.
• En Error, la propiedad error se ha renombrado a transloaditErrorCode.
• En Error, la propiedad assembly_id se ha renombrado a assemblyId.
• Todas las demás propiedades de la respuesta JSON de Transloadit ya no se agregan directamente al objeto Error, sino que se encuentran en HTTPError.response?.body, por ejemplo, catch (err) { err.response?.body?.assembly_id }. Ten en cuenta que err.response será undefined para los errores que no provienen del servidor.
• Ahora también esperará el estado ASSEMBLY_REPLAYING en waitForCompletion.
• Las Assemblies con un estado de error (assembly.error, pero que devuelven HTTP 200) también provocarán que se lance un error al llamar a replayAssembly, para que sea coherente con createAssembly.
• Cuando result.ok resulta ser undefined, ya no se lanza un Unkown error para createTemplate ni editTemplate.
• Las respuestas HTTP 404 del servidor ahora lanzan un Transloadit.HTTPError (antes un 404 daba un resultado exitoso).

¡Eso es todo, amigos!

¡Consulta la siguiente documentación⁠ y estos ejemplos⁠ para empezar a usar nuestro nuevo y mejorado SDK v3 de Node.js! Esperamos que puedas sacarle provecho a este anuncio, y estamos ansiosos por ver cómo ayuda a tus proyectos. Y como siempre, si tienes algún comentario, ¡dínoslo!