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.

$3

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

$3

- 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

Author

Developed by Aldoivan.

---

Keywords

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