From ee876fda04910131c10a9ff8d370426d2e03b2c1 Mon Sep 17 00:00:00 2001 From: Tomas Zijdemans Date: Thu, 6 Aug 2026 11:21:55 +0200 Subject: [PATCH] docs(uuid): document that v7 UUIDs are not monotonic within a millisecond --- uuid/v7.ts | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/uuid/v7.ts b/uuid/v7.ts index f011b24892cd..aad71429696c 100644 --- a/uuid/v7.ts +++ b/uuid/v7.ts @@ -6,6 +6,10 @@ * * UUID Version 7 is defined in {@link https://www.rfc-editor.org/rfc/rfc9562.html#section-5.7 | RFC 9562}. * + * UUIDv7 values sort by creation time at millisecond precision. Values + * generated within the same millisecond sort in arbitrary order relative to + * each other, see {@linkcode generate} for details. + * * ```ts * import { generate, validate, extractTimestamp } from "@std/uuid/v7"; * import { assert, assertEquals } from "@std/assert"; @@ -46,6 +50,11 @@ export function validate(id: string): boolean { /** * Generates a {@link https://www.rfc-editor.org/rfc/rfc9562.html#section-5.7 | UUIDv7}. * + * All bits after the 48-bit timestamp are random, so UUIDs generated within + * the same millisecond do not sort in generation order: this implementation + * uses none of the optional monotonicity methods of + * {@link https://www.rfc-editor.org/rfc/rfc9562.html#section-6.2 | RFC 9562 section 6.2}. + * * @throws {RangeError} If the timestamp is not a non-negative integer. * * @param timestamp Unix Epoch timestamp in milliseconds.