الإعدادات

يُدمج الإعداد من افتراضيات العميل وخيارات كل استدعاء عبر mergeConfig (انظر قواعد الدمج أدناه). للصورة الكاملة للمسار والميزات الجديدة راجع الميزات ومسار الطلب.

OpenFetchConfig (الطلب)

العنوان وسلسلة الاستعلام

• url — مطلق أو نسبي (مع baseURL).
• baseURL — يُسبق للمسارات غير المطلقة.
• params — كائن عادي يُسلسل كسلسلة استعلام (يمكن استبدال المسلسل بـ paramsSerializer).

الطريقة والجسم

• method — طريقة HTTP؛ المساعدات تضبطها تلقائياً.
• data — الحمولة المنطقية: بعد خطافات transformRequest، تُسلسل الكائنات (ما عدا FormData، URLSearchParams، Blob، ArrayBuffer، المصفوفات المشاهَدة) كـ JSON؛ يُضبط content-type على application/json إن كان ناقصاً.
• body — جسم fetch الخام عند عدم استخدام data بنفس الطريقة؛ يستخدم dispatch قيمة data إن وُجدت وإلا body.

الرؤوس والمصادقة

• headers — Record<string, string> (تُطبَّع المفاتيح إلى أحرف صغيرة داخلياً للطلب الصادر).
• auth — { username, password } → Authorization: Basic ….
• withCredentials: true — يضبط credentials: 'include' ما لم يُضبط credentials صراحة.

المهلات والإلغاء

• timeout — بالمللي ثانية؛ يُدمج مع signal. إن انتهت المهلة الداخلية أولاً → ERR_TIMEOUT؛ إلغاء المستخدم على signal → ERR_CANCELED.
• signal — AbortSignal خارجي؛ يُدمج مع مهلة الإلغاء.

معالجة الاستجابة

• responseType — "json" | "text" | "arraybuffer" | "blob" | "stream".
  إن وُجد، يستنتج JSON من Content-Type: application/json، وإلا يُقرأ كنص.
• validateStatus — (status: number) => boolean. الافتراضي: 200–299. إن رجع false، يُرمى OpenFetchError برمز ERR_BAD_RESPONSE مع إرفاق الاستجابة.
• throwHttpErrors — يُستخدم فقط عند عدم تعيين validateStatus: مثل Ky (false لا يرمي على حالة HTTP؛ دالة ترجع true تعني «ارمِ لهذه الحالة»). إن وُجد validateStatus يُتجاهل throwHttpErrors.
• jsonSchema — Standard Schema اختياري على JSON المحلّل بعد نجاح الحالة؛ الفشل → SchemaValidationError (قبل transformResponse).
• init — مصفوفة (config) => void متزامنة على الإعداد المدمج قبل معترضات الطلب.

مدخل Request

• client.request(Request, تجاوزات?) — يدمج عنوان الطلب والطريقة والرؤوس والجسم والإشارة مع الافتراضيات ثم التجاوزات.

التحويلات

• transformRequest — مصفوفة (data, headers) => unknown تُنفَّذ بالترتيب قبل بناء جسم fetch.
• transformResponse — مصفوفة (data) => T على الاستجابات الناجحة بعد التحليل.

الوسيط وإعادة المحاولة وتلميحات التخزين المؤقت

• middlewares — مصفوفة دوال وسيط (تُلحق بالافتراضيات).
• retry — دمج سطحي لخيارات createRetryMiddleware (افتراضيات + لكل طلب).
• memoryCache — تجاوزات لكل طلب لوسيط التخزين المؤقت: ttlMs، staleWhileRevalidateMs، skip.

مريحة الاستخدام

• unwrapResponse — عند true، تُرجع get/post/… data فقط بدلاً من OpenFetchResponse الكامل. مفيد لـ RSC.

تمرير RequestInit

تُمرَّر هذه الحقول إلى fetch:
cache، credentials، integrity، keepalive، mode، redirect، referrer، referrerPolicy.

Node.js: dispatcher و HTTP/2 (allowH2)

على Node (وأي بيئة يقبل فيها fetch خيار dispatcher بأسلوب Undici):

• dispatcher — وكيل أو تجميعة خاص بك (مثلاً new Agent({ allowH2: true }) من حزمة undici التي تثبتها أنت). يمرّرها openFetch إلى fetch إن دعمتها البيئة.
• allowH2: true — اختصار: openFetch يحمّل undici ديناميكيًا ويبني Agent بـ allowH2: true ويمرّره كـ dispatcher.

undici ليست تبعية npm لـ @hamdymohamedak/openfetch. الحزمة المنشورة بلا dependencies وبلا peerDependencies ولا تُضمّن undici. ثبّتها فقط عند الحاجة: npm install undici. إذا كان allowH2: true وفشل import("undici")، يُرمى OpenFetchError برمز ERR_UNDICI_REQUIRED.

في المتصفحات والحواف حيث fetch يتجاهل dispatcher، لا تأثير لهذه الخيارات أو يتجاهلها المشغّل.

OpenFetchResponse

type OpenFetchResponse<T = unknown> = {
  data: T;
  status: number;
  statusText: string;
  headers: Record<string, string>;
  config: OpenFetchConfig;
};

سلوك الدمج (mergeConfig)

• المفاتيح على المستوى الأعلى: الإعداد الأحدث يغلب.
• headers: دمج سطحي؛ رؤوس الاستدعاء تغلب الافتراضيات.
• middlewares، transformRequest، transformResponse، init: تُلحق (الافتراضيات أولاً ثم الخاصة بالاستدعاء).
• retry، memoryCache: دمج سطحي لحقول الكائن؛ retry.onBeforeRetry و retry.onAfterResponse يُركّبان (الافتراضيات ثم لكل استدعاء).
• تُزال مفاتيح تلوث النموذج الأولي (__proto__، constructor، prototype) من الكائنات المدمجة والرؤوس / retry / memoryCache المتداخلة.

التالي

• الميزات ومسار الطلب
• المعترضات والوسيط