@se-oss/uuid

@se-oss/uuid is a TypeScript library for generating and working with all modern UUID versions (1, 3, 4, 5, 6, and 7). It is designed to be lightweight, fast, and tree-shakable, making it suitable for any project.

• Installation
• Usage
• Documentation
• Contributing
• License

📦 Installation

pnpm install @se-oss/uuid

npm

npm install @se-oss/uuid

yarn

yarn add @se-oss/uuid

📖 Usage

Quick Start: General-Purpose UUIDs (v4 & v7)

For most use cases, you'll want either a completely random UUID (v4) or a time-sortable one (v7).

import { v4, v7 } from '@se-oss/uuid';

// Generate a random v4 UUID
// Ideal for unique identifiers where order doesn't matter.
const randomId = v4();
console.log('v4:', randomId);
// -> e.g., '1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed'

// Generate a time-sortable v7 UUID
// Perfect for database keys that need to be roughly sequential.
const sortableId = v7();
console.log('v7:', sortableId);
// -> e.g., '018f9e2c-0a8c-7b2a-8b0f-9e8e2d2b1c6d'

Time-Based UUIDs (v1, v6, v7)

These UUIDs embed a timestamp, making them useful for tracking creation order.

import { getTimestamp, v1, v6, v7 } from '@se-oss/uuid';

// v1: Timestamp + MAC address (or random node)
const v1Id = v1();
console.log('v1 Timestamp:', getTimestamp(v1Id)); // -> Date object

// v6: Reordered timestamp for better database indexing
const v6Id = v6();
console.log('v6 Timestamp:', getTimestamp(v6Id)); // -> Date object

// v7: Unix Epoch timestamp (more modern and sortable)
const v7Id = v7();
console.log('v7 Timestamp:', getTimestamp(v7Id)); // -> Date object

Name-Based UUIDs (v3 & v5)

These generate a deterministic UUID based on a name and a namespace. The same inputs will always produce the same output.

import { NS, v3, v5 } from '@se-oss/uuid';

// Predefined namespaces are available for DNS, URL, etc.
const namespace = NS.DNS;
const name = 'hello.world';

// Generate a v3 (MD5) UUID
const v3Id = await v3(name, namespace);
console.log('v3:', v3Id);
// -> '9f3784ab-23b0-3373-b262-01b3d68a27d3'

// Generate a v5 (SHA-1) UUID
const v5Id = await v5(name, namespace);
console.log('v5:', v5Id);
// -> '016f2f48-6366-5527-a36c-217e573a0a52'

Validation and Utilities

The library includes helpers for working with UUIDs.

import { parse, stringify, validate, version } from '@se-oss/uuid';

const uuid = 'a9b6f8e4-7b3b-4c8f-8f8b-9e8e2d2b1c6d';

// Check if a string is a valid UUID
console.log('Is valid?', validate(uuid)); // -> true
console.log('Is valid?', validate('not-a-uuid')); // -> false

// Get the version of a UUID
console.log('Version:', version(uuid)); // -> 4

// Parse a UUID string into a byte array (Uint8Array)
const bytes = parse(uuid);
console.log('Bytes:', bytes);
// -> Uint8Array(16) [ 169, 182, 248, 228, ... ]

// Convert a byte array back to a string
const backToString = stringify(bytes);
console.log('Stringified:', backToString);
// -> 'a9b6f8e4-7b3b-4c8f-8f8b-9e8e2d2b1c6d'

console.log('Are they equal?', uuid === backToString); // -> true

Object-Oriented Usage with the UUID Class

For an object-oriented approach, you can use the UUID class.

import { UUID, v4, v7 } from '@se-oss/uuid';

// Create a UUID instance from a string
const uuidV4 = new UUID(v4());

// Get version and bytes
console.log('Version:', uuidV4.getVersion()); // -> 4
console.log('Bytes:', uuidV4.toBytes()); // -> Uint8Array(16)

// For time-based UUIDs, you can get the timestamp
const uuidV7 = new UUID(v7());
console.log('Timestamp:', uuidV7.getTimestamp()); // -> Date object

// Compare UUIDs for equality
const anotherUuid = new UUID(uuidV4.toString());
console.log('Are they equal?', uuidV4.equals(anotherUuid)); // -> true

📚 Documentation

For all configuration options, please see the API docs.

🤝 Contributing

Want to contribute? Awesome! To show your support is to star the project, or to raise issues on GitHub.

Thanks again for your support, it is much appreciated! 🙏

License

MIT © Shahrad Elahi and contributors.