UUIDv7

Cada id de registro storh es un UUIDv7: una marca de tiempo de 48 bits en milisegundos seguida de entropía aleatoria, con el formato estándar de UUID de 36 caracteres. Como la marca de tiempo va primero, los ids se ordenan por hora de creación, y esta propiedad permite la mayoría de las funciones de storh: paginación por cursor (after($id)), lecturas por intervalo de tiempo, omisión de segmentos en el registro y orden estable en todas partes.

$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);

La generación es monotónica dentro de un proceso: los ids creados en el mismo milisegundo incrementan la entropía anterior en vez de volver a sortearla, por lo que incluso las ráfagas de escrituras rápidas mantienen el orden de creación.

Localización temporal

Para los intervalos de tiempo, storh obtiene los valores mínimo y máximo posibles de UUIDv7 para una marca de tiempo en milisegundos y compara los ids con esos límites:

$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);

Por eso las lecturas por intervalo de tiempo no necesitan un campo de marca de tiempo en los datos del registro: el id contiene la hora de creación.

Proporcionar ids propios

Todos los motores aceptan un id explícito por escritura ($docs->put($data, $id)) y un invocable id_generator en sus constructores. Los ids de cualquiera de las dos vías se validan como UUIDv7, así que los generadores personalizados deben producirlos; los generadores deterministas permiten que el conjunto de pruebas cree datos de prueba reproducibles. UuidV7::reset_for_tests() restablece el estado de monotonicidad del proceso entre casos de prueba.