機能と使いやすさを向上した Node.js SDK v3 を公開
Node.js SDK を初めて発表してから、まもなく 7 年になります。その間に SDK は大きく進化しましたが、JavaScript 自体も同様です。現在では、Promises や await、async 関数など、モダンな JavaScript の新機能がもたらすシンプルさが開発者に支持されています。こうした標準に対応するため、これらの新機能をデフォルトで使うよう SDK を書き直しました。今回の再構築に伴い、破壊的変更を含む新しいメジャーバージョンの公開が必要になりましたが、それだけの価値があったと感じていただければ幸いです。コールバックも引き続き使えますが、各メソッドを自身で callbackify する必要があります。

新機能
- より使いやすい新しい Promise API
Streams、stringsなどのアップロードに対応- TypeScript の型定義
- エラー処理と再試行ロジックの改善
- デバッグしやすく読みやすい内部の非同期コード
- 多数のバグ修正と改善
このリリースには API の破壊的変更が含まれるため、この機会に SDK の大規模なリファクタリングと安定性の向上にも取り組みました。API はできるだけ以前のバージョンに近づけていますが、いくつか注意が必要な変更点があります。
破壊的変更
-
以前はコールバックを受け取っていたメソッドはすべて Promise を返すようになり、コールバックを受け取らなくなりました。
-
Node v10 以降が必要です。
-
replayAssembly(opts)をreplayAssembly(assemblyId, params)に変更しました(以前はassemblyIdがopts内のキーでした)。-replayAssembly(opts, callback) +await replayAssembly(assemblyId, params) -
replayAssemblyNotification(opts)をreplayAssemblyNotification(assemblyId, params)に変更しました(以前はassemblyIdがopts内のキーでした)。-replayAssemblyNotification(opts, callback) +await replayAssemblyNotification(assemblyId, params) -
基盤となる API の用語に合わせて、
deleteAssemblyをcancelAssemblyに改名しました。 -
ドキュメントに記載のなかった
fieldsオプション(createAssembly(opts)直下)を削除しました。代わりにfieldsキーをparams内で使ってください。 -
createAssemblyの進捗コールバックを変更しました。// Before: createAssembly({ params: { ... }, fields: { field1: 'val' }, }, callback, progressCb) // Now: await createAssembly({ params: { fields: { field1: 'val' }, }, onUploadProgress, onAssemblyProgress, })readme も参照してください。
-
リクエストのデフォルトのタイムアウトを
5秒から60秒に延長しました。 -
waitForCompletionは、result.okがASSEMBLY_CANCELEDまたはREQUEST_ABORTEDの場合、不明なエラーをスローする代わりに Assembly の結果を返すようになりました。 -
constructorのオプションuseSslとserviceをendpointに置き換えました。// Before: useSsl: true, service: 'api2.transloadit.com' // Now: endpoint: 'https://api2.transloadit.com'
宣言的な createAssembly
addFile と addStream は削除され、代わりに 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.
})
自動再試行ロジック
RATE_LIMIT_REACHEDの自動再試行は5 回までに制限されました。以前の再試行ロジックは過剰で、INVALID_FILE_META_DATAなどの回復不能なエラーも含め、ほぼすべてのエラーで再試行していました。assembly_url == nullまたはassembly_ssl_url == nullの場合は、自動再試行しなくなりました。代わりにTransloadit.InconsistentResponseErrorをスローします。
エラー
SDK がスローするエラーを変更しました。
- 成功を示さない HTTP レスポンスコードを受信した場合、エラーは従来の通常の Error オブジェクトではなく、Transloadit.HTTPError オブジェクトになり、該当する場合は transloaditErrorCode プロパティが追加されます。
- エラーメッセージを改善しました。
ErrorのプロパティerrorをtransloaditErrorCodeに改名しました。Errorのプロパティassembly_idをassemblyIdに改名しました。- Transloadit の JSON レスポンスに含まれるその他のプロパティはすべて、
Errorオブジェクトに直接追加されなくなりました。代わりにHTTPError.response?.body内で参照できます。例:catch (err) { err.response?.body?.assembly_id }。なお、サーバー以外のエラーではerr.responseはundefinedになります。 ASSEMBLY_REPLAYINGステータスもwaitForCompletion内で待機するようになりました。- エラーステータス(
assembly.error、ただし HTTP 200 を返す)の Assembly も、replayAssemblyの呼び出し時にエラーをスローするようになり、createAssemblyと動作が統一されました。 result.okが未定義の場合に、createTemplate と editTemplate でUnkown errorがスローされなくなりました。- サーバーからの HTTP 404 レスポンスは、
Transloadit.HTTPErrorをスローするようになりました(以前は 404 でも成功として扱われていました)。
今回のお知らせは以上です!
以下のドキュメントとサンプルを参考に、新しく改良された Node.js SDK v3 を使い始めてみてください!今回のお知らせが役立ち、プロジェクトに貢献できることを楽しみにしています。いつものように、ご意見がありましたら、ぜひお聞かせください!
