النوع Record في TypeScript: شرح Record<K, V> بالأمثلة

Record<K, V> نوع أداة مدمج لكائن مفاتيحه من النوع K وكل قيمه من النوع V. مع مفاتيح string يصف قاموسًا؛ ومع union من المفاتيح الحرفية يصف كائنًا يجب أن يملك هذه المفاتيح تحديدًا.

// Any string key, number values
const stock: Record<string, number> = { apples: 12, pears: 0 };
stock.plums = 7;

// Exactly these three keys, each with a string value
type Lang = "en" | "de" | "fr";
const greeting: Record<Lang, string> = {
  en: "Hello",
  de: "Hallo",
  fr: "Bonjour",
};

console.log(stock);          // { apples: 12, pears: 0, plums: 7 }
console.log(greeting.de);    // Hallo

Record موجود في نظام الأنواع فقط. وقت التشغيل الكائنان كائنا JavaScript عاديان، فيعملان مع الكائنات الحرفية والنشر وJSON.stringify وكل ما يأخذ كائنًا.

الصياغة والتعريف

Record<Keys, Value>

يجب أن يكون Keys شيئًا يصلح مفتاحًا لكائن: string أو number أو symbol أو union من أنواع حرفية نصية أو رقمية أو نوع template literal. ويمكن أن يكون Value أي نوع. التعريف كاملًا في المكتبة القياسية لـ TypeScript سطر واحد، وهو mapped type:

type Record<K extends keyof any, T> = {
  [P in K]: T;
};

keyof any هو string | number | symbol، أي مجموعة كل أنواع المفاتيح الممكنة. و[P in K]: T ينشئ خاصية واحدة من النوع T لكل عضو في K. وهذا يفسر السلوكين التاليين: K الواسع مثل string ينتج index signature (أي مفتاح)، وK من نوع union ينتج خاصية إلزامية لكل عضو.

مفاتيح union: كل مفتاح إلزامي

عندما تكون المفاتيح union من أنواع حرفية، يجب أن يذكر Record كلًّا منها، ولا شيء غيرها. وهذا يحوّل المترجم إلى قائمة تحقق:

type Status = "idle" | "loading" | "success" | "error";

const label: Record<Status, string> = {
  idle: "Ready",
  loading: "Loading...",
  success: "Done",
  error: "Something went wrong",
};

const color: Record<Status, `#${string}`> = {
  idle: "#888888",
  loading: "#3b82f6",
  success: "#16a34a",
  error: "#dc2626",
};

function render(s: Status): string {
  return `${label[s]} (${color[s]})`;
}

console.log(render("success")); // Done (#16a34a)

أضف "cancelled" إلى Status فيتوقف الكائنان عن الترجمة حتى تعطي الحالة الجديدة تسمية ولونًا. وحذف مفتاح، أو إضافة مفتاح ليس في union، خطأ ترجمة:

// This does not compile: one key is missing and one is not allowed
type Status = "idle" | "loading" | "success" | "error";

const label: Record<Status, string> = {
  idle: "Ready",
  loading: "Loading...",
  success: "Done",
};

const icon: Record<Status, string> = {
  idle: "o", loading: "~", success: "v", error: "x", paused: "=",
};

index.ts(4,7): error TS2741: Property 'error' is missing in type '{ idle: string; loading: string; success: string; }' but required in type 'Record<Status, string>'.
index.ts(11,54): error TS2353: Object literal may only specify known properties, and 'paused' does not exist in type 'Record<Status, string>'.

ويعمل الأمر نفسه مع enum نصي كنوع للمفاتيح: Record<Color, string> يشترط مُدخلًا لكل عضو في الـ enum.

Record<string, T> والمفتاح المفقود

مع مفاتيح string يُسمح بأي مفتاح، وتعطي TypeScript كل عملية قراءة النوع T، حتى لمفتاح غير موجود. ووقت التشغيل يعطي المفتاح المفقود undefined:

const prices: Record<string, number> = { tea: 2.5, coffee: 3.2 };

const juice = prices["juice"]; // typed number, but undefined at runtime
console.log(juice);            // undefined
console.log(juice * 2);        // NaN, and no compile error

// Check before you use it
if ("juice" in prices) {
  console.log("juice costs", prices.juice);
} else {
  console.log("no juice"); // no juice
}

// Or put undefined in the value type so the compiler makes you check
const safePrices: Record<string, number | undefined> = { tea: 2.5 };
const maybe = safePrices["juice"]; // number | undefined
console.log(maybe ?? 0);           // 0

هذا أشيع أخطاء Record. وهناك ثلاث طرق للتعامل معه: افحص بـ in أو Object.hasOwn قبل القراءة، أو صرّح بالقيمة كـ V | undefined، أو فعّل خيار المترجم noUncheckedIndexedAccess الذي يضيف | undefined إلى كل قراءة عبر index signature في المشروع. أما Record بمفاتيح union فلا يعاني هذه المشكلة، لأن وجود كل مفتاح مضمون.

Partial<Record<K, V>>: بعض المفاتيح فقط

لتستخدم union من المفاتيح دون أن تشترطها كلها، غلّف الـ Record بـ Partial. عندها تعيد القراءات V | undefined، وهذا هو الوصف الصادق:

