@cutticat/uuids

UUID library.

Table of Contents

• Overview
• Installation
• Quick Start
• API
• Documentation
• Requirements

Overview

The library provides functions for generating, validating, and normalizing UUIDs. Uses the uuid package for v4 generation.

Installation

pnpm i @cutticat/uuids

Quick Start

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

// Generation
generateUuid() // "550e8400-e29b-41d4-a716-446655440000"

// Validation
isUuid("550e8400-e29b-41d4-a716-446655440000") // true
isUuid("550e8400-e29b-41d4-a716", true) // false (strict)

// Normalization
normalizeUuid("550E8400-E29B-41D4-A716-446655440000") // "550e8400-e29b-41d4-a716-446655440000"
tryNormalizeUuid("not-a-uuid") // "not-a-uuid" (unchanged)

API

Functions

• generateUuid() — generates a new UUID v4
• isUuid(s, strict?) — checks whether a string is a valid UUID (strict — full 8-4-4-4-12 format only)
• normalizeUuid(s) — normalizes a UUID (lowercase, zero-padding); throws on invalid string
• tryNormalizeUuid(s) — normalizes a UUID or returns the original string if it is not a UUID

Constants

• uuidGroupLengths — group lengths [8, 4, 4, 4, 12]
• uuidLength — total UUID length with hyphens (36)
• uuidRegex — regular expression (allows incomplete groups)
• strictUuidRegex — strict regular expression (full format only)

Documentation

Detailed documentation:

• Project structure
• Scripts
• Style guide
• Contributing

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

Requirements

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