Merge pull request #9 from hamdymohamedak/feat/ky-parity-features

Feat/parity features

Author: hamdymohamedak

.vitepress/config.mts

@@ -38,6 +38,7 @@ type NavLabels = {
   pluginsFluent: string;
   interceptors: string;
   architecture: string;
+  featuresPipeline: string;
   retryCache: string;
   errorsSecurity: string;
 };
@@ -52,6 +53,7 @@ const LABELS: Record<Lang, NavLabels> = {
     pluginsFluent: "الإضافات والواجهة السلسة",
     interceptors: "المعترضات والوسيط",
     architecture: "البنية والداخلية",
+    featuresPipeline: "الميزات ومسار الطلب",
     retryCache: "إعادة المحاولة والتخزين المؤقت",
     errorsSecurity: "الأخطاء والأمان",
   },
@@ -64,6 +66,7 @@ const LABELS: Record<Lang, NavLabels> = {
     pluginsFluent: "Plugins y API fluida",
     interceptors: "Interceptores y middleware",
     architecture: "Arquitectura",
+    featuresPipeline: "Funciones y pipeline",
     retryCache: "Reintentos y caché",
     errorsSecurity: "Errores y seguridad",
   },
@@ -76,6 +79,7 @@ const LABELS: Record<Lang, NavLabels> = {
     pluginsFluent: "افزونه‌ها و API روان",
     interceptors: "قطع‌کننده‌ها و میان‌افزار",
     architecture: "معماری",
+    featuresPipeline: "ویژگی‌ها و خط لوله",
     retryCache: "تلاش مجدد و حافظهٔ نهان",
     errorsSecurity: "خطا و امنیت",
   },
@@ -88,6 +92,7 @@ const LABELS: Record<Lang, NavLabels> = {
     pluginsFluent: "Plugins et API fluent",
     interceptors: "Intercepteurs et middleware",
     architecture: "Architecture",
+    featuresPipeline: "Fonctionnalités et pipeline",
     retryCache: "Nouvelles tentatives et cache",
     errorsSecurity: "Erreurs et sécurité",
   },
@@ -100,6 +105,7 @@ const LABELS: Record<Lang, NavLabels> = {
     pluginsFluent: "प्लगइन और फ्लुएंट API",
     interceptors: "इंटरसेप्टर और मिडलवेयर",
     architecture: "Architecture",
+    featuresPipeline: "Features और pipeline",
     retryCache: "रीट्राई और कैश",
     errorsSecurity: "त्रुटियाँ और सुरक्षा",
   },
@@ -112,6 +118,7 @@ const LABELS: Record<Lang, NavLabels> = {
     pluginsFluent: "Plugin e API fluent",
     interceptors: "Intercettori e middleware",
     architecture: "Architettura",
+    featuresPipeline: "Funzionalità e pipeline",
     retryCache: "Retry e cache",
     errorsSecurity: "Errori e sicurezza",
   },
@@ -124,6 +131,7 @@ const LABELS: Record<Lang, NavLabels> = {
     pluginsFluent: "プラグインと Fluent API",
     interceptors: "インターセプターとミドルウェア",
     architecture: "アーキテクチャ",
+    featuresPipeline: "機能とパイプライン",
     retryCache: "リトライとキャッシュ",
     errorsSecurity: "エラーとセキュリティ",
   },
@@ -136,6 +144,7 @@ const LABELS: Record<Lang, NavLabels> = {
     pluginsFluent: "플러그인과 Fluent API",
     interceptors: "인터셉터와 미들웨어",
     architecture: "아키텍처",
+    featuresPipeline: "기능과 파이프라인",
     retryCache: "재시도와 캐시",
     errorsSecurity: "오류와 보안",
   },
