Lancement du nouveau SDK Node.js v3 : amélioré et convivial

Mikael Finstad

Développeur · Norvège · Afficher la bio

Cela fait presque sept ans que nous avons annoncé pour la première fois notre SDK Node.js. Depuis, le SDK a considérablement évolué, tout comme le langage JavaScript dans son ensemble. Aujourd’hui, les développeurs apprécient la simplicité des nouvelles fonctionnalités qu’apporte le JavaScript moderne, comme les promesses ou les fonctions await et async. Pour suivre les standards, nous avons réécrit le SDK afin qu’il utilise ces nouvelles fonctionnalités par défaut. Cette refonte nous a obligés à publier une nouvelle version majeure comportant des changements incompatibles, mais nous espérons que vous conviendrez que cela en valait la peine ! Vous pouvez toujours utiliser des callbacks, mais il vous faudra « callbackifier »⁠ les méthodes vous-même.

Nouvelles fonctionnalités

• Nouvelle API Promise plus simple à utiliser
• Permet de téléverser des Streams, des strings et plus encore
• Définitions TypeScript
• Gestion des erreurs et logique de nouvelle tentative améliorées
• Code asynchrone interne plus facile à déboguer et à lire
• De nombreux correctifs et améliorations⁠

Comme cette version contient des changements incompatibles de l’API, nous en avons profité pour effectuer également une refonte majeure et une stabilisation de notre SDK. Nous avons essayé de garder une API similaire à la version précédente, mais il y a quelques changements dont vous devez tenir compte.

Changements incompatibles

• Toutes les méthodes qui acceptaient auparavant un callback renvoient désormais une promesse et n’acceptent plus de callback.

• Nécessite Node v10 ou une version plus récente.

• replayAssembly(opts) est remplacé par replayAssembly(assemblyId, params) (auparavant, assemblyId était une clé de opts) :

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

• replayAssemblyNotification(opts) est remplacé par replayAssemblyNotification(assemblyId, params) (auparavant, assemblyId était une clé de opts) :

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

• deleteAssembly est renommé en cancelAssembly pour refléter la terminologie de l’API sous-jacente.

• Suppression de l’option non documentée fields (directement sous createAssembly(opts)). Veuillez plutôt utiliser la clé fields dans params.

• Modification des callbacks de progression de createAssembly :

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

  Consultez également le fichier README⁠.

• Le délai d’expiration par défaut des requêtes passe de 5 à 60 secondes.

• Renvoie désormais depuis waitForCompletion le résultat de l’Assembly au lieu de lever une erreur inconnue si result.ok vaut ASSEMBLY_CANCELED ou REQUEST_ABORTED.

• Remplacement, dans constructor, des options useSsl et service par endpoint :

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

createAssembly déclaratif

addFile et addStream ont été supprimés et font désormais partie 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.
})

Logique de nouvelle tentative automatique

• RATE_LIMIT_REACHED ne réessaie désormais automatiquement que cinq fois. L’ancienne logique de nouvelle tentative était trop agressive : elle réessayait pour presque toutes les erreurs, même irrécupérables, par exemple INVALID_FILE_META_DATA.
• Le SDK ne réessaiera plus automatiquement si assembly_url == null ou assembly_ssl_url == null. Il lèvera plutôt une erreur Transloadit.InconsistentResponseError.

Erreurs

Les erreurs levées par le SDK ont changé :

• Lorsqu’un code de réponse HTTP d’échec est reçu, l’erreur sera désormais un objet Transloadit.HTTPError (auparavant un objet Error ordinaire) avec une propriété supplémentaire transloaditErrorCode (le cas échéant).
• Les messages d’erreur ont été améliorés.
• Error : la propriété error a été renommée en transloaditErrorCode.
• Error : la propriété assembly_id a été renommée en assemblyId.
• Toutes les autres propriétés de la réponse JSON de Transloadit ne sont plus ajoutées directement à l’objet Error, mais se trouvent désormais dans HTTPError.response?.body, par exemple catch (err) { err.response?.body?.assembly_id }. Notez que err.response vaudra undefined pour les erreurs qui ne proviennent pas du serveur.
• Attend désormais aussi le statut ASSEMBLY_REPLAYING dans waitForCompletion.
• Les Assemblies présentant un statut d’erreur (assembly.error, mais renvoyant HTTP 200) entraîneront aussi la levée d’une erreur lors de l’appel à replayAssembly, par cohérence avec createAssembly.
• Lorsque result.ok est indéfini, une erreur Unkown error n’est plus levée pour createTemplate et editTemplate.
• Les réponses HTTP 404 du serveur lèvent désormais une erreur Transloadit.HTTPError (auparavant, une réponse 404 donnait un résultat positif).

C’est tout pour aujourd’hui !

Consultez la documentation⁠ et les exemples⁠ suivants pour bien démarrer avec notre SDK Node.js v3, nouveau et amélioré ! Nous espérons que cette annonce vous sera utile, et nous avons hâte de voir comment elle aidera vos projets. Et comme toujours, si vous avez des retours, faites-le-nous savoir !