UUIDv7

Todo id de registro storh é um UUIDv7: um timestamp em milissegundos de 48 bits seguido de entropia aleatória, formatado como um UUID padrão de 36 caracteres. Como o timestamp vem primeiro, os ids são ordenados pela hora de criação, e essa propriedade permite a maioria dos recursos de storh: paginação por cursor (after($id)), leituras por intervalo de tempo, saltos de segmentos no log e ordenação estável em todos os lugares.

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

A geração é monotônica dentro de um processo: ids criados no mesmo milissegundo incrementam a entropia anterior em vez de gerá-la novamente, então até gravações em sequência rápida mantêm a ordem de criação.

Localização por horário

Para intervalos de tempo, storh deriva o menor e o maior UUIDv7 possíveis para um timestamp em milissegundos e compara os ids com esses limites:

$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 isso, leituras por intervalo de tempo não precisam de um campo de timestamp nos dados do registro: o id contém a hora de criação.

Fornecimento dos próprios ids

Todos os mecanismos aceitam um id explícito por gravação ($docs->put($data, $id)) e um callable id_generator em seus construtores. Os ids de qualquer um dos caminhos são validados como UUIDv7, portanto os geradores personalizados precisam produzi-los; geradores determinísticos são usados pelo conjunto de testes para criar fixtures reproduzíveis. UuidV7::reset_for_tests() limpa o estado monotônico do processo entre casos de teste.