@@ -148,6 +157,7 @@ const LABELS: Record<Lang, NavLabels> = {
     pluginsFluent: "Plugin û Fluent API",
     interceptors: "Interceptors û middleware",
     architecture: "Mîmarî",
+    featuresPipeline: "Taybetmendî û pipeline",
     retryCache: "Retry û cache",
     errorsSecurity: "Çewtî û ewlehî",
   },
@@ -162,6 +172,7 @@ const ROOT_LABELS: NavLabels = {
   pluginsFluent: "Plugins & fluent API",
   interceptors: "Interceptors & middleware",
   architecture: "Architecture & internals",
+  featuresPipeline: "Features & pipeline",
   retryCache: "Retry & cache",
   errorsSecurity: "Errors & security",
 };
@@ -193,6 +204,7 @@ function sidebarRoot() {
         { text: L.pluginsFluent, link: "/plugins-fluent" },
         { text: L.interceptors, link: "/interceptors-middleware" },
         { text: L.architecture, link: "/architecture" },
+        { text: L.featuresPipeline, link: "/features-pipeline" },
         { text: L.retryCache, link: "/retry-cache" },
         { text: L.errorsSecurity, link: "/errors-security" },
         { text: "AI assistants & skills", link: "/skills" },
@@ -224,6 +236,10 @@ function sidebarFor(lang: Lang) {
     { text: L.pluginsFluent, link: pluginsFluentLink },
     { text: L.interceptors, link: `${p}/interceptors-middleware` },
     { text: L.architecture, link: architectureLink },
+    {
+      text: L.featuresPipeline,
+      link: lang === "ar" ? `${p}/features-pipeline` : "/features-pipeline",
+    },
     { text: L.retryCache, link: `${p}/retry-cache` },
     { text: L.errorsSecurity, link: `${p}/errors-security` },
   );

.vitepress/llms.template.txt

@@ -10,7 +10,7 @@
 - **This file (machine-oriented summary):** https://openfetch-js.github.io/openfetch-docs/llms.txt
 - VitePress `base` is `/openfetch-docs/` — prefix relative doc paths below with that base when resolving URLs (e.g. `/skills` → `https://openfetch-js.github.io/openfetch-docs/skills`).
 - Path map: English at `/` (default), locale hubs at `/ar/`, `/es/`, …, hub at `/languages/`.
-- Monorepo package layout & request lifecycle: `openFetch/docs/PROJECT_FLOW.md` in the GitHub repo.
+- Package layout & request lifecycle: [docs/PROJECT_FLOW.md](https://github.com/openfetch-js/OpenFetch/blob/main/docs/PROJECT_FLOW.md) in the library repo.
 
 ## Install & import
 
@@ -105,7 +105,7 @@ import { createFluentClient } from "@hamdymohamedak/openfetch/sugar";
 
 ## Agent skills (Cursor, Claude Code, compatible tools)
 
-The repo includes **`openfetchskill/`** — a **`SKILL.md`** skill aligned with the [Agent Skills specification](https://agentskills.io/specification) (YAML frontmatter + Markdown). Ecosystem hub: [skills.sh](https://skills.sh). Human docs page: `/skills` on the site above.
+Published plugin: **[openfetch-js/openFetchSkill](https://github.com/openfetch-js/openFetchSkill)** (`SKILL.md` + `references/`). The same folder exists as **`openfetchskill/`** in **[openfetch-js/OpenFetch](https://github.com/openfetch-js/OpenFetch)**. Spec: [Agent Skills](https://agentskills.io/specification). Hub: [skills.sh](https://skills.sh). Human overview: [openfetch-docs `/skills`](https://openfetch-js.github.io/openfetch-docs/skills).
 
 ## Human readers
 

README.md

@@ -96,4 +96,4 @@ Translated locales live under **`ar/`**, **`es/`**, etc. (same filenames where t
 
 ### Package version
 
-The docs site reads the displayed version from **`.vitepress/openfetch-version.ts`** (single source of truth for pages, hero “Ask ChatGPT / Claude” links, and generated `public/llms.txt`). Bump that file when you cut a release. For runtime behavior details and file-level architecture, see `openFetch/docs/PROJECT_FLOW.md`.
+The docs site reads the displayed version from **`.vitepress/openfetch-version.ts`** (single source of truth for pages, hero “Ask ChatGPT / Claude” links, and generated `public/llms.txt`). Bump that file when you cut a release. For runtime behavior details and file-level architecture, see [**`docs/PROJECT_FLOW.md`**](https://github.com/openfetch-js/OpenFetch/blob/main/docs/PROJECT_FLOW.md) in the library repository.

ar/configuration.md

@@ -1,6 +1,6 @@
 # الإعدادات
 
-يُدمج الإعداد من **افتراضيات العميل** و**خيارات كل استدعاء** عبر `mergeConfig` (انظر قواعد الدمج أدناه).
+يُدمج الإعداد من **افتراضيات العميل** و**خيارات كل استدعاء** عبر `mergeConfig` (انظر قواعد الدمج أدناه). للصورة الكاملة للمسار والميزات الجديدة راجع [الميزات ومسار الطلب](./features-pipeline.md).
 
 ## `OpenFetchConfig` (الطلب)
 
@@ -24,14 +24,21 @@
 
 ### المهلات والإلغاء
 
-- **`timeout`** — بالمللي ثانية؛ يستخدم `AbortController` داخلياً يُدمج مع **`signal`** عبر `mergeAbortSignals`.
+- **`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](https://github.com/standard-schema/standard-schema) اختياري على JSON المحلّل بعد نجاح الحالة؛ الفشل → **`SchemaValidationError`** (قبل **`transformResponse`**).
+- **`init`** — مصفوفة `(config) => void` **متزامنة** على الإعداد المدمج **قبل** معترضات الطلب.
+
+### مدخل `Request`
+
+- **`client.request(Request, تجاوزات?)`** — يدمج عنوان الطلب والطريقة والرؤوس والجسم والإشارة مع الافتراضيات ثم التجاوزات.
 
 ### التحويلات
 
@@ -69,10 +76,11 @@ type OpenFetchResponse<T = unknown> = {
 
 - المفاتيح على المستوى الأعلى: الإعداد الأحدث يغلب.
 - **`headers`**: دمج سطحي؛ رؤوس الاستدعاء تغلب الافتراضيات.
-- **`middlewares`**، **`transformRequest`**، **`transformResponse`**: **تُلحق** (الافتراضيات أولاً ثم الخاصة بالاستدعاء).
-- **`retry`**، **`memoryCache`**: دمج سطحي للكائنات.
+- **`middlewares`**، **`transformRequest`**، **`transformResponse`**، **`init`**: **تُلحق** (الافتراضيات أولاً ثم الخاصة بالاستدعاء).
+- **`retry`**، **`memoryCache`**: دمج سطحي لحقول الكائن؛ **`retry.onBeforeRetry`** و **`retry.onAfterResponse`** يُركّبان (الافتراضيات ثم لكل استدعاء).
 - تُزال مفاتيح تلوث النموذج الأولي (`__proto__`، `constructor`، `prototype`) من الكائنات المدمجة والرؤوس / `retry` / `memoryCache` المتداخلة.
 
 ## التالي
 
+- [الميزات ومسار الطلب](./features-pipeline.md)  
 - [المعترضات والوسيط](./interceptors-middleware.md)

ar/features-pipeline.md

@@ -0,0 +1,136 @@
+# الميزات ومسار الطلب الكامل
+
+صفحة مرجعية: **ما يوفّره openFetch** و**ترتيب التنفيذ** من دمج الإعداد حتى إرجاع الاستجابة (بعد آخر التعديلات على الحزمة).
+
+للمقارنات المعمّقة راجع [البنية والداخلية](./architecture.md). لجدول الخيارات راجع [الإعدادات](./configuration.md). النسخة الإنجليزية الكاملة: [Features & pipeline](../features-pipeline.md).
+
+## نظرة على الحزمة
+
+| الموضوع | التفاصيل |
+|---------|----------|
+| **npm** | `@hamdymohamedak/openfetch` |
+| **التنسيق** | ESM فقط |
+| **اعتماديات التشغيل** | صفر |
+| **المحركات** | Node 18+ والمتصفحات وBun وDeno وWorkers |
+| **نقاط الدخول** | الحزمة الرئيسية؛ `/plugins`؛ `/sugar` |
+| **النقل** | `fetch` الأصلي فقط |
+
+---
+
+## قائمة الميزات
+
+### العميل والإعداد
+
+- **`createClient` / `create`** — افتراضيات، أوامر HTTP، `request`، `use`.
+- **`mergeConfig`** — دمج افتراضيات + استدعاء؛ دمج رؤوس؛ **سلسلة** للـ `middlewares` و`transformRequest` و`transformResponse` و**`init`**؛ دمج مركّب لـ **`retry.onBeforeRetry` / `onAfterResponse`**؛ دمج سطحي لـ `retry` و`memoryCache`.
+- **`init`** — مصفوفة دوال **متزامنة** على الإعداد المدمج **قبل** المعترضات (تعديل رؤوس، إلخ).
+- **`Request` كمدخل** — `client.request(request, تجاوزات?)` يدمج عنوان الطلب والطريقة والرؤوس والجسم والإشارة مع الافتراضيات.
+- **`throwHttpErrors`** — سلوك قريب من Ky عند عدم وجود **`validateStatus`**: `false` لا يرمي على حالة HTTP؛ دالة ترجع `true` تعني «ارمِ خطأ HTTP لهذه الحالة». إن وُجد **`validateStatus`** فهو **يغلب** `throwHttpErrors`.
+
+### المعترضات والوسيط
+
+- **معترضات الطلب** — تسلسل غير متزامن (LIFO).
+- **معترضات الاستجابة** — تسلسل غير متزامن (FIFO).
+- **الوسيط** — حول `next()` حتى يصل الطلب إلى **`dispatch`** (استدعاء `fetch` الفعلي).
+
+### `dispatch` (النقل)
+
+- بناء URL، **`assertSafeUrl`** اختياري، رؤوس، **`Accept`** مقترح عند **`responseType`**، مصادقة Basic، **`transformRequest`**، ثم **`fetch`**.
+- **`timeout`** — مع تمييز **`ERR_TIMEOUT`** عن إلغاء المستخدم **`ERR_CANCELED`** عندما يكون الإلغاء من المهلة الداخلية فقط.
+- **`rawResponse`** — تخطي التحليل و`transformResponse`؛ `data` هي `Response` الأصلية.
+
+### بعد `fetch` (المسار العادي)
+
+1. **تحليل الجسم**
+2. **`validateStatus`** — فشل → `ERR_BAD_RESPONSE` (مع الجسم المحلّل إن وُجد)
+3. **`jsonSchema`** — تحقق Standard Schema اختياري؛ فشل → **`SchemaValidationError`**
+4. **`transformResponse`**
+
+### إعادة المحاولة
+
+- backoff، حالات HTTP، الشبكة، مفتاح **Idempotency** لـ POST عند التفعيل، ميزانية زمنية أحادية **`timeoutTotalMs`**.
+- **`onAfterResponse`** — بعد نجاح المحاولة؛ رمي **`OpenFetchForceRetry`** يعيد المحاولة.
+- **`onBeforeRetry`** — بعد فشل محاولة وقبل الانتظار (عند وجود محاولة لاحقة).
+- **`hooks()`** — يدمج `onBeforeRetry` / `onAfterResponse` في `ctx.request.retry`.
+
+### التخزين المؤقت والـ fluent
+
+- وسيط ذاكرة للـ GET/HEAD مع TTL وSWR (انظر [إعادة المحاولة والتخزين المؤقت](./retry-cache.md)).
+- الإضافات: `timeout`، `hooks`، `debug`، **`strictFetch`**.
+- **Fluent**: `createFluentClient`، سلاسل مثل `.json()` و**`.json(schema)`**، **`.memo()`**.
+
+### الأخطاء والمساعدات
+
+- **`OpenFetchError`** + **`toShape()`** للسجلات الآمنة نسبياً.
+- **`isOpenFetchError`**, **`isHTTPError`**, **`isTimeoutError`**, **`isSchemaValidationError`**.
+- **`assertSafeHttpUrl`**, **`maskHeaderValues`**, **`redactSensitiveUrlQuery`**, مفاتيح idempotency، **`cloneResponse`**.
+
+---
+
+## الصورة الكاملة للـ pipeline (مخطط)
+
+```mermaid
+flowchart TD
+  M[mergeConfig] --> I[init hooks متزامنة]
+  I --> RI[معترضات الطلب]
+  RI --> MW[كومة الوسيط]
+  MW --> RO[معترضات الاستجابة]
+  RO --> OUT[إرجاع OpenFetchResponse أو unwrap]
+```
+
+**داخل الوسيط (مثال `createRetryMiddleware`):** كل محاولة تنفّذ `await next()` فيمرّ الوسيط الداخلي ثم **`dispatch`**. عند النجاح يُستدعى **`onAfterResponse`**؛ إذا أُلقِي **`OpenFetchForceRetry`** تُعاد المحاولة. عند الفشل يُستدعى **`onBeforeRetry`** (إن وُجد) ثم الانتظار ثم المحاولة التالية إن سمحت السياسة.
+
+### داخل `dispatch` (بعد `fetch` — ليس `rawResponse`)
+
+```mermaid
+flowchart TD
+  A[URL + رؤوس + transformRequest + fetch] --> E{rawResponse?}
+  E -->|نعم| VS1[validateStatus على الحالة فقط] --> Z[إرجاع Response كـ data]
+  E -->|لا| P[parseBody]
+  P --> VS2[validateStatus]
+  VS2 --> JV{jsonSchema?}
+  JV -->|نعم| SCHEMA[Standard Schema]
+  JV -->|لا| TR
+  SCHEMA --> TR[transformResponse]
+  TR --> Z2[إرجاع OpenFetchResponse]
+```
+
+### مخطط نصي (نسخ سريع)
+
+```
+mergeConfig
+   ↓
+init hooks (sync)
+   ↓
+request interceptors
+   ↓
+middleware stack
+   ↓
+   ┌─ retry: لكل محاولة → next → … → dispatch
+   │     dispatch: URL/headers → transformRequest → fetch
+   │       [raw?] validateStatus → return Response
+   │       OR parse → validateStatus → jsonSchema? → transformResponse
+   │     ↓
+   │   onAfterResponse — رمي OpenFetchForceRetry؟ → حلقة المحاولة
+   │     ↓
+   └─ عند الفشل: onBeforeRetry → backoff → حلقة
+   ↓
+response interceptors
+   ↓
+return
+```
+
+**ملاحظات**
+
+- **`onAfterResponse`** يعمل **بعد** اكتمال `dispatch` (بما فيه **`transformResponse`**)، فيرى `data` النهائية إلا في حالة **`rawResponse`**.
+- الوسيط **فوق** retry يعمل **مرة واحدة** لكل استدعاء عميل؛ الوسيط **تحت** retry يعمل **مرة لكل محاولة**.
+
+---
+
+## روابط
+
+- [الإعدادات](./configuration.md)  
+- [المعترضات والوسيط](./interceptors-middleware.md)  
+- [إعادة المحاولة والتخزين المؤقت](./retry-cache.md)  
+- [الأخطاء والأمان](./errors-security.md)  
+- [الإضافات والـ fluent](../plugins-fluent.md) (إنجليزي)