حالة عنوان URL بأنواع محدَّدة، في المتصفح والخادم والاختبارات.

المشكلة

حالة عنوان URL حاضرة في أكثر من موضع: في المتصفح، وعلى الخادم، وفي الاختبارات، وفي الروابط التي يتبادلها المستخدمون. وفي أغلب المشاريع تُوصف هذه الحالة أكثر من مرة: دالة تقرؤها في المتصفح، وأخرى على الخادم، وثالثة تكتبها، وقيم افتراضية مكرّرة في كل واحدة. ومع الوقت تختلف هذه النسخ.

نموذج واحد ومحوّلات

في QueryWeave تُعرَّف حالة الاستعلام مرة واحدة في نموذج، ويتولّى محوّل لكل بيئة مزامنتها. والمسار واحد في كل البيئات: يُقرأ نص الاستعلام، ويُتحقَّق منه فيصير حالة محدَّدة الأنواع، ثم تُحدَّث الحالة، ثم تُكتب في العنوان بصيغة قياسية.

import { createQueryRuntime, defineQueryModel, param } from '@queryweave/core'

const productFilters = defineQueryModel({
  search: param.text().optional(),
  page: param.integer({ min: 1 }).default(1),
  archived: param.boolean().default(false),
  sort: param.choice(['name', 'created_at', 'price']).default('created_at'),
  tags: param.list(param.text()).default([]),
})

const runtime = createQueryRuntime({ model: productFilters, adapter })

runtime.read().values.page // 1

await runtime.update({ search: 'vue', page: 1 })
await runtime.update({ page: 2 }, { navigation: 'replace' })

await runtime.transaction((draft) => {
  draft.search = 'vue'
  draft.page = 1
})

والرابط الذي فيه خطأ لا يعطّل الصفحة. فالاستعلام ?page=abc يُقرأ على أنه الصفحة 1، ومع النتيجة ملاحظة تبيّن السبب، فيستطيع التطبيق أن يكمل عمله وأن يُعلم المستخدم.

الاستعمال في Vue

const filters = useQueryModel(productFilters)

filters.values.page // readonly reactive state
await filters.update({ page: 2 }) // explicit operation

const search = filters.field('search', { navigation: 'replace' }) // v-model target

لا دالة خاصة بكل مفتاح، ولا دالة تعيين تُرجَع مع القيمة، ولا تعديل مباشر للحالة. و Vue و Nuxt أول ما دعمتُه من الواجهات، لكن تصميم النواة لا يعتمد على أيٍّ منهما.

تسع حزم

وهذه الحدود مفروضة: يفشل الأمر pnpm bundle:size:check إذا تجاوزت حزمةٌ حدّها.

الاختبارات

قبل كل إصدار تُشغَّل كل مشاريع Vitest، ومنها الاختبارات داخل المتصفح واختبارات الأنواع، ثم اختبارات في متصفحات فعلية هي Chromium و Firefox و WebKit، ثم Playwright على تطبيق التجربة. وتُفحص حدود الحزم في المصادر وملفات التعريف ومخطط التبعيات، ويُفحص ما يُبنى وملفات الأنواع المرافقة له، ثم تُثبَّت الحزم بعد تحزيمها في مشاريع نظيفة للتأكد من أنها تعمل عند من يستعملها.

والمشروع تجريبي ولم يبلغ الإصدار 1.0 بعد: قد تتغيّر واجهته العامة بين إصدار وآخر، وكل تغيير غير متوافق يُدوَّن في سجل القرارات المعمارية وفي changeset.