@sdxc/uuid 0.0.0-pre.1

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergio Xalambrí
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,230 @@
+# @sdxc/uuid
+
+Validate, assert and generate UUIDs behind a branded UUID type.
+
+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.
+
+## Installation
+
+```bash
+npm add @sdxc/uuid
+```
+
+`generateUUID` calls the platform's
+[`crypto.randomUUID()`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/randomUUID).
+[`@sdxc/typeid`](https://www.npmjs.com/package/@sdxc/typeid) installs alongside it when you
+want prefixed identifiers built on these values.
+
+## Usage
+
+### Generate An Identifier
+
+```typescript
+import { generateUUID } from "@sdxc/uuid";
+
+let id = generateUUID();
+// "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" as UUID
+```
+
+The longhand is `crypto.randomUUID()` followed by the check that brands its result, which is
+what lets the value flow into anything typed as `UUID` without a cast.
+
+### Narrow A String You Received
+
+```typescript
+import { isUUID } from "@sdxc/uuid";
+
+let value = "550e8400-e29b-41d4-a716-446655440000";
+
+if (isUUID(value)) {
+	// value is UUID here
+}
+```
+
+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
+}
+```
+
+`assertUUID` throws rather than returning, which suits the edge of a system: the value is an
+identifier or the request stops here.
+
+### Tell The Failures Apart
+
+```typescript
+import {
+	assertUUID,
+	InvalidUUIDFormatError,
+	InvalidUUIDLengthError,
+	InvalidUUIDTypeError,
+} from "@sdxc/uuid";
+
+try {
+	assertUUID(value);
+} 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) {
+		// 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.
+
+### `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.
+
+### `generateUUID(): UUID`
+
+Returns a new random UUID from `crypto.randomUUID()`, already narrowed to `UUID`. That is a
+version 4 UUID as defined by [RFC 9562](https://www.rfc-editor.org/rfc/rfc9562), random in
+every position the format leaves free.
+
+### Errors
+
+#### `InvalidUUIDTypeError`
+
+Validation received something that is not a string. The message names the runtime type that
+arrived, as in `Expected a string, got object`.
+
+#### `InvalidUUIDLengthError`
+
+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.
+
+#### `InvalidUUIDFormatError`
+
+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`.
+
+## Pattern: Narrowing Once At The Edge
+
+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:
+
+```typescript
+import type { UUID } from "@sdxc/uuid";
+
+import { assertUUID } from "@sdxc/uuid";
+
+export async function GET(request: Request) {
+	let accountId = new URL(request.url).pathname.split("/").at(-1) ?? "";
+	assertUUID(accountId);
+
+	return Response.json(await loadAccount(accountId));
+}
+
+async function loadAccount(accountId: UUID) {
+	// no re-validation: the type already carries the check
+}
+```
+
+The throw is the point: an identifier that never validated never reaches the query.
+
+## Pattern: Branching Instead Of 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:
+
+```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");
+	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: 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:
+
+```typescript
+import { TypeID } from "@sdxc/typeid";
+import { generateUUID } from "@sdxc/uuid";
+
+let accountId = TypeID.fromUUID("account", generateUUID());
+
+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.
+
+## Versioning
+
+Releases are dated rather than semantic. A version is the UTC date it was published,
+written `YYYY.M.D`, so `2026.9.4` is the release from 4 September 2026. At most one
+release goes out per day.
+
+Those numbers say when, not what: a later date means a later release and carries no
+compatibility promise. Any release may change or remove an export.
+
+Depend on one exact date, and move it when you are ready to take the change:
+
+```json
+{
+	"dependencies": {
+		"@sdxc/uuid": "2026.9.4"
+	}
+}
+```
+
+A caret or tilde range reads the date as major, minor and patch, so it accepts every
+later release in the same year. An exact version keeps the upgrade yours to schedule.
+
+## License
+
+MIT
+
+## Author
+
+[Sergio Xalambrí](https://sergiodxa.com)

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { InvalidUUIDFormatError, InvalidUUIDLengthError, InvalidUUIDTypeError } from "./lib/errors.js";
+import type { UUID as BaseUUID } from "node:crypto";
+export type UUID = BaseUUID & {
+    __brand: "UUID";
+};
+export declare function isUUID(value: string): value is UUID;
+export declare function assertUUID(value: string): asserts value is UUID;
+export declare function generateUUID(): UUID;
+export { InvalidUUIDFormatError, InvalidUUIDLengthError, InvalidUUIDTypeError };

package/dist/index.js

@@ -0,0 +1,29 @@
+/**
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { InvalidUUIDFormatError, InvalidUUIDLengthError, InvalidUUIDTypeError, } from "./lib/errors.js";
+export function isUUID(value) {
+    try {
+        assertUUID(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function assertUUID(value) {
+    if (typeof value !== "string")
+        throw new InvalidUUIDTypeError(typeof value);
+    if (value.length !== 36)
+        throw new InvalidUUIDLengthError(value.length);
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(value)) {
+        throw new InvalidUUIDFormatError(value);
+    }
+}
+export function generateUUID() {
+    let id = crypto.randomUUID();
+    assertUUID(id);
+    return id;
+}
+export { InvalidUUIDFormatError, InvalidUUIDLengthError, InvalidUUIDTypeError };

package/dist/lib/errors.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** Error thrown when a UUID string has an invalid length. */
+export declare class InvalidUUIDLengthError extends Error {
+    name: string;
+    /**
+     * Creates an invalid UUID length error.
+     * @param length Actual UUID length.
+     * @example
+     * throw new InvalidUUIDLengthError(10);
+     */
+    constructor(length: number);
+}
+/** Error thrown when a UUID value is not a string. */
+export declare class InvalidUUIDTypeError extends Error {
+    name: string;
+    /**
+     * Creates an invalid UUID type error.
+     * @param type Runtime type received instead of a UUID string.
+     * @example
+     * throw new InvalidUUIDTypeError("number");
+     */
+    constructor(type: string);
+}
+/** Error thrown when a UUID string does not match the expected format. */
+export declare class InvalidUUIDFormatError extends Error {
+    name: string;
+    /**
+     * Creates an invalid UUID format error.
+     * @param uuid UUID value that failed format validation.
+     * @example
+     * throw new InvalidUUIDFormatError("not-a-uuid");
+     */
+    constructor(uuid: string);
+}

package/dist/lib/errors.js

@@ -0,0 +1,43 @@
+/**
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** Error thrown when a UUID string has an invalid length. */
+export class InvalidUUIDLengthError extends Error {
+    name = "InvalidUUIDLengthError";
+    /**
+     * Creates an invalid UUID length error.
+     * @param length Actual UUID length.
+     * @example
+     * throw new InvalidUUIDLengthError(10);
+     */
+    constructor(length) {
+        super(`Invalid UUID length: ${length}`);
+    }
+}
+/** Error thrown when a UUID value is not a string. */
+export class InvalidUUIDTypeError extends Error {
+    name = "InvalidUUIDTypeError";
+    /**
+     * Creates an invalid UUID type error.
+     * @param type Runtime type received instead of a UUID string.
+     * @example
+     * throw new InvalidUUIDTypeError("number");
+     */
+    constructor(type) {
+        super(`Expected a string, got ${type}`);
+    }
+}
+/** Error thrown when a UUID string does not match the expected format. */
+export class InvalidUUIDFormatError extends Error {
+    name = "InvalidUUIDFormatError";
+    /**
+     * Creates an invalid UUID format error.
+     * @param uuid UUID value that failed format validation.
+     * @example
+     * throw new InvalidUUIDFormatError("not-a-uuid");
+     */
+    constructor(uuid) {
+        super(`Invalid UUID format: ${uuid}`);
+    }
+}

package/package.json

@@ -0,0 +1,19 @@
+{
+	"name": "@sdxc/uuid",
+	"version": "0.0.0-pre.1",
+	"description": "Validate, assert and generate UUIDs behind a branded UUID type",
+	"license": "MIT",
+	"type": "module",
+	"exports": {
+		".": "./dist/index.js"
+	},
+	"gitHead": "e96a064f9208eb667923f57374e2cdaac73c72fb",
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/sergiodxa/monorepo.git",
+		"directory": "packages/uuid"
+	}
+}