# LiteRT/UUID

[![Strict TypeScript Checked](https://badgen.net/badge/TS/Strict "Strict TypeScript Checked")](https://www.typescriptlang.org)
[![npm version](https://img.shields.io/npm/v/@litert/uuid.svg?colorB=brightgreen)](https://www.npmjs.com/package/@litert/uuid "Stable Version")
[![License](https://img.shields.io/npm/l/@litert/uuid.svg?maxAge=2592000?style=plastic)](https://github.com/litert/uuid/blob/master/LICENSE)
[![node](https://img.shields.io/node/v/@litert/uuid.svg?colorB=brightgreen)](https://nodejs.org/dist/latest-v8.x/)
[![GitHub issues](https://img.shields.io/github/issues/litert/uuid.js.svg)](https://github.com/litert/uuid.js/issues)
[![GitHub Releases](https://img.shields.io/github/release/litert/uuid.js.svg)](https://github.com/litert/uuid.js/releases "Stable Release")

A uuid generator library for NodeJS.

## Requirement

- TypeScript v5.0.0 (or newer)
- Node.js v20.0.0 (or newer)

## Installation

Install by NPM:

```sh
npm i @litert/uuid --save
```

## Exports

This package provides the main entry point and several subpath imports:

| Import Path | Description |
| --- | --- |
| `@litert/uuid` | Main entry — namespace re-exports of all modules |
| `@litert/uuid/snowflake` | Snowflake generator (64-bit bigint IDs) |
| `@litert/uuid/snowflake-si` | Snowflake-SI generator (safe-integer number IDs) |
| `@litert/uuid/uuid4` | UUIDv4 generator (random UUIDs) |
| `@litert/uuid/uuid5` | UUIDv5 generator (namespace + name derived UUIDs) |
| `@litert/uuid/uuid7` | UUIDv7 generator (time-ordered UUIDs) |
| `@litert/uuid/errors` | Error classes (`UuidError`, `E_TIME_REVERSED`, etc.) |
| `@litert/uuid/constants` | Shared enums (`ETimeReversedStrategy`, `ESequenceStrategy`) |
| `@litert/uuid/utils` | Utility functions |

```ts
// Namespace import (main entry)
import { Snowflake, UUIDv7 } from '@litert/uuid';
const gen = new Snowflake.SnowflakeGenerator({ machineId: 7 });

// Direct subpath import
import { SnowflakeGenerator } from '@litert/uuid/snowflake';
const gen = new SnowflakeGenerator({ machineId: 7 });
```

## Documents

- [English Website](https://litert.org/projects/uuid.js)
- [English Markdown Source](./docs/en/README.md)

## Algorithms

- [Snowflake](https://blog.twitter.com/engineering/en_us/a/2010/announcing-snowflake.html)

    A 64-bit integer UUID algorithm provided by X (Twitter).

- [Snowflake-SI](./docs/en/api/Snowflake-SI.md)

    A safe-integer Snowflake variant for JavaScript applications.

- [UUIDv4](./docs/en/api/UUIDv4.md)

    A random UUID generator.

- [UUIDv5](./docs/en/api/UUIDv5.md)

    A deterministic UUID generator based on namespace and name.

- [UUIDv7](./docs/en/api/UUIDv7.md)

    A time-ordered UUID generator.

## Examples

- [Snowflake](./src/examples/Snowflake.ts)
- [Snowflake-SI](./src/examples/SnowflakeSI.ts)
- [UUIDv4](./src/examples/UUIDv4.ts)
- [UUIDv5](./src/examples/UUIDv5.ts)
- [UUIDv7](./src/examples/UUIDv7.ts)

## License

This library is published under [Apache-2.0](./LICENSE) license.

## AI Disclaimer

This project may use AI tools to assist in documentation writing and inspiration for unit test cases, but all code is written and reviewed by human developers.