ai-uuid-v7/README.md

Library to generate uuidv7 with javascript

# ai-uuid-v7

A lightweight library to generate and parse **UUID v7** in JavaScript/TypeScript.

UUID v7 is a new timestamp-based UUID format that provides better sorting and uniqueness guarantees for systems that require time-based identifiers.

## Features

-   Generate UUID v7 strings.
-   Extract the timestamp from a UUID v7 and convert it into a `Date` object.
-   Fully compatible with Node.js and modern JavaScript environments.

## Installation

You can install the library via npm or pnpm:

```apache
npm i ai-uuid-v7
```

Or with pnpm:

```apache
pnpm add ai-uuid-v7
```

# Usage

## Generate a UUID v7

```javascript
import { uuidv7 } from "ai-uuid-v7"

const uuid = uuidv7.generate()
console.log("Generated UUID v7:", uuid)
// Example output: "01890e42-c5d2-7f11-8000-8f30c5df7ffb"
```

## Extract the timestamp from a UUID v7

```javascript
import { uuidv7 } from "ai-uuid-v7"

const uuid = "01890e42-c5d2-7f11-8000-8f30c5df7ffb"
const date = uuidv7.getDate(uuid)
console.log("Timestamp from UUID:", date)
// Example output: Date object representing the timestamp.
```

## Error handling

The `getDate` function will throw an error if the UUID is not a valid v7 UUID:

```javascript
try {
    const date = getDate("invalid-uuid")
} catch (error) {
    console.error(error.message)
    // Output: "Invalid UUID, not v7"
}
```

## API

`uuidv7.generate(): string`

Generates a new UUID v7 string.

`uuidv7.getDate(uuid: string): Date`

Parses a UUID v7 string and returns the corresponding `Date` object.

### **Parameters:**

-   uuid (string): A valid UUID v7 string.

### **Returns:**

-   A Date object.
-   Throws: An error if the provided string is not a valid UUID v7.

## License

This project is licensed under the [ISC License](https://choosealicense.com/licenses/isc/)

## Author

Developed by **[Aldoivan.](https://github.com/Aldoivan10)**

---

## Keywords

`uuid`, `uuid-v7`, `javascript`, `typescript`, `timestamp`, `identifier`, `unique`