TypeScript Academy · درس

تصميم DSL للاستعلامات السلسة

ابنوا واجهة API للاستعلامات قابلة للتسلسل وتتحقق من صحتها ذاتيًا

تصميم DSL للاستعلامات السلسة درس مجاني في TypeScript Academy على CoddyKit. هذا هو الدرس 2 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في TypeScript Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة TypeScript Academy 4 دروس في المجموع.

تصميم DSL متسلسلة للاستعلامات

نصمم DSL للاستعلامات قابلة لتسلسل الاستدعاءات، بحيث تعمل كل خطوة على تنقيح الخطوات التالية المسموح بها من خلال الأنواع المُرجعة. وتبدو النتيجة شبيهة بـ SQL، كما ترفض الترتيبات غير الصحيحة وقت الترجمة.

القواعد النحوية المستهدفة

نريد التسلسل التالي: from ثم where اختيارية (يمكن تكرارها)، ثم select نهائية. لا يمكنكم استخدام select قبل from، ولا يمكنكم استخدام from مرتين.

واجهات الحالات

مثّلوا كل مرحلة على شكل واجهة تُرجع المرحلة التالية.

interface Builder {
  from(table: string): FromStage;
}
interface FromStage {
  where(cond: string): FromStage; // repeatable
  select(...cols: string[]): Result;
}
interface Result { sql: string; }

فرض الترتيب

بما أن select موجودة فقط في FromStage، فإن استدعاءها على Builder الأولي يُعد خطأً في وقت الترجمة. ويُفرض الترتيب بالكامل من خلال الدوال التي تعرضها كل مرحلة.

declare const db: Builder;
db.from("users").select("id"); // ok
db.select("id");               // Error: select missing on Builder

تتبّع الأعمدة المحددة

أضيفوا نوعًا عامًا وهميًا لتذكّر الأعمدة التي حُددت، حتى يكون نوع النتيجة دقيقًا.

interface FromStage<T extends string = never> {
  where(c: string): FromStage<T>;
  select<C extends string>(...cols: C[]): Result<C>;
}
interface Result<C extends string> { columns: C[]; }

التنقيح مع كل استدعاء

يمكن لكل where أن يراكم القيود في النوع أيضًا. سنبقي المثال بسيطًا هنا، لكن يمكن تعميم النمط لتتبّع المعلمات المرتبطة.

const q = db.from("users").where("age > 18").where("active = true");
// still FromStage; select remains available

منع تكرار from

بما أن FromStage لا تعرض from، فلا يمكنكم استدعاؤها مرتين. وتمنع القواعد النحوية ذلك بنيويًا، من دون الحاجة إلى حارس وقت التشغيل.

db.from("a").from("b"); // Error: from does not exist on FromStage

خطوة نهائية

تُرجع select قيمة من النوع Result، الذي لا يعرض where ولا from، وبذلك ينهي سلسلة الاستدعاءات. ولا تبقى سوى عمليات قراءة النتيجة.

const r = db.from("users").select("id", "name");
r.columns; // ("id" | "name")[]
// r.where(...) -> Error: where not on Result

قيود الأعمدة المنمّطة

قيّدوا الأعمدة بمخطط جدول معروف باستخدام نوع عام آخر، بحيث تُرفض الأعمدة غير المعروفة، وبذلك تدمجون DSL هذه مع أفكار ORM السابقة.

interface Table<Cols extends string> {
  select<C extends Cols>(...cols: C[]): Result<C>;
}
// db.from gives Table<"id" | "name" | "age">

الخطوات الاختيارية مقابل المطلوبة

اجعلوا الخطوة مطلوبة من خلال إتاحة الدالة التالية فقط بعد إتمامها. فعلى سبيل المثال، افرضوا وجود where واحدة على الأقل بإرجاع مرحلة لا تظهر فيها select إلا بعد استدعاء where. ويمكن للأنواع المتسلسلة نفسها أيضًا استنتاج نوع صف النتيجة لتنفيذ الاستعلام، مما يربط القواعد النحوية وقت الترجمة ببيانات وقت التشغيل.

لماذا يهم هذا

تكون DSL المتسلسلة المصممة بهذه الطريقة موثِّقة لنفسها ويستحيل إساءة استخدامها: يعرض الإكمال التلقائي الخطوات التالية الصحيحة فقط، ولا تُترجم التسلسلات غير القانونية أبدًا. وهذا هو الأساس الذي تقوم عليه مكتبات أدوات البناء سهلة الاستخدام.

تحقّق سريع

تأكدوا من فهمكم لتصميم DSL المتسلسلة.

مراجعة

صممتم DSL متسلسلة للاستعلامات بوصفها آلة حالات على مستوى النوع: تُرجع واجهة كل مرحلة المرحلة التالية، ولا تعرض سوى الدوال الصحيحة. وتتتبّع الأنواع العامة الوهمية الأعمدة المحددة، وتنهي المراحل النهائية سلسلة الاستدعاءات، بينما ترفض قيود الأعمدة الأسماء غير المعروفة، وكل ذلك تفرضه الأنواع المُرجعة.

الأسئلة الشائعة

هل درس «تصميم DSL للاستعلامات السلسة» مجاني؟

نعم — نص درس «تصميم DSL للاستعلامات السلسة» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة TypeScript Academy، انتقل إلى CoddyKit PRO. تتضمن دورة TypeScript Academy 4 دروس في المجموع.

ماذا ستتعلم في «تصميم DSL للاستعلامات السلسة»؟

ابنوا واجهة API للاستعلامات قابلة للتسلسل وتتحقق من صحتها ذاتيًا تتمرن على TypeScript Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ TypeScript Academy؟

لا تُشترط خبرة سابقة. TypeScript Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 2 من أصل 4.

كم من الوقت يستغرق درس «تصميم DSL للاستعلامات السلسة»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس TypeScript Academy هذا؟

نعم. كل درس في TypeScript Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

← العودة إلى TypeScript Academy