npm package: @se-oss/uuid
Description: A TypeScript library for generating and validating all modern UUID versions (1, 3, 4, 5, 6, and 7).
Author: Shahrad Elahi
Latest version: 1.0.0

# @se-oss/uuid

[![CI](https://github.com/shahradelahi/ts-uuid/actions/workflows/ci.yml/badge.svg?branch=main&event=push)](https://github.com/shahradelahi/ts-uuid/actions/workflows/ci.yml)
[![NPM Version](https://img.shields.io/npm/v/@se-oss/uuid.svg)](https://www.npmjs.com/package/@se-oss/uuid)
[![MIT License](https://img.shields.io/badge/License-MIT-blue.svg?style=flat)](/LICENSE)
![npm bundle size](https://img.shields.io/bundlephobia/minzip/@se-oss/uuid)
[![Install Size](https://packagephobia.com/badge?p=@se-oss/uuid)](https://packagephobia.com/result?p=@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](#-installation)
- [Usage](#-usage)
- [Documentation](#-documentation)
- [Contributing](#-contributing)
- [License](#license)

## 📦 Installation

```bash
pnpm install @se-oss/uuid
```

<details>
<summary>Install using your favorite package manager</summary>

**npm**

```bash
npm install @se-oss/uuid
```

**yarn**

```bash
yarn add @se-oss/uuid
```

</details>

## 📖 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).

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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](https://www.jsdocs.io/package/@se-oss/uuid).

## 🤝 Contributing

Want to contribute? Awesome! To show your support is to star the project, or to raise issues on [GitHub](https://github.com/shahradelahi/ts-uuid).

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

## License

[MIT](/LICENSE) © [Shahrad Elahi](https://github.com/shahradelahi) and [contributors](https://github.com/shahradelahi/ts-uuid/graphs/contributors).