@cutticat/uuids

Thin wrapper around uuid, plus lenient parse/normalize helpers.

Table of Contents

• Overview
• Installation
• Quick Start
• What is accepted
• API
• Documentation
• Requirements

Overview

Generation is delegated to the uuid package. generateUuid() calls v4(); pass 7 for time-ordered v7. The rest of the API is a small validation and normalization layer that is less strict than most UUID libraries, including uuid.validate().

Canonical UUIDs are 8-4-4-4-12 hex groups. This library also accepts shorter groups and left-pads them with zeros. The point is being able to type identifiers by hand — in a URL, a query, or a fixture — without counting hex digits.

Example: an app with /resource/<uuid> can use /resource/0-0-0-0-1 while debugging.

normalizeUuid("0-0-0-0-1")
→ "00000000-0000-0000-0000-000000000001"

You still need five hyphen-separated groups. RFC version and variant bits are not checked, so debug values like 0-0-0-0-1 are valid here on purpose.

If you need RFC-strict parsing, v1/v3/v5/v6, or the rest of the uuid API, import uuid directly.

Installation

pnpm i @cutticat/uuids

Quick Start

import { generateUuid, isUuid, normalizeUuid, tryNormalizeUuid } from "@cutticat/uuids"

generateUuid() // canonical v4
generateUuid(7) // canonical v7

isUuid("0-0-0-0-1") // true — short groups allowed
isUuid("0-0-0-0-1", true) // false — strict mode wants full 8-4-4-4-12 widths

normalizeUuid("0-0-0-0-1") // "00000000-0000-0000-0000-000000000001"
normalizeUuid("550E8400-E29B-41D4-A716-446655440000")
// "550e8400-e29b-41d4-a716-446655440000"

tryNormalizeUuid("not-a-uuid") // "not-a-uuid" (unchanged)

What is accepted

isUuid(s) / normalizeUuid(s) accept a hyphenated 5-group string. Each group is hex; lengths may be shorter than canonical (up to 8, 4, 4, 4, and 12). Input is treated case-insensitively. Surrounding whitespace is ignored. normalizeUuid lowercases and zero-pads each group.

| Input | isUuid | isUuid(s, true) | normalizeUuid | | --- | --- | --- | --- | | 550e8400-e29b-41d4-a716-446655440000 | true | true | same, lowercased | | 0-0-0-0-1 | true | false | 00000000-0000-0000-0000-000000000001 | | 1-2-3-4-5 | true | false | 00000001-0002-0003-0004-000000000005 | | 550e8400-e29b-41d4-a716-44665544 | true | false | last group padded | | not-a-uuid | false | false | throws | | 550e8400-e29b-41d4-a716 | false | false | throws (four groups) |

Not accepted: missing hyphens, URN (urn:uuid:…), {braces}, extra groups.

tryNormalizeUuid never throws: it normalizes when isUuid(s) is true, otherwise returns the original string.

API

Functions

• generateUuid(version?) — uuid v4 (default) or v7. Throws RangeError for other versions
• isUuid(s, strict?) — whether s looks like a UUID. strict: true requires full 8-4-4-4-12 widths
• normalizeUuid(s) — lowercase + zero-pad groups; throws Error("Invalid UUID") if s is not a UUID
• tryNormalizeUuid(s) — normalizeUuid(s) or the original string if it is not a UUID

Constants

• minUuid — nil UUID (00000000-0000-0000-0000-000000000000), alias of uuid.NIL
• maxUuid — all-ones UUID (ffffffff-ffff-ffff-ffff-ffffffffffff), alias of uuid.MAX
• uuidGroupLengths — group lengths [8, 4, 4, 4, 12]
• uuidLength — canonical length with hyphens (36)
• uuidRegex — allows incomplete groups
• strictUuidRegex — full 8-4-4-4-12 widths only

Documentation

• Project structure
• Scripts
• Style guide
• Contributing

Full API documentation is in JSDoc. Use IDE autocomplete to browse it.

Requirements

• Node.js >= 22.0.0
• pnpm >= 10.17.0
• TypeScript >= 5.9.0