core-uuid

A lightweight, zero-dependency, cryptographically secure UUID generator written in TypeScript.

core-uuid provides a fast, reliable, and modern way to generate UUIDs (v4) and optionally gives you access to cryptographically secure random bytes for other use cases. Perfect for Node.js and browser environments.

---

Features

• 🔐 Cryptographically secure (uses Web Crypto API / Node webcrypto)
• ⚡ Zero dependencies – tiny and focused
• 🧩 TypeScript-first – fully typed
• 📏 RFC 4122 compliant – UUID v4 standard
• 🌍 Cross-platform – works in Node and browser
• 🔧 Advanced utilities – access secure random bytes for custom use

---

Installation

npm install core-uuid
# or
yarn add core-uuid

---

Usage

1️⃣ Generate a UUID v4 (Basic)

import { uuidv4 } from "core-uuid";


  const id = uuidv4();
  console.log("Generated UUID v4:", id);
  // Example output: "1757c02d-0aff-4b21-884e-0e5a0c22384d"

2️⃣ Generate multiple UUIDs

import { uuidv4 } from "core-uuid";

  const uuids = Array.from({ length: 5 }, () => uuidv4());
  console.log("5 UUIDs:", uuids);
;

3️⃣ Advanced: Secure Random Bytes

import { getSecureRandomBytes, UUID_BYTES, TOKEN_BYTES } from "core-uuid";


  // Default 16 bytes (same as UUID size)
  const uuidBytes = getSecureRandomBytes();
  console.log("Secure 16 bytes (Uint8Array):", uuidBytes);

  // 32-byte random token
  const tokenBytes = getSecureRandomBytes(TOKEN_BYTES);
  const tokenHex = Array.from(tokenBytes)
    .map(b => b.toString(16).padStart(2, "0"))
    .join("");
  console.log("Secure 32-byte token (hex):", tokenHex);

Output example:

Secure 16 bytes (Uint8Array): Uint8Array(16) [23, 156, 87, ...]
Secure 32-byte token (hex): c1f5e9a0dce43f2a9b4e7f1a8d12e3c4b5a6d7e8f9a0b1c2d3e4f5a6b7c8d9e0

---

API

uuidv4(): string

• Returns a UUID v4 string.
• Synchronous and RFC 4122 compliant.

getSecureRandomBytes(length?: number): Uint8Array

• Returns a cryptographically secure Uint8Array of specified length.

• Default: 16 bytes.

• Can be used for:

  • UUIDs
  • Tokens
  • Salts
  • Nonces
  • Any random data you need

Optional constants:

UUID_BYTES = 16
TOKEN_BYTES = 32

---

Folder Structure

core-uuid/
├── src/
│   ├── random/
│   │   └── secure-random.ts
│   ├── uuid/
│   │   ├── v4.ts
│   │   └── index.ts
│   └── index.ts
├── test/
│   ├── uuid.v4.test.ts
│   └── random.test.ts
├── dist/
├── tsconfig.json
├── package.json
├── README.md
└── LICENSE

---

Testing

Uses Vitest for unit testing.

npm install --save-dev vitest @types/node
npm run test

• Validates UUID format
• Checks uniqueness across multiple generations
• Tests getSecureRandomBytes() for length and randomness

---

Philosophy

core-uuid is built around a clear set of principles:

• Lightweight: minimal footprint, no external dependencies
• Secure: cryptographically strong random number generation
• Reliable: RFC 4122 v4 compliant, predictable formatting
• Future-proof: modular design allows adding v1, v5, etc., easily

---

Contributing

Contributions, issues, and feature requests are welcome! Feel free to submit a PR or open an issue.

---

License

MIT