تقدير المشروع
← كل المقالات

نهج جديد لبناء مكتبات TypeScript سهلة الاستخدام وقابلة لـ tree-shaking في آن واحد

نهج ذكي لبناء مكتبات TypeScript قابلة لـ tree-shaking دون التضحية بتجربة المستخدم.

10 دقائق قراءة
type-level programmingtypescriptlibrary

يستعرض هذا المقال نهجًا ذكيًا لبناء مكتبات TypeScript قابلة لـ tree-shaking دون التضحية بتجربة المستخدم.

الصورة العامة تبدو كالتالي:

  • يصل المستخدمون إلى واجهة برمجة مكتبتنا (API) عبر نقطة دخول واحدة (فكّر في Zod).
  • وبفضل ذلك، يمكنهم الاعتماد على تقنيات مثل تسلسل الدوال (method chaining) ونمط المُنشئ (builder pattern) وغيرها.
  • لكن قبل استخدام نقطة الدخول هذه، عليهم تهيئتها باستيراد الوظائف التي يريدونها صراحةً. وكل وظيفة إضافية يستوردونها توسّع الـ API وتزيد حجم الحزمة النهائية.
  • ونتيجة لذلك، يستطيع مؤلف المكتبة تقديم مزيد من الميزات دون خوف من تضخم الـ API العامة، لأن المستخدم هو من يختار أي واجهات تُفعَّل وتُضمَّن في الحزمة.

لفهم هذه الفكرة بصورة أفضل ومعرفة كيفية تنفيذها، لنتناول مثالًا عمليًا.

لنأخذ Zod، وهي مكتبة شائعة للتحقق من المخططات (schema validation) تعتمد TypeScript أولًا. يحب المطورون العمل بها، ولها منظومة غنية.

هكذا تُستخدم عادةً:

import { z } from "zod"; // 12.8 kB

const LoginSchema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
});

// Throws error
LoginSchema.parse({ email: "", password: "" });

// Returns data as { email: string; password: string }
LoginSchema.parse({ email: "jane@example.com", password: "12345678" });

تُعدّ سهولة الاستخدام من أكبر نقاط قوة Zod. فهي توفر واجهة بديهية ومختصرة لبناء المخططات عبر تسلسل دوال لا تغيّر أي حالة.

من حيث راحة المطور، تتمتع الواجهة التي تدعم تسلسل الدوال بميزة كبيرة واحدة: اكتشاف الـ API. فبمجرد كتابة “.”، تعرض بيئة التطوير (IDE) كل العمليات المحتملة التي قد تحتاجها، مع أنواعها الدقيقة.

لكن هناك مشكلة: حجم الاستيراد الثابت. يبدأ استخدام Zod باستيراد كائن z واحد والبناء عليه. وبالتالي، كلما استخدمنا Zod لأي غرض، علينا استيراد كل دالة متاحة. وسواء استدعينا .brand أو .superRefine أو .passthrough أم لا، فإنها كلها تنتهي في حزمة تطبيقنا، لأن Zod غير قابلة لـ tree-shaking. فماذا يعني ذلك بالضبط؟

ما المكتبة القابلة لـ Tree-Shaking؟

باختصار، tree shaking هو إزالة الشيفرة غير المستخدمة. تحققه أدوات التجميع (bundlers) في JavaScript بتحليل عبارات الاستيراد والتصدير وتحديد الصادرات غير المستخدمة. ولا ينطبق tree shaking على وحدات الشيفرة في مصدرك فحسب، بل على جميع تبعياتك أيضًا.

ليست كل مكتبة قابلة لـ tree shaking. فلكي تكون المكتبة قابلة لذلك، يجب تنظيمها بطريقة معينة.

مثال على بنية مكتبة قابلة لـ Tree-Shaking

انظر إلى هذا المثال:

// `tree-shakable-lib`

export const fun1 = () => "fun1";

export const fun2 = () => "fun2"

فإذا كان تطبيقك بعد ذلك يبدو هكذا:

import { fun1 } from "tree-shakable-lib";

console.log(fun1());

فستكون الحزمة الناتجة:

const fun1 = () => "fun1";

console.log(fun1());

كما ترى، حُذف تعريف fun2 من الحزمة، مما يجعلها أصغر.

مثال على بنية مكتبة غير قابلة لـ Tree-Shaking

