الاستعلامات وعمليات Mutation والاشتراكات

اربط ‎.input(zodSchema).query(async ({ input, ctx }) => ...)‎ مع publicProcedure. يستقبل المعالج المدخلات التي تم التحقق منها وسياق الطلب. ويمكنه إرجاع أي قيمة قابلة للتسلسل، مثل كائن أو مصفوفة أو قيمة بدائية.

يُستنتج نوع القيمة المرجعة تلقائيًا، ويصبح نوع البيانات لخطاف useQuery المقابل على العميل.

يستدعي trpc.post.getById.useQuery({ id: '1' }) الإجراء getById في موجّه post. ويُرجع الخطاف كائن النتائج المألوف في React Query: { data, isLoading, isError, refetch }.

كائن الإدخال مكتوب بالأنواع بشكل ثابت: تمرير { id: 123 } عندما يتوقع المخطط سلسلة نصية يُعد خطأً في TypeScript يكتشفه أثناء التطوير.

استخدم ‎.input(zodSchema).mutation(async ({ input, ctx }) => ...)‎ لتنفيذ عمليات الكتابة على الخادم، مثل إنشاء البيانات أو تحديثها أو حذفها. تُستدعى عمليات mutation صراحةً، ولا تعمل عند تحميل المكوّن.

يتمتع معالج mutation بإمكانية الوصول إلى سياق الطلب الكامل، بما في ذلك الجلسة من NextAuth، عبر ctx.

استخدم const { mutate, isLoading, error } = trpc.post.create.useMutation(). ثم استدعِ mutate({ title: 'New', content: '...' }) لتشغيل عملية mutation. وكما هي الحال مع useMutation في React Query، لا تعمل هذه العملية عند تحميل المكوّن.

مرّر دالتَي الاستدعاء onSuccess وonError إلى خيارات useMutation لتنفيذ الآثار الجانبية بعد عملية mutation.

لتحديث بيانات الاستعلام بعد نجاح عملية mutation، استخدم خطاف أدوات tRPC: const utils = trpc.useUtils(). وفي onSuccess، استدعِ utils.post.getAll.invalidate() لإعادة جلب قائمة المنشورات.

هذا هو المكافئ في tRPC للدالة queryClient.invalidateQueries() في React Query، ويتبع النمط نفسه المتمثل في اعتبار البيانات قديمة ثم إعادة جلبها.

تستخدم tRPC مكتبة Zod للتحقق من صحة المدخلات بشكل افتراضي. يعمل مخطط Zod على الخادم أثناء وقت التشغيل، ويرفض المدخلات غير السليمة قبل وصولها إلى المعالج. كما يوفّر المخطط نفسه أنواع TypeScript للعميل.

يلغي هذا الدور المزدوج، أي التحقق أثناء وقت التشغيل وتوفير أنواع TypeScript، الازدواجية؛ إذ تعرّف العقد مرة واحدة في Zod وتحصل على ضمانَي الأمان معًا.

تستخدم tRPC افتراضيًا httpBatchLink، الذي يجمع عدة طلبات tRPC متزامنة في طلب HTTP واحد. تُرسل استدعاءات useQuery المتعددة في دورة عرض المكوّن نفسها معًا، وتُعالَج معًا.

يقلل ذلك من الحمل على الشبكة بدرجة كبيرة مقارنةً بإرسال طلب HTTP منفصل لكل استعلام في صفحة تتطلب بيانات متعددة.

عرّف إجراء اشتراك: publicProcedure.subscription(async function*() { while (true) { yield await nextEvent(); } }). تستخدم الاشتراكات مولدات غير متزامنة، وتتطلب وسيلة نقل عبر WebSocket.

تُعد الاشتراكات مثالية للميزات الفورية، مثل الإشعارات المباشرة ومؤشرات التحرير التعاوني أو استجابات الذكاء الاصطناعي المتدفقة.

استبدل httpBatchLink بمزيج من httpBatchLink وwsLink باستخدام splitLink: وجّه الاشتراكات إلى wsLink، والاستعلامات وعمليات mutation إلى httpBatchLink. أنشئ عميل WebSocket باستخدام createWSClient({ url: 'ws://localhost:3000' }).

يعني هذا النقل الهجين أن معظم الطلبات تستخدم تجميع HTTP الفعّال، بينما تستخدم الاشتراكات اتصالات WebSocket مستمرة.

يشترك trpc.notifications.onNew.useSubscription(undefined, { onData: (notification) => addToList(notification), onError: console.error }) في الإجراء. ويُستدعى رد النداء onData مع كل قيمة يتم توليدها.

تُعاد تهيئة الاشتراك تلقائيًا إذا انقطع اتصال WebSocket ثم أُعيد الاتصال.

قد تستخدم صفحة قائمة فورية استعلامًا لتحميل القائمة الأولية، وعملية mutation لإضافة عنصر، واشتراكًا لتلقي الإضافات المباشرة من المستخدمين الآخرين. وتكون الأنواع الثلاثة مرتبطةً بـ AppRouter نفسه، كما تتكامل طبيعيًا.

تعتمد استراتيجية إبطال ذاكرة التخزين المؤقت على تفضيلك لإعادة الجلب الكامل، عبر الإبطال بعد عملية mutation، أو تحديث ذاكرة التخزين المؤقت، عبر utils.post.getAll.setData.

ما طريقة أداة tRPC التي تؤدي إلى إعادة جلب استعلام بعد نجاح عملية mutation؟

عرّف الاستعلامات باستخدام ‎.query()‎ وعمليات mutation باستخدام ‎.mutation()‎، مع التحقق من صحة كليهما بواسطة مخططات Zod. وعلى العميل، استخدم trpc.router.procedure.useQuery() وuseMutation(). أبطِل الاستعلامات بعد عملية mutation باستخدام utils.procedure.invalidate(). تستخدم الاشتراكات مولدات غير متزامنة، وتتطلب wsLink لنقل WebSocket.

يجمع httpBatchLink الاستعلامات المتزامنة في طلب HTTP واحد بشكل افتراضي.