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:

npm i ai-uuid-v7

Or with pnpm:

pnpm add ai-uuid-v7

Usage

Generate a UUID v7

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

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:

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

Author

Developed by Aldoivan.

Keywords

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