It has been almost seven years since we first announced our Node.js SDK. Since then, the SDK has drastically evolved, but so has the JavaScript language as a whole. These days, developers love the simplicity of the new features that modern-day JavaScript brings to the table, such as Promises or the await and async functions. To keep up with standards, we have rewritten the SDK to use those new features by default. With our latest rebuild, it meant that we needed to release a new major version with breaking changes, but we hope you agree it was worth it! You can still use callbacks, but you would need to callbackify the methods yourself.

The text 'Upgraded Node.js SDK' in front of a grid of offset dots.

New features

  • New Promise API that is easier to use
  • Allows uploading Streams, strings and more
  • TypeScript definitions
  • Improved error handling and retry logic
  • Easier to debug and read internal async code
  • Numerous bugfixes and improvements

Because this release contains breaking API changes, we have taken the opportunity to also do some major refactoring and stabilization to our SDK. We tried to keep the API similar to the previous version, but there are a few changes you need to be aware of.

Breaking changes

  • All previous callback-accepting methods now return a promise and do not accept a callback.

  • Requires Node v10 or newer.

  • replayAssembly(opts) changed to replayAssembly(assemblyId, params) (previously assemblyId was a key inside opts):

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

  • replayAssemblyNotification(opts) changed to replayAssemblyNotification(assemblyId, params) (previously assemblyId was a key inside opts):

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

  • deleteAssembly renamed to cancelAssembly to reflect the underlying API's terminology.

  • Removed the undocumented fields option (directly under createAssembly(opts)). Please use the fields key inside params instead.

  • Changed createAssembly progress callbacks:

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

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

    Also, view the readme.

  • Increase default request timeout from 5 to 60 seconds.

  • Now returns from waitForCompletion with the Assembly result instead of throwing an unknown error if result.ok is ASSEMBLY_CANCELED or REQUEST_ABORTED.

  • Replaced constructor options useSsl and service with endpoint:

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

// Now:
endpoint: 'https://api2.transloadit.com'

Declarative createAssembly

addFile and addStream have been removed and are instead part of createAssembly:

// Before:
transloadit.addFile('file1', '/path/to/file')
...
transloadit.createAssembly({ ... })

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

// Before:
transloadit.addStream('file2', process.data.stdin)
...
transloadit.createAssembly({ ... })

// Now:
transloadit.createAssembly({
  uploads: {
    file2: process.data.stdin,
    ...
  },
  ...
})

Auto retry logic

  • RATE_LIMIT_REACHED now only automatically retries five times. The previous retry logic was overly aggressive: it used to retry on almost all errors, even unrecoverable ones, e.g., INVALID_FILE_META_DATA.
  • Will no longer automatically retry if assembly_url == null or assembly_ssl_url == null. Will instead throw a TransloaditClient.InconsistentResponseError.

Errors

Errors thrown by the SDK have changed:

  • When an unsuccessful HTTP response code is received, the error will now be a TransloaditClient.HTTPError object (used to be an ordinary Error object) with an additional transloaditErrorCode property (when relevant).
  • Error messages have been improved.
  • Error property error has been renamed to transloaditErrorCode.
  • Error property assembly_id has been renamed to assemblyId.
  • All other properties from the Transloadit JSON response are no longer added directly to the Error object but can instead be found in HTTPError.response?.body, e.g., catch (err) { err.response?.body?.assembly_id }. Note that err.response will be undefined for non-server errors.
  • Will now also await ASSEMBLY_REPLAYING status in waitForCompletion.
  • Assemblies with an error status (assembly.error, but return HTTP 200) will also result in an error thrown when calling replayAssembly to make it consistent with createAssembly.
  • When result.ok happens to be undefined, an Unkown error for createTemplate and editTemplate is no longer thrown.
  • HTTP 404 responses from the server now throw a TransloaditClient.HTTPError (previously 404 gave a successful result).

That's all folks!

Check out the following documentation and examples to get up and running with our new and improved Node.js SDK v3! We hope you'll be able to put this announcement to good use, and we can't wait to see how it helps your projects. And as always, if you have any feedback, let us know!