UUIDv7

معرّف كل سجل في storh هو UUIDv7: طابع زمني بدقة المللي ثانية من 48 بت يتبعه قدر عشوائي، ومنسّق كسلسلة UUID قياسية من 36 محرفًا. وبما أن الطابع الزمني يأتي أولًا، تُرتب المعرّفات حسب وقت الإنشاء، وهذه الخاصية الواحدة تدعم معظم وظائف storh: ترقيم الصفحات بالمؤشر (after($id))، وقراءات النطاقات الزمنية، وتجاوز المقاطع في السجل، والترتيب الثابت في كل مكان.

$id = Storh\UuidV7::generate();

Storh\UuidV7::is_valid($id);          // bool, accepts upper and lower case
Storh\UuidV7::assert_valid($id);      // throws StorageException instead
$timestampMs = Storh\UuidV7::timestamp_ms($id);

يكون التوليد متزايدًا رتيبًا داخل العملية: فالمعرّفات التي تُنشأ في المللي ثانية نفسها تزيد القيمة العشوائية السابقة بدل إعادة توليدها، لذا تظل دفعات الكتابة السريعة مرتبة حسب وقت الإنشاء.

التحديد الزمني

للنوافذ الزمنية، يستنتج storh أصغر وأكبر معرّف UUIDv7 ممكنين لطابع زمني بالمللي ثانية، ثم يقارن المعرّفات بهذين الحدّين:

$query = Storh\RecordQuery::all()->time_range_ms(
    1_700_000_000_000,
    1_700_000_060_000,
);

$lower = Storh\UuidV7::min_for_timestamp_ms(1_700_000_000_000);
$upper = Storh\UuidV7::max_for_timestamp_ms(1_700_000_060_000);

لهذا لا تحتاج قراءات النطاقات الزمنية إلى حقل طابع زمني في بيانات السجل: فالمعرّف يحمل وقت الإنشاء.

تمرير معرّفاتك الخاصة

تقبل جميع المحركات معرّفًا صريحًا لكل عملية كتابة ($docs->put($data, $id)) وقابل استدعاء id_generator في بُناة الكائنات. ويُتحقق من أن المعرّفات من كلا المسارين هي UUIDv7، لذا يجب أن تنتج المولدات المخصصة هذه الصيغة؛ وتُستخدم المولدات الحتمية لإنشاء بيانات اختبار قابلة لإعادة الإنتاج. يمسح UuidV7::reset_for_tests() الحالة الرتيبة على مستوى العملية بين حالات الاختبار.