Files SDK: یک API واحد برای همه استوریجها
جاوااسکریپت
نود جیاسخلاصهٔ کاملتر
ایده اصلی Files SDK اینه که کار با سرویسهای ذخیرهسازی مختلف رو پشت یه API واحد و ساده پنهان کنه. بهجای اینکه برای هر ارائهدهندهای کد مخصوص خودش رو بنویسی، یه مجموعه متد ثابت داری: upload، download، head، exists، delete، copy، move، list و url. همین شکل ثابت روی S3 و هر استوریج سازگار با S3 (مثل R2، MinIO، DigitalOcean Spaces و Backblaze)، گوگل کلاد، آژور، Vercel Blob، فایلسیستم محلی و حتی Dropbox کار میکنه.
هسته جابهجایی بین ارائهدهندهها هم همین adapterهاست. تو فقط import مربوط به adapter رو عوض میکنی (مثلاً files-sdk/s3 به files-sdk/r2 یا files-sdk/gcs) و بقیه کدت دستنخورده میمونه:
import { Files } from "files-sdk";
import { s3 } from "files-sdk/s3";
const files = new Files({ adapter: s3({ bucket: "uploads" }) });
await files.upload("avatars/abc.png", file, { contentType: "image/png" });
const got = await files.download("avatars/abc.png");یه نکته خوب طراحی اینه که ورودی و خروجیها بر پایه استانداردهای وب هستن: بدنه فایل میتونه Blob، File، ReadableStream، Uint8Array، ArrayBuffer یا رشته باشه. اینجوری نوعهای مخصوص هر ارائهدهنده وارد کد خودت نمیشن. متد exists هم فقط وقتی false برمیگردونه که ارائهدهنده بگه فایل پیدا نشد؛ خطاهای احراز هویت و دسترسی و شبکه همچنان throw میشن تا با نبودِ فایل قاطی نشن.
وقتی با یه فایل مشخص زیاد سروکار داری، میتونی با files.file(key) یه handle بسازی که به همون کلید قفله و متدهای upload، exists، head، url و delete رو مستقیم روش صدا بزنی. این handle فقط یه لایه نازک روی همون متدهای adaptere، پس adapterها لازم نیست چیز اضافهای پیاده کنن.
هر adapter یه entry point جداست، پس tree-shakeable هست و فقط چیزی که import میکنی توی باندل میاد. SDKهای اصلی هر ارائهدهنده هم optional peer dependency هستن؛ یعنی فقط همونایی رو نصب میکنی که واقعاً استفاده میکنی. اگه adapterی رو بدون نصب peer مربوطه import کنی، Node با خطای ERR_MODULE_NOT_FOUND بهت میگه کدوم پکیج کمه.
یه قابلیت تازهتر هم اینه که Files SDK میتونه نمونه پیکربندیشدهت رو بهصورت ابزار آماده در اختیار SDKهای هوش مصنوعی بذاره؛ فعلاً Vercel AI SDK، API و Agents SDK مربوط به OpenAI و Claude Agent SDK پشتیبانی میشن. همه اینها از همون عملیات فایل و همون پیشفرضهای تأیید استفاده میکنن، پس مدلها میتونن از همون سطح یکدست، باکت رو مرور و (در صورت اجازه) دستکاری کنن.
نکات کلیدی:
- یه API واحد و کوچیک برای کار با S3، GCS، آژور، Vercel Blob، فایلسیستم محلی و Dropbox
- جابهجایی بین ارائهدهندهها فقط با عوضکردن import مربوط به adapter
- ورودی/خروجی بر پایه استانداردهای وب (Blob، ReadableStream و ...)؛ بدون نشتِ نوعهای مخصوص هر ارائهدهنده
- adapterها tree-shakeable و SDK هر ارائهدهنده optional peer dependency هست
- امکان ارائه باکت بهصورت ابزار آماده برای SDKهای هوش مصنوعی مثل Vercel AI SDK و OpenAI و Claude