بعد ذلك، انظر إلى هذا المثال:

// `non-tree-shakable-lib`

export const lib = {
    fun1: () => "val1",
    fun2: () => "val2"
}

فإذا كان تطبيقك بعد ذلك يبدو هكذا:

import { lib } from "./non-tree-shakable-lib.js";

console.log(lib.fun1());

فستكون الحزمة الناتجة:

const lib = {
    fun1: () => "val1",
    fun2: () => "val2"
};

console.log(lib.fun1());

هنا، ورغم أن الدالة fun1 وحدها هي المستخدمة، يجب أن يدخل كائن lib بالكامل في الحزمة، لأن أداة التجميع لا تستطيع استخراج جزء واحد فقط من كائن أو فئة بأمان.

نصيحة: يتيح لك Rollup REPL اللعب بـ tree shaking عبر الإنترنت بسهولة

ما سبق مجرد مقدمة قصيرة للموضوع الأوسع حول tree shaking، لكنها كافية لأغراض هذا المقال.

Valibot = Zod مع Tree Shaking؟

الآن وقد عرفنا كيف نبني مكتبة قابلة لـ tree shaking، كيف يمكننا جعل Zod قابلة لذلك؟ لقد حاولت مكتبة أُطلقت حديثًا تُدعى Valibot ذلك.

هكذا يبدو مثال Zod السابق بعد إعادة كتابته بـ Valibot:

import { email, minLength, object, parse, string } from 'valibot'; // 0.85 kB

const LoginSchema = object({
  email: string([email()]),
  password: string([minLength(8)]),
});

// Throws error
parse(LoginSchema, { email: '', password: '' });

// Returns data as { email: string; password: string }
parse(LoginSchema, { email: 'jane@example.com', password: '12345678' });

تبدو الواجهة مألوفة، لكنها تميل أكثر إلى الأسلوب الوظيفي:

  • بدلًا من استدعاء الدالة parse على LoginSchema، نستدعي دالة parse مستقلة ونمرر المخطط وسيطًا لها.
  • وبدلًا من ربط القيود الإضافية بالمدقق string بالنقطة، نمررها وسائط. وكل قيد دالة تُستورد على حدة.

يتوافق هذا مع القاعدة المبسطة للمكتبات القابلة لـ tree shaking: المكتبة التي تصدّر مجموعة من الدوال النقية يرجَّح أنها قابلة لذلك. وهذا صحيح مع Valibot. انظر إلى حجم الاستيراد المذكور في التعليق على السطر الأول – إنه أصغر 15 مرة من حجم Zod، مع أنه يؤدي المهمة نفسها تمامًا. وبطبيعة الحال، سيزداد حجم الاستيراد كلما استخدم تطبيقك دوال أكثر، لكن من النادر عمليًا استخدام 100% من وظائف مكتبة ما، خصوصًا المكتبات متعددة الاستخدامات مثل Zod وValibot.

ومع ذلك، تعاني Valibot من مشكلة. فواجهتها الوظيفية تجعل المكتبة قابلة لـ tree shaking، لكنني أرى أنها هنا تخاطر أيضًا بجعل الـ API أقل سهولة. فسهولة الاستخدام أصعب في التقدير من أحجام الاستيراد، لأنها أدق وقد ترجع إلى التفضيل الشخصي. ومع ذلك، أعتقد أن ملاءمة Zod للمطور تجعلها أفضل. وهذه بعض عيوب واجهة Valibot:

  • لا يمكنك استكشاف الـ API بسهولة دون الخروج من بيئة التطوير.
  • يتطلب بناء كل مخطط إما القفز من تعريف المخطط إلى عبارة الاستيراد لإضافة دوال جديدة، وإما سرد جميعها مسبقًا.

Correttore: أفضل ما في العالمين

مراجعة سريعة لما تناولناه:

  • تقدم Zod تجربة مطور (DX) ممتازة لكنها غير قابلة لـ tree shaking.
  • Valibot قابلة لـ tree shaking، لكن واجهتها قد تُعدّ أقل سهولة.

وهذا يطرح سؤالًا بسيطًا: هل يمكننا بناء مكتبة بواجهة Zod نفسها تكون قابلة لـ tree shaking بطريقة ما؟ نعم، يمكننا – وهذا بالضبط موضوع التقنية التي أوشك أن أعرضها. وكإثبات للمفهوم، بنيت Correttore:

