@sdxc/uuid 2026.10.12 → 2026.10.13

package/README.md

@@ -2,51 +2,43 @@
 
 Validate and assert UUIDs behind a branded UUID type, and generate v4 or v7 values.
 
-A UUID reaches your code as a `string`, and every layer below re-checks it because the type
-says nothing. This package checks once and hands back a `UUID`: the same string, carrying
-proof of the check in its type, so a function that asks for a `UUID` cannot be handed the
-raw path segment it came from.
+A `UUID` is the same string, carrying proof of the check in its type: validate once where the
+value enters, and every function below can ask for a `UUID` instead of re-checking a `string`.
 
 ## Installation
 
-```bash
+```sh
 npm add @sdxc/uuid
 ```
 
 The generators use the platform's Web Crypto API, available in browsers, Node, Bun, Deno and
-Cloudflare Workers. [`@sdxc/typeid`](https://www.npmjs.com/package/@sdxc/typeid) installs alongside it when you
-want prefixed identifiers built on these values.
+Cloudflare Workers.
 
 ## Usage
 
-### Generate An Identifier
+### Generate an identifier
 
-Each UUID version is its own entry point, and each exports the same `generateUUID()`. The
-import path picks the version, so switching an identifier to the other one changes only that
-line.
+Each UUID version is its own entry point exporting the same `generateUUID()`, so the import
+path picks the version.
 
 ```typescript
 import { generateUUID } from "@sdxc/uuid/v7";
 
 let id = generateUUID();
-// "019a6f3e-5c21-7a4b-9d3e-8f1a2b3c4d5e" as UUID
+// "019a6f3e-5c21-7a4b-9d3e-8f1a2b3c4d5e", typed UUID
 ```
 
-A v7 value starts with the millisecond it was created, so identifiers sort in creation order
-and new database rows append to the end of their primary-key index. Import from
-`@sdxc/uuid/v4` instead when the identifier must not reveal when it was created:
+A v7 value starts with its creation time, so values sort in the order they were generated.
+Import from `@sdxc/uuid/v4` for a fully random value that reveals nothing:
 
 ```typescript
 import { generateUUID } from "@sdxc/uuid/v4";
 
 let id = generateUUID();
-// "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" as UUID
+// "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", typed UUID
 ```
 
-Either way the result is already branded, so it flows into anything typed as `UUID` without a
-cast.
-
-### Narrow A String You Received
+### Check a string you received
 
 ```typescript
 import { isUUID } from "@sdxc/uuid";