type Lang = "en" | "de" | "fr" | "ja";

// Translations are optional per language, but only these languages are allowed
const title: Partial<Record<Lang, string>> = {
  en: "Settings",
  de: "Einstellungen",
};

function translate(lang: Lang): string {
  return title[lang] ?? title.en ?? "(missing)";
}

console.log(translate("de")); // Einstellungen
console.log(translate("ja")); // Settings

// Required "en", optional others
type Labels = Record<"en", string> & Partial<Record<Exclude<Lang, "en">, string>>;
const save: Labels = { en: "Save", fr: "Enregistrer" };
console.log(save); // { en: 'Save', fr: 'Enregistrer' }

المفتاح المكتوب خطأً مثل jp يبقى خطأ ترجمة، وهذه هي الميزة مقارنة بـ Record<string, string>.

المرور على Record

Object.keys وObject.values وObject.entries تعمل كلها. والمشكلة في نوع المفتاح: Object.keys يعيد string[] وObject.entries يعيد [string, V][]، ولا يعيدان أبدًا union المفاتيح الخاص بك:

type Plan = "free" | "pro" | "team";
const seats: Record<Plan, number> = { free: 1, pro: 1, team: 10 };

for (const [plan, n] of Object.entries(seats)) {
  console.log(plan, n); // plan is string, n is number
}
// free 1
// pro 1
// team 10

// When you need the union type, cast the keys
const plans = Object.keys(seats) as Plan[];
const total = plans.reduce((sum, p) => sum + seats[p], 0);
console.log(total); // 12

// for...in gives string keys too
for (const key in seats) {
  console.log(key.toUpperCase()); // FREE, PRO, TEAM on separate lines
}

تُبقي TypeScript المفاتيح بالنوع string عن قصد: قد يملك الكائن وقت التشغيل خصائص أكثر مما يذكره نوعه، فالوعد بـ Plan[] غير آمن عمومًا. أما لكائن أنشأته من كائن حرفي، مثل seats، فالتحويل آمن.

بناء Record من البيانات

الـ Records هي النتيجة المعتادة لتجميع مصفوفة أو فهرستها. ابدأ من كائن فارغ بنوع Record ثم املأه:

interface Book {
  id: string;
  title: string;
  genre: "fiction" | "science" | "history";
}

const books: Book[] = [
  { id: "b1", title: "Dune", genre: "fiction" },
  { id: "b2", title: "Cosmos", genre: "science" },
  { id: "b3", title: "Emma", genre: "fiction" },
];

// Index by id
const byId: Record<string, Book> = {};
for (const b of books) byId[b.id] = b;

// Group by genre (every genre present, even if empty)
const byGenre: Record<Book["genre"], string[]> = { fiction: [], science: [], history: [] };
for (const b of books) byGenre[b.genre].push(b.title);

console.log(byId.b2.title); // Cosmos
console.log(byGenre);       // { fiction: [ 'Dune', 'Emma' ], science: [ 'Cosmos' ], history: [] }

// Object.fromEntries gives { [k: string]: V }, which fits Record<string, V>
const titles: Record<string, string> = Object.fromEntries(books.map((b) => [b.id, b.title]));
console.log(titles); // { b1: 'Dune', b2: 'Cosmos', b3: 'Emma' }

يعيد Book["genre"] استخدام union من الـ interface كنوع للمفاتيح، فإضافة نوع كتب جديد إلى Book تجعل byGenre يطلب مُدخلًا جديدًا.

Record<string, unknown> والـ interfaces

Record<string, unknown> نوع شائع لـ «كائن ما بمفاتيح نصية». يقبل الكائنات الحرفية والقيم المعرّفة بـ type alias، لكنه يرفض الـ interface:

// This does not compile: interfaces have no implicit index signature
interface User {
  name: string;
}

function logFields(obj: Record<string, unknown>) {
  console.log(Object.keys(obj));
}

const user: User = { name: "Ada" };
logFields(user);

index.ts(11,11): error TS2345: Argument of type 'User' is not assignable to parameter of type 'Record<string, unknown>'.
  Index signature for type 'string' is missing in type 'User'.

يمكن توسيع الـ interfaces عبر دمج التعريفات (declaration merging)، لذا لا تفترض TypeScript أنها تناسب index signature؛ أما type aliases فلا يمكن إعادة فتحها، فالنوع type User = { name: string } كان سيمر. والحلول المعتادة: اقبل object بدلًا منه (ويمكنك مع ذلك استدعاء Object.keys عليه)، أو اجعل الدالة generic (<T extends object>(obj: T))، أو عرّف User بـ type (تشرح صفحة interface أم type بقية الفروق).

Record أم index signature أم Map

اختر Record بمفاتيح union كلما كانت مجموعة المفاتيح معروفة: إنه الخيار الوحيد الذي يتحقق من وجود كل مفتاح. وللمفاتيح النصية المفتوحة، Record<string, V> والـ index signature قابلان للتبادل، وكثير من المشاريع تفضّل Record لسهولة قراءته. والجأ إلى Map عندما تُضاف المفاتيح وتُحذف وقت التشغيل، أو عندما لا تكون المفاتيح نصوصًا، أو عندما تحتاج إلى الحجم وترتيب الإدراج دون عمل إضافي.