import { email, minLength, object, initCorrettore, string } from "correttore"; // 0.54 kB

export const c = initCorrettore({
  string,
  email,
  object,
  minLength,
});

const LoginSchema = c.object({
  email: c.string().email(),
  password: c.string().minLength(8),
});

// Throws error
LoginSchema.parse({ email: "", password: "" });

// Returns data as { email: string; password: string }
LoginSchema.parse({ email: "jane@example.com", password: "12345678" });

بمزيد من التفصيل:

  1. في السطر الأول، نستورد initCorrettore مع كل «قطعة» من الـ API سيستخدمها تطبيقنا.
  2. نستدعي initCorrettore لإنشاء متغير c وتصديره. يؤدي هذا c دور z المألوف في Zod. وفي أي مكان آخر في التطبيق، نكتفي باستيراد c من هذا الملف.
  3. نبني LoginSchema بما يبدو تمامًا كطريقة Zod، لكن باستخدام كائن c لدينا. والفرق أننا أثناء تسلسل الدوال نرى فقط تلك التي استوردناها سابقًا ومررناها إلى الدالة initCorrettore. فمثلًا، حذف email من استدعاء initCorrettore سيجعل الدالة email تختفي من string()، وسيُحدث كائن المخطط خطأ TypeScript وقت الترجمة. وعلى العكس، فاستيراد مدقق number مثلًا وإضافته سيجعله يظهر على الكائن c دالةً صالحة.

كل شيء آخر يعمل كما في Zod، لكن حجم الاستيراد لا يتجاوز 500 بايت بقليل – أصغر 25 مرة!

ما الوصفة السرية

لا تتطلب كتابة مكتبة كهذه سوى مكوّنين:

  1. كائنات Proxy
  2. قليل من البرمجة على مستوى الأنواع (type-level programming).

Proxy

تتيح لك كائنات Proxy اعتراض العمليات الأساسية لأي كائن وإعادة تعريفها. في المثال أدناه، نغلّف someObject بـ proxy بحيث يُسجَّل كل وصول إلى خاصية مع اسمها.

const someObject = {
    a: 100,
    b: "hello"
}

const proxyObject = new Proxy(someObject, {
    get: (target, prop) => {
        console.log(`property ${String(prop)} was called!`);
        return target[prop as keyof typeof target];
    }
});

proxyObject.a; // logs: "property a was called!"
proxyObject.b; // logs: "property b was called!"

في معالج الـ proxy (الوسيط الثاني الممرر إلى مُنشئ Proxy)، يمكننا فعل أي شيء تقريبًا. اطّلع على وثائق MDN Web Docs حول Proxy لمزيد من الأمثلة ونظرة شاملة على الـ API.

الفكرة الأساسية إذن هي: عندما يهيئ المستخدم Correttore بسجل من المحللات (parsers) (مثل number وstring وboolean وغيرها)، نبني proxy من كائن فارغ ونشغّل المحللات ديناميكيًا كلما استُدعيت:

// NOTE: the code below works, but for now, the `c` object is typed as `any`

// mocked parsers for brevity
const string = (x: any) => `${x} is a string`;
const number = (x: any) => `${x} is a number`;
const boolean = (x: any) => `${x} is a boolean`;

const simplifiedInitCorrettore = (parsers: Record<string, (arg: any) => string>) => {
    return new Proxy({} as any, {
        get(target, key) {
            if (key in parsers) {
                return (args: any) => parsers[key as any](args);
            } else {
                throw new Error("Unknown parser");
            }
        }
    })
}

const c = simplifiedInitCorrettore({
    string,
    number,
    // we purposely omit boolean parser here
});

console.log(c.string("hello")); // -> "hello is a string"
console.log(c.number(42)); // -> "hello is a string"
console.log(c.boolean(true)); // -> Error: Unknown parser

يوضح التنفيذ أعلاه المفهوم العام لكنه لا يدعم بعد تسلسل الدوال ولا الأنواع الصحيحة.

لتمكين تسلسل الدوال (مثل c.string().email())، سنُدخل متغير parsersChain الذي يحتفظ بكل محلل في سلسلة الدوال (*). وهكذا، مثلًا، يُحوَّل c.string().email() إلى [stringParser, emailParser]. ولا نمرّ على جميع المحللات ونتحقق من الوسيط مقابل كل منها إلا عند استدعاء .parse (**).

