@uuid-ts/uuid
Short description of project.
Basic usage | Installation | Advanced usage | API | Table of contents
## Features
- Automatic parsing 🔮
- Automatically identifies UUID from hex, base64 or buffer
- Automatic generation 🪄
- Generates UUID (defaults to v7)
- Easy conversion ✌️
- Converts UUID to hex, base64 or buffer
- Validation ✅
- Utility methods to validate existing strings or buffers
## TL;DR: basic usage
[](https://npm.runkit.com/@uuid-ts/uuid)
Parsing an existent UUID as string:
```typescript
const uuidString = '01932c07-209c-7401-9658-4e7a759e7bf7';
const uuid = new Uuid(uuidString);
// methods
uuid.toHex(); // '01932c07-209c-7401-9658-4e7a759e7bf7'
uuid.toBase64(); // 'AZMsByCcdAGWWAAATnp1ng'
uuid.toBuffer(); // [Buffer]
uuid.toInstance(Binary); // [Binary]
```
Generating a new UUID:
```typescript
const uuid = new Uuid();
uuid.toString(); // '01932c0a-235b-7da6-8153-aee356735b58'
```
Parsing an UUID from a Node.js Buffer:
```typescript
const uuid = new Uuid(buffer);
uuid.toString(); // '01932c0b-e834-7b5a-9bae-2964245fc0b6'
```
See also utility functions:
- `Uuid.bufferToUuidHex(buffer: Buffer): string`
- `Uuid.uuidBufferFromHex(uuidHexString: string): Buffer`
- `Uuid.isUuidHexString(uuid: string | Buffer): boolean`
- `Uuid.isUuidBase64String(uuid: string | Buffer): Buffer | null`
- `Uuid.fromHex(hexString: string): Uuid`
- `Uuid.fromBase64(base64String: string): Uuid`
- `Uuid.fromBuffer(buffer: Buffer): Uuid`
See more usage topics in [usage](#usage) section.
## Table of contents
---
## Installation
### Requirements
    
### Installing
#### Via package manager
```shell
$ npm install --save @uuid-ts/uuid
```
See other options
#### Yarn
```shell
$ yarn add @uuid-ts/uuid
```
#### Unpkg
[https://unpkg.com/:@uuid-ts/uuid](https://unpkg.com/:@uuid-ts/uuid)
```javascript
```
### Module/language support
This means you:
* **May** use the module with `import`, `require` or `define`
* **Should** use polyfills or transpilation if you want to support older environments
↟ Back to top
---
## Usage
### Creating new UUIDs using `Uuid` class
You can create a new UUID using the `Uuid` constructor without arguments:
```typescript
import { Uuid } from '@uuid-ts/uuid';
const uuid = new Uuid();
uuid.toString(); // '01932c0a-235b-7da6-8153-aee356735b58'
```
### Parsing UUIDs from strings
You can parse an UUID from formatted UUID hex strings (with or without dashes) or from base64 strings:
```typescript
import { Uuid } from '@uuid-ts/uuid';
const uuidHex = '01932c07-209c-7401-9658-4e7a759e7bf7';
const uuidFromHex = new Uuid(uuidString);
uuidFromHex.toString(); // '01932c07-209c-7401-9658-4e7a759e7bf7'
const uuidBase64 = 'AZMsByCcdAGWWAAATnp1ng';
const uuidFromBase64 = new Uuid(uuidBase64);
uuidFromBase64.toString(); // '01932c07-209c-7401-9658-4e7a759e7bf7'
```
### Parsing UUIDs from buffers
You can parse an UUID from a Node.js buffer:
```typescript
import { Uuid } from '@uuid-ts/uuid';
const uuidFromBuffer = new Uuid(buffer);
uuidFromBuffer.toString(); // '01932c0b-e834-7b5a-9bae-2964245fc0b6'
```
### Converting UUIDs to different formats
After parsing or generating an UUID, you can convert it to different formats:
```typescript
import { Uuid } from '@uuid-ts/uuid';
const uuid = new Uuid();
uuid.toHex(); // '01932c0a-235b-7da6-8153-aee356735b58'
uuid.toBase64(); // 'AZMsCgI1tqYBSO7jZnN1tY'
uuid.toBuffer(); // [Buffer]
```
The `toInstance` method allows you to convert the UUID to a custom class that accepts a buffer as argument:
```typescript
import { Uuid } from '@uuid-ts/uuid';
class Binary {
constructor(buffer: Buffer) {
this.buffer = buffer;
}
}
const uuid = new Uuid();
uuid.toInstance(Binary); // [Binary]
```
### Validation functions
The easiest way to validate an UUID in any format is to use the Uuid constructor itself. If the argument is a valid UUID, it will be parsed correctly. Otherwise, an error will be thrown.
You can also use the static methods `Uuid.isUuidHexString` and `Uuid.isUuidBase64String` to validate UUIDs in hex or base64 format:
```typescript
import { Uuid } from '@uuid-ts/uuid';
Uuid.isUuidHexString('01932c07-209c-7401-9658-4e7a759e7bf7'); // true
Uuid.isUuidBase64String('AZMsByCcdAGWWAAATnp1ng'); // true
```
### Constructing UUIDs from different formats
If you want to avoid the automatic parsing of the Uuid constructor or if you need explicit argument types, you can use the static methods `Uuid.fromHex`, `Uuid.fromBase64` and `Uuid.fromBuffer`:
```typescript
import { Uuid } from '@uuid-ts/uuid';
const uuidFromHex = Uuid.fromHex('01932c07-209c-7401-9658-4e7a759e7bf7');
uuidFromHex.toString(); // '01932c07-209c-7401-9658-4e7a759e7bf7'
const uuidFromBase64 = Uuid.fromBase64('AZMsByCcdAGWWAAATnp1ng');
uuidFromBase64.toString(); // '01932c07-209c-7401-9658-4e7a759e7bf7'
const uuidFromBuffer = Uuid.fromBuffer(buffer);
uuidFromBuffer.toString(); // '01932c0b-e834-7b5a-9bae-2964245fc0b6'
```
### Utility functions
The `Uuid` class also provides utility functions to convert UUIDs to hex strings and to convert hex strings to buffers:
```typescript
import { Uuid } from '@uuid-ts/uuid';
const buffer = Uuid.uuidBufferFromHex('01932c0b-e834-7b5a-9bae-2964245fc0b6');
Uuid.bufferToUuidHex(buffer); // '01932c0b-e834-7b5a-9bae-2964245fc0b6'
```
↟ Back to top
---
## Help
### FAQ
1. Do I need to install any dependencies?
This package depends directly to the main `uuid` package and also to `uuidv7` package. You don't need to install them manually, they are already included in the package.
2. Can I use this package in the browser?
Yes, if you are using polyfills to support the `Buffer` class in the browser. This package is isomorphic and can be used in both Node.js and browser environments.
3. What is the difference between this package and the main `uuid` package?
This package is a wrapper around the main `uuid` package that provides a more user-friendly API and automatic parsing of UUIDs from different formats. It also includes utility functions to convert UUIDs to different formats and to validate UUIDs.
4. What about the other UUID versions?
This package currently supports only UUID version 7. We may add support for other versions in a near future.
You can also contribute to this project by adding support for other versions.
5. Can I use this package with TypeScript?
Yes, this package is written in TypeScript and includes type definitions. You can use it with TypeScript without any additional configuration.
6. Can I use this package with JavaScript?
Yes, this package is written in TypeScript but it is compiled to JavaScript and includes type definitions. You can use it with JavaScript without any additional configuration.
Just make sure to use a modern version of Node.js or a browser that supports the latest ECMAScript features, or use a transpiler like Babel to support older environments.
### Support
If you need help or have a problem with this project and you not found you problem in FAQ above, [start an issue](https://github.com/ggondim/uuid/issues).
> We will not provide a SLA to your issue, so, don't expect it to be answered in a short time.
↟ Back to top
---
## API
[under construction] See jsdoc in the source code for more information.
↟ Back to top
---
## Tecnhical concepts
### Motivation and design
@uuid-ts/uuid was inspired from the main `uuid` package, but with a more user-friendly API and automatic parsing of UUIDs from different formats. It also includes utility functions to convert UUIDs to different formats and to validate UUIDs.
The main goal of this package is to provide a simple and easy-to-use API to work with UUIDs in different formats and to provide a more user-friendly interface to the main `uuid` package.
It also has support for UUID version 7, which is the latest version of UUIDs and is recommended for most use cases.
### Related projects
* [uuid](https://www.npmjs.com/package/uuid)
* [uuid](https://www.npmjs.com/package/uuidv7)
↟ Back to top
---
## Contributing
### If you don't want to code
Help us spreading the word or consider making a donation.
#### Star the project
#### Tweet it
#### Add your company name to the [Who is using](#Who-is-using) secion
Make a pull request or start an issue to add your company's name.
### If you want to code
#### Code of conduct
We follow [Contributor Covenant Code of Conduct](https://www.contributor-covenant.org/version/2/0/code_of_conduct/code_of_conduct.md). If you want to contribute to this project, you must accept and follow it.
#### SemVer
This project adheres to [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html).
#### Roadmap
If you are not solving an issue or fixing a bug, you can help developing the roadmap below.
See the roadmap
* [ ] Develop tests
* [ ] Improve documentation
* [ ] Add support for other UUID versions
↟ Back to top
---
## Hall of fame
### Who is using
* [Your company here]()
### Contributors
[](https://sourcerer.io/fame/ggondim/${OWNER}/uuid/links/0)
↟ Back to top
---
## License
Licensed under the [MIT License](LICENSE.md).
↟ Back to top