@@ -58,26 +50,12 @@ if (isUUID(value)) {
 }
 ```
 
-A value passes when it is a string of exactly 36 characters shaped `8-4-4-4-12` in lowercase
-hex. Uppercase and the brace-wrapped form both fail, so the identifiers you store and compare
-have one spelling. The version and variant digits are read as hex like any other, so the
-check is about the format rather than which UUID version produced it.
-
-### Assert At A Boundary
-
-```typescript
-import { assertUUID } from "@sdxc/uuid";
-
-function readAccountId(value: string) {
-	assertUUID(value);
-	return value; // typed UUID from here on
-}
-```
+A UUID is exactly 36 characters of lowercase hex shaped `8-4-4-4-12`, so stored identifiers
+have one spelling. Any version passes.
 
-`assertUUID` throws rather than returning, which suits the edge of a system: the value is an
-identifier or the request stops here.
+### Assert and tell the failures apart
 
-### Tell The Failures Apart
+`assertUUID` narrows the value for the rest of the scope, or throws one of three error classes.
 
 ```typescript
 import {
@@ -89,128 +67,142 @@ import {
 
 try {
 	assertUUID(value);
+	// value is UUID from here on
 } catch (error) {
 	if (error instanceof InvalidUUIDTypeError) {
-		// something other than a string arrived
-	}
-
-	if (error instanceof InvalidUUIDLengthError) {
-		// a string of the wrong length: "Invalid UUID length: 10"
-	}
-
-	if (error instanceof InvalidUUIDFormatError) {
+		// not a string: "Expected a string, got object"
+	} else if (error instanceof InvalidUUIDLengthError) {
+		// wrong length: "Invalid UUID length: 10"
+	} else if (error instanceof InvalidUUIDFormatError) {
 		// 36 characters in the wrong shape
 	}
 }
 ```
 
-Three classes rather than one message, so a truncated identifier and a mistyped one are
-distinguishable when you decide what to answer.
-
 ## API
 
-### `UUID`
-
-The UUID string type, branded. A plain `string` is not assignable to it, and a `UUID` is
-assignable anywhere a `string` is, so the brand costs nothing at the call sites that only
-read the value.
-
 ### `isUUID(value: string): value is UUID`
 
-Reports whether a string is a UUID, narrowing it to `UUID` inside the branch that takes it.
-Use it where an invalid value is an outcome you handle.
+Returns `true` when the value is a lowercase `8-4-4-4-12` hex string, narrowing it to `UUID`.
+Accepts exactly the values `assertUUID` accepts.
 
 ### `assertUUID(value: string): asserts value is UUID`
 
-Narrows a string to `UUID` for the rest of the enclosing scope, throwing when it is not one:
-`InvalidUUIDTypeError` for a non-string, `InvalidUUIDLengthError` for a string that is not 36
-characters, and `InvalidUUIDFormatError` for 36 characters in the wrong shape.
+Narrows the value to `UUID`, or throws `InvalidUUIDTypeError` for a non-string,
+`InvalidUUIDLengthError` for a length other than 36, and `InvalidUUIDFormatError` otherwise.
 
 ### `generateUUID(): UUID` from `@sdxc/uuid/v7`
 
-Returns a new version 7 UUID as defined by [RFC 9562](https://www.rfc-editor.org/rfc/rfc9562):
-a 48-bit millisecond timestamp, a 12-bit counter and 62 random bits. Values sort in the order
-they were generated, including several created in the same millisecond, which matters on
-runtimes such as Cloudflare Workers where `Date.now()` holds still until the next I/O. The
-guarantee holds within one process or isolate; values from two processes in the same
-millisecond are unique and share no defined order.
-
-The timestamp is readable by anyone holding the value, including through a
-[`@sdxc/typeid`](https://www.npmjs.com/package/@sdxc/typeid) prefix. Use it for identifiers
-whose creation time is fine to expose, and keep secrets on random values.
+Returns a version 7 UUID ([RFC 9562](https://www.rfc-editor.org/rfc/rfc9562)): a 48-bit
+millisecond timestamp, a 12-bit counter and 62 random bits. Each value sorts after the previous
+one from the same process, including within one millisecond. Anyone holding the value can read
+its creation time.
 
 ### `generateUUID(): UUID` from `@sdxc/uuid/v4`
 
-Returns a new version 4 UUID from `crypto.randomUUID()`: 122 random bits, so two values carry
-no ordering and none reveals when it was created.
+Returns a version 4 UUID from `crypto.randomUUID()`: 122 random bits, with no ordering and no
+creation time.
+
+### `InvalidUUIDTypeError`
 
-### Errors
+Thrown for a non-string; the message names the type received.
 
-#### `InvalidUUIDTypeError`
+### `InvalidUUIDLengthError`
 
-Validation received something that is not a string. The message names the runtime type that
-arrived, as in `Expected a string, got object`.
+Thrown for a string that is not 36 characters; the message names the length.
 
-#### `InvalidUUIDLengthError`
+### `InvalidUUIDFormatError`
 
-A string of the wrong length, reported as `Invalid UUID length: 10`. The check runs before
-the shape check, so a truncated identifier says so instead of reading as malformed.
+Thrown for 36 characters that are not lowercase `8-4-4-4-12` hex; the message repeats the value.
 
-#### `InvalidUUIDFormatError`
+### Types
 
-A 36-character string that is not lowercase `8-4-4-4-12` hex. The message repeats the value
-that failed, as in `Invalid UUID format: 550e8400_e29b_41d4_a716_446655440000`.
+#### `UUID`
 
-## Pattern: Narrowing Once At The Edge
+A branded UUID string. A plain `string` must pass `isUUID` or `assertUUID` to become one, and a
+`UUID` is usable anywhere a `string` is.
 
-An identifier arrives as text — a path segment, a query parameter, a form field — and every
-function under the handler wants it typed. Assert it where it enters, and the signatures
-below can ask for a `UUID` and be sure they have one:
+## Pattern: Narrow Once At The Edge
+
+Assert an identifier where it enters a request handler, and the functions below take a `UUID`
+without re-validating.
 
 ```typescript
 import type { UUID } from "@sdxc/uuid";
 
-import { assertUUID } from "@sdxc/uuid";
+import { assertUUID, InvalidUUIDLengthError, InvalidUUIDFormatError } from "@sdxc/uuid";
 
-export async function GET(request: Request) {
+export async function handler(request: Request) {
 	let accountId = new URL(request.url).pathname.split("/").at(-1) ?? "";
-	assertUUID(accountId);
+
+	try {
+		assertUUID(accountId);
+	} catch (error) {
+		if (error instanceof InvalidUUIDLengthError || error instanceof InvalidUUIDFormatError) {
+			return new Response("Not Found", { status: 404 });
+		}
+		throw error;
+	}
 
 	return Response.json(await loadAccount(accountId));
 }
 
 async function loadAccount(accountId: UUID) {
-	// no re-validation: the type already carries the check
+	return { id: accountId };
 }
 ```
 
-The throw is the point: an identifier that never validated never reaches the query.
-
-## Pattern: Branching Instead Of Throwing
+## Pattern: Validate A Form Field Without Throwing
 
-A form field is a value a person can get wrong, which makes an exception the wrong shape for
-the answer. `isUUID` gives you the same narrowing in an expression you can branch on:
+A person can mistype a field, so branch on `isUUID` and answer with a result.
 
 ```typescript
 import type { UUID } from "@sdxc/uuid";
 
 import { isUUID } from "@sdxc/uuid";
 
-function readAccountId(input: FormData): { ok: true; accountId: UUID } | { ok: false } {
-	let value = input.get("accountId");
+function readAccountId(form: FormData): { ok: true; accountId: UUID } | { ok: false } {
+	let value = form.get("accountId");
 	if (typeof value !== "string" || !isUUID(value)) return { ok: false };
 	return { ok: true, accountId: value };
 }
 ```
 
-`isUUID` is `assertUUID` with the throw turned into a `false`, so the two agree on exactly
-which strings are identifiers.
+## Pattern: Time-Ordered Record Ids
+
+Use v7 for primary keys: new rows append to the end of the index, and sorting by id sorts by
+creation, so the last id of a page is enough of a cursor for the next one.
+
+```typescript
+import type { UUID } from "@sdxc/uuid";
+
+import { generateUUID } from "@sdxc/uuid/v7";
+
+interface Note {
+	id: UUID;
+	body: string;
+}
+
+let notes: Note[] = [];
+
+function createNote(body: string): Note {
+	let note = { id: generateUUID(), body };
+	notes.push(note);
+	return note;
+}
+
+function notesAfter(cursor: UUID | null, limit: number) {
+	return notes.filter((note) => cursor === null || note.id > cursor).slice(0, limit);
+}
+```
+
+Reach for `@sdxc/uuid/v4` when an identifier must not reveal when it was created, such as a
+public share id.
 
 ## Pattern: Prefixed Identifiers
 
-A UUID says nothing about what it identifies, which is why an identifier pasted into a bug
-report is so hard to place. [`@sdxc/typeid`](https://www.npmjs.com/package/@sdxc/typeid)
-takes a `UUID` and a prefix and encodes them as one sortable, self-describing string:
+[`@sdxc/typeid`](https://www.npmjs.com/package/@sdxc/typeid) takes a `UUID` and a prefix and
+encodes them as one self-describing string that keeps the v7 sort order.
 
 ```typescript
 import { TypeID } from "@sdxc/typeid";
@@ -222,10 +214,6 @@ accountId.toString();
 // "account_01h455vb4pex5vsknk084sn02q"
 ```
 
-It asks for a `UUID` rather than a `string`, so the value you generate here is accepted and a
-random 36 characters is not. TypeID keeps the UUID's sort order, so a v7 identifier stays
-time-ordered once it is prefixed.
-
 ## Versioning
 
 Releases are dated rather than semantic. A version is the UTC date it was published,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sdxc/uuid",
-	"version": "2026.10.12",
+	"version": "2026.10.13",
 	"description": "Validate and assert UUIDs behind a branded UUID type, and generate v4 or v7 values",
 	"license": "MIT",
 	"type": "module",
@@ -9,7 +9,7 @@
 		"./v4": "./dist/v4.js",
 		"./v7": "./dist/v7.js"
 	},
-	"gitHead": "857ef87ddb0b2484e28b46431d0740fcc80e5f33",
+	"gitHead": "5ff758a57e35480a8db7abd24f1d9527b81bfb51",
 	"publishConfig": {
 		"access": "public"
 	},