const createParserProxy = (
  p: Parser<any>,
  parsers: Record<string, (...args: any) => Parser<any>>,
  parsersChain: Parser<any>[]
) =>
  new Proxy(p, {
    get(target, key) {
      if (key === "parse") { // (**)
        return (arg: any) => {
          parsersChain.forEach((p) => p.parse(arg));
          return target.parse(arg);
        };
      }
      if (key in parsers) {
        return (args: any) =>
          createParserProxy(parsers[key as any](args), parsers, [
            ...parsersChain, // (*)
            parsers[key as any](args),
          ]);
      } else {
        throw new Error(`Unknown parser ${key as string}`);
      }
    },
  });

export const initCorrettore = <
  Parsers extends Record<string, (...args: any) => Parser<any>>
>(
  parsers: Parsers
): calculateCorrettoreType<keyof Parsers> => {
  return new Proxy({} as calculateCorrettoreType<keyof Parsers>, {
    get(target, key) {
      if (key in parsers) {
        return (args: any) =>
          createParserProxy(parsers[key as any](args), parsers, [
            parsers[key as any](args),
          ]);
      } else {
        throw new Error(`Unknown parser ${key as string}`);
      }
    },
  });
};

التنفيذ مليء بأنواع any، لكن الكائن c الناتج يحمل أنواعًا صحيحة بفضل المقطع as calculateCorrettoreType<keyof Parsers>.

البرمجة على مستوى الأنواع

هنا تدخل البرمجة على مستوى الأنواع إلى الصورة. عليك كتابة نوع يعكس سجل المحللات المستوردة المقدَّم. وهذا بسيط في معظمه؛ أما الجزء الصعب فهو جعله يتصرف بحيث يكون المحلل email متاحًا بعد المحلل string() فقط وليس، مثلًا، بعد number().

// Full correttore type with all parsers and extensions
type FullCorrettore = {
  // StringParser is an object that includes the `parse` method as well
  // as all the other parsers that can occur after `string()`, for example
  // `email` or `minLength`. 
  string: () => StringParser;

  // Similarly for this one.
  number: () => NumberParser;

  // see ObjectParser implementation here:
  // based on the object parser from the author's proof-of-concept library
  object: <S extends Record<string, Parser<any>>>(schema: S) => ObjectParser<S>;
};

// given the list of imported parsers and validator, calculate a type for the correttore object
type calculateCorrettoreType<
  features,
  parser extends Record<string, (...args: any[]) => any> = FullCorrettore
> = {
  [k in Extract<keyof parser, features | "parse">]: k extends "parse"
    ? parser[k]
    : (
        ...args: Parameters<parser[k]>
      ) => calculateCorrettoreType<features, ReturnType<parser[k]>>;
};

الخلاصة

التقنية المعروضة في هذا المقال تؤتي ثمارها بوضوح في تجربة المستخدم وتحسين حجم الحزمة – لكن هل لها عيوب؟

بالنسبة لمن يستهلكون المكتبة، لا يكاد يوجد. قد يقول البعض إن تهيئة المكتبة خطوة إضافية، وإنه حين لا يهتم المستخدم بحجم الاستيراد (كما في تطبيقات جانب الخادم) فإنها تضيف تعقيدًا فحسب. لكن يمكن معالجة ذلك بتصدير كائن إضافي مهيأ مسبقًا من المكتبة يعرض الـ API كاملة.

وبما أن هذه التقنية تحسّن تجربة المستخدم، فإنها تجعل حياة مؤلفي المكتبات أصعب. فمن جهة، ربط كل القطع معًا بواسطة proxy بسيط عادةً، لكنه يعني كتابة شيفرة غير آمنة نوعيًا (not type-safe) ومليئة بـ any. ومن جهة أخرى، قد يتطلب تزويد مستهلك المكتبة بأنواع صحيحة بعض الحيل المعقدة على مستوى الأنواع، وقد تبدو مرهبة للمبرمجين الجدد على هذا المجال.


يسعدني أن أسمع رأيك في هذا – اترك تعليقًا أدناه.

وإذا أردت المساعدة في جعل هذا المشروع جاهزًا للإنتاج، فمرحّب بك لفتح PR بتغييرات تقرّبه من واجهة API متوافقة 1:1 مع Zod.