Neues Node.js SDK v3 erscheint: verbessert & benutzerfreundlich

Mikael Finstad

Entwickler · Norwegen · Bio anzeigen

Es ist fast sieben Jahre her, dass wir unser Node.js SDK erstmals angekündigt EN (English) haben. Seitdem hat sich das SDK stark weiterentwickelt, aber auch die Sprache JavaScript als Ganzes. Heute schätzen Entwickler die Einfachheit der neuen Funktionen, die modernes JavaScript mitbringt, etwa Promises oder die Funktionen await und async. Um mit den Standards Schritt zu halten, haben wir das SDK so neu geschrieben, dass es diese neuen Funktionen standardmäßig nutzt. Unser jüngster Umbau bedeutete, dass wir eine neue Hauptversion mit Breaking Changes veröffentlichen mussten, aber wir hoffen, Sie stimmen uns zu, dass es sich gelohnt hat! Sie können weiterhin Callbacks verwenden, müssen die Methoden dann aber selbst mit callbackify⁠ umwandeln.

Neue Funktionen

• Neue Promise-API, die einfacher zu verwenden ist
• Ermöglicht das Hochladen von Streams, strings und mehr
• TypeScript-Definitionen
• Verbesserte Fehlerbehandlung und Retry-Logik
• Interner asynchroner Code lässt sich leichter debuggen und lesen
• Zahlreiche Bugfixes und Verbesserungen⁠

Da dieses Release Breaking Changes an der API enthält, haben wir die Gelegenheit genutzt, unser SDK zudem umfassend zu refactoren und zu stabilisieren. Wir haben versucht, die API ähnlich zur vorherigen Version zu halten, aber es gibt einige Änderungen, die Sie kennen sollten.

Breaking Changes

• Alle bisherigen Methoden, die einen Callback akzeptierten, geben jetzt ein Promise zurück und akzeptieren keinen Callback.

• Erfordert Node v10 oder neuer.

• replayAssembly(opts) wurde zu replayAssembly(assemblyId, params) geändert (zuvor war assemblyId ein Schlüssel innerhalb von opts):

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

• replayAssemblyNotification(opts) wurde zu replayAssemblyNotification(assemblyId, params) geändert (zuvor war assemblyId ein Schlüssel innerhalb von opts):

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

• deleteAssembly wurde in cancelAssembly umbenannt, um die Terminologie der zugrunde liegenden API widerzuspiegeln.

• Die undokumentierte Option fields (direkt unter createAssembly(opts)) wurde entfernt. Verwenden Sie stattdessen den Schlüssel fields innerhalb von params.

• Bei createAssembly wurden die Progress-Callbacks geändert:

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

  Sehen Sie sich außerdem die Readme⁠ an.

• Das Standard-Timeout für Requests wurde von 5 auf 60 Sekunden erhöht.

• waitForCompletion gibt jetzt das Ergebnis der Assembly zurück, anstatt einen unbekannten Fehler zu werfen, wenn result.ok den Wert ASSEMBLY_CANCELED oder REQUEST_ABORTED hat.

• Bei constructor wurden die Optionen useSsl und service durch endpoint ersetzt:

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

Deklaratives createAssembly

addFile und addStream wurden entfernt und sind stattdessen Teil von 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.
})

Automatische Retry-Logik

• RATE_LIMIT_REACHED wiederholt jetzt automatisch nur noch fünfmal. Die bisherige Retry-Logik war übermäßig aggressiv: Sie wiederholte bei fast allen Fehlern, selbst bei nicht behebbaren, z. B. INVALID_FILE_META_DATA.
• Wiederholt nicht mehr automatisch, wenn assembly_url == null oder assembly_ssl_url == null gilt. Stattdessen wird Transloadit.InconsistentResponseError geworfen.

Fehler

Die Fehler, die das SDK wirft, haben sich geändert:

• Wenn ein nicht erfolgreicher HTTP-Response-Code empfangen wird, ist der Fehler jetzt ein Transloadit.HTTPError-Objekt (zuvor war es ein gewöhnliches Error-Objekt) mit einer zusätzlichen Eigenschaft transloaditErrorCode (sofern relevant).
• Die Fehlermeldungen wurden verbessert.
• Bei Error wurde die Eigenschaft error in transloaditErrorCode umbenannt.
• Bei Error wurde die Eigenschaft assembly_id in assemblyId umbenannt.
• Alle anderen Eigenschaften aus der Transloadit-JSON-Antwort werden nicht mehr direkt zum Objekt Error hinzugefügt, sondern finden sich stattdessen in HTTPError.response?.body, z. B. catch (err) { err.response?.body?.assembly_id }. Beachten Sie, dass err.response bei Fehlern, die nicht vom Server stammen, undefined ist.
• Wartet jetzt auch auf den Status ASSEMBLY_REPLAYING in waitForCompletion.
• Assemblies mit einem Fehlerstatus (assembly.error, geben aber HTTP 200 zurück) führen beim Aufruf von replayAssembly ebenfalls zu einem geworfenen Fehler, damit dies konsistent mit createAssembly ist.
• Wenn result.ok zufällig undefined ist, wird Unkown error für createTemplate und editTemplate nicht mehr geworfen.
• HTTP-404-Antworten vom Server werfen jetzt Transloadit.HTTPError (zuvor lieferte 404 ein erfolgreiches Ergebnis).

Das war's, Leute!

Werfen Sie einen Blick auf die folgende Dokumentation⁠ und die Beispiele⁠, um mit unserem neuen und verbesserten Node.js SDK v3 durchzustarten! Wir hoffen, dass Sie diese Ankündigung gut nutzen können, und wir sind gespannt, wie sie Ihren Projekten hilft. Und wie immer gilt: Falls Sie Feedback haben, sagen Sie es uns!