‏React Query Key Manager: مدیریت type-safe کلیدهای query

مدیریت query keyها در پروژه‌های بزرگ React Query یه دردسر واقعیه. وقتی چند توسعه‌دهنده روی یه پروژه کار می‌کنن، رشته‌هایی مثل "user" یا "profile" ممکنه چندجا تکرار بشن و باعث تداخل کش یا باگ‌های سخت‌یاب بشن. React Query Key Manager یه کتابخانه سبک (حدود ۶۰ خط کد) هست که این مشکل رو با یه API تایپ‌سیف و ساختارمند حل می‌کنه.

کار با این کتابخانه خیلی ساده‌ست. با تابع defineQueryKeys یه مجموعه نام‌فضابندی‌شده از کلیدها تعریف می‌کنی و هر کلید رو با key() می‌پوشونی تا هم type safety داشته باشی هم قابلیت ترکیب:

export const userKeys = defineQueryKeys("user", {
  profile: key((userId: string) => ["user", "profile", userId]),
  list: key(() => ["user", "list"]),
});

بعد از تعریف، کلیدها رو مستقیم توی useQuery استفاده می‌کنی: queryKey: userKeys.profile(userId). اگه پارامتر اشتباه بدی — مثلاً عدد به‌جای رشته — TypeScript سر وقت کامپایل خطا می‌ده، نه در runtime.

یکی از قابلیت‌های جالب Key Composition هست؛ یعنی می‌شه کلیدهای مختلف رو با هم ترکیب کرد. با صدا زدن یه کلید به‌شکل key()() آرایه خامش رو می‌گیری و می‌تونی اون رو spread کنی توی یه کلید جدیدتر. این برای کوئری‌های وابسته به هم خیلی کاربردیه.

همچنین اگه دوبار یه namespace یکسان رجیستر کنی، در محیط توسعه بلافاصله یه خطای runtime می‌بینی: Query key name "user" has already been registered. این ویژگی جلوی تداخل ناخواسته رو می‌گیره. برای پروژه‌های بزرگ هم می‌شه کلیدها رو به‌صورت nested سازماندهی کرد، مثلاً adminKeys.users.list(1).

نسخه ۰.۰.۲ یه سری تغییرات breaking داشته: QueryKeyManager.create() حذف شده و باید به defineQueryKeys() تغییر بدی، defineKey() هم جاش key() اومده. این تغییرات برای ساده‌تر شدن API و type safety بهتر انجام شده.

نکات کلیدی:

• مشکل رشته‌های جادویی پراکنده و تداخل کلیدها رو حل می‌کنه
• تایپ‌سیف کامل با TypeScript 5.0+، خطاها در زمان کامپایل گرفته می‌شن
• پشتیبانی از namespace تودرتو برای پروژه‌های بزرگ
• قابلیت ترکیب کلیدها برای کوئری‌های وابسته
• سازگار با React Query نسخه‌های v4 و v5
• بدون dependency خارجی، حدود ۶۰ خط کد خالص TypeScript