TypeScript Academy · درس

نشر مكتبة أدوات الأنواع

جمّعوا أدوات الأنواع المخصّصة وشاركوها على npm

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

ما مكتبة أدوات الأنواع؟

تصدّر مكتبة أدوات الأنواع أنواع TypeScript فقط، دون شيفرة وقت التشغيل. ومن أمثلتها الشائعة type-fest وts-essentials وutility-types.

// A type utility library exports types like:
export type DeepPartial<T> = T extends object
  ? { [K in keyof T]?: DeepPartial<T[K]> }
  : T;

بنية المشروع

حافظوا على البساطة: ملف src/index.ts واحد يعيد تصدير جميع الأدوات، مع إعداد tsconfig.json لإصدار التصريحات فقط.

// tsconfig.json
{
  "compilerOptions": {
    "declaration": true,
    "emitDeclarationOnly": true,
    "outDir": "dist",
    "strict": true
  }
}

package.json لحزمة تحتوي على الأنواع فقط

اضبطوا حقلي main وtypes للإشارة إلى ملفات التصريحات. واضبطوا sideEffects: false لتمكين tree-shaking.

{
  "name": "@myorg/type-utils",
  "version": "1.0.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "sideEffects": false,
  "files": ["dist"]
}

توليد التصريحات

شغّلوا tsc لإصدار ملفات .d.ts. وفي مكتبة تحتوي على الأنواع فقط، تكون مخرجات JavaScript فارغة أو محدودة.

# Build declarations
npx tsc
# dist/index.d.ts is generated

إدارة الإصدارات وسجلات التغييرات

اتبع الإصدار الدلالي: تغييرات الأنواع الكاسرة للتوافق تكون رئيسية، والأدوات الجديدة تكون ثانوية، والإصلاحات تكون تصحيحية.

# Bump version
npm version minor
# Generate changelog with conventional-changelog or changesets

النشر إلى npm

استخدم npm publish أو pnpm publish. بالنسبة إلى الحزم ذات النطاق ضمن مؤسسة، تأكد من تسجيل دخولك ومن ضبط النطاق.

npm login
npm publish --access public
# or for private: npm publish --access restricted

توافق إصدارات TypeScript

وثّق الحد الأدنى من إصدار TypeScript الذي تتطلبه أدواتك. تتطلب الأنواع الشرطية العودية TS 4.1+، بينما يتوفر Awaited مضمّنًا بدءًا من TS 4.5+.

// package.json peerDependencies
{
  "peerDependencies": {
    "typescript": ">=4.5"
  }
}

اختبار الأنواع باستخدام tsd

استخدم الحزمة tsd لكتابة اختبارات على مستوى الأنواع تُشغَّل أثناء CI للتأكد من أن أدواتك تعمل بشكل صحيح.

import { expectType } from "tsd";
import type { DeepPartial } from "@myorg/type-utils";

expectType<DeepPartial<{ a: { b: number } }>>({ a: {} });

التوثيق باستخدام TSDoc

أضف تعليقات JSDoc من النوع /** */ إلى أنواعك. تنشئ أدوات مثل TypeDoc توثيق API منها.

/**
 * Makes all properties of T optional at every depth.
 * @example type A = DeepPartial<{ x: { y: number } }> // { x?: { y?: number } }
 */
export type DeepPartial<T> = ...

توزيع الحزم في مستودع متعدد الحزم

في مستودع متعدد الحزم، انشر حزمة الأنواع كحزمة workspace حتى تستهلكها التطبيقات الأخرى عبر workspace:* بدلًا من npm.

// Other package's package.json
{
  "dependencies": {
    "@myorg/type-utils": "workspace:*"
  }
}

مراجعة: نشر مكتبات الأنواع

تتضمن مكتبة أدوات الأنواع ما يلي: emitDeclarationOnly: true، وتصدير الأنواع من src/index.ts، وإدارة الإصدارات باستخدام semver، واختبارها باستخدام tsd، وتوثيقها باستخدام TSDoc، ونشرها إلى npm أو سجل workspace.

تحقق سريع

ما خيار tsconfig الذي ينشئ ملفات .d.ts فقط دون إخراج JavaScript؟

ما تعلمته

يتطلب نشر مكتبة أدوات للأنواع استخدام emitDeclarationOnly، وحقول package.json المناسبة، واختبارات على مستوى الأنواع باستخدام tsd، وتعليقات TSDoc، والإصدار الدلالي. شارك أدواتك مع المجتمع أو عبر مستودعك متعدد الحزم.

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

هل درس «نشر مكتبة أدوات الأنواع» مجاني؟

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

ماذا ستتعلم في «نشر مكتبة أدوات الأنواع»؟

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

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

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

كم من الوقت يستغرق درس «نشر مكتبة أدوات الأنواع»؟

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

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

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

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

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