A well-implemented UUID TypeScript class, with all the necessary features and extensibility.
Basic usage | Installation | Advanced usage | API | Table of contents
- 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
Parsing an existent UUID as string:
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); // [Binary]Generating a new UUID:
const uuid = new Uuid();
uuid.toString(); // '01932c0a-235b-7da6-8153-aee356735b58'Parsing an UUID from a Node.js Buffer:
const uuid = new Uuid(buffer);
uuid.toString(); // '01932c0b-e834-7b5a-9bae-2964245fc0b6'See also utility functions:
Uuid.bufferToUuidHex(buffer: Buffer): stringUuid.uuidBufferFromHex(uuidHexString: string): BufferUuid.isUuidHexString(uuid: string | Buffer): booleanUuid.isUuidBase64String(uuid: string | Buffer): Buffer | nullUuid.fromHex(hexString: string): UuidUuid.fromBase64(base64String: string): UuidUuid.fromBuffer(buffer: Buffer): Uuid
See more usage topics in usage section.
$ npm install --save @uuid-ts/uuidSee other options
$ yarn add @uuid-ts/uuidhttps://unpkg.com/:@uuid-ts/uuid
<script src="https://unpkg.com/:@uuid-ts/uuid" />
This means you:
- May use the module with
import,requireordefine - Should use polyfills or transpilation if you want to support older environments
You can create a new UUID using the Uuid constructor without arguments:
import { Uuid } from '@uuid-ts/uuid';
const uuid = new Uuid();
uuid.toString(); // '01932c0a-235b-7da6-8153-aee356735b58'You can parse an UUID from formatted UUID hex strings (with or without dashes) or from base64 strings:
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'You can parse an UUID from a Node.js buffer:
import { Uuid } from '@uuid-ts/uuid';
const uuidFromBuffer = new Uuid(buffer);
uuidFromBuffer.toString(); // '01932c0b-e834-7b5a-9bae-2964245fc0b6'After parsing or generating an UUID, you can convert it to different formats:
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:
import { Uuid } from '@uuid-ts/uuid';
class Binary {
constructor(buffer: Buffer) {
this.buffer = buffer;
}
}
const uuid = new Uuid();
uuid.toInstance<Binary>(Binary); // [Binary]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:
import { Uuid } from '@uuid-ts/uuid';
Uuid.isUuidHexString('01932c07-209c-7401-9658-4e7a759e7bf7'); // true
Uuid.isUuidBase64String('AZMsByCcdAGWWAAATnp1ng'); // trueIf 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:
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'The Uuid class also provides utility functions to convert UUIDs to hex strings and to convert hex strings to buffers:
import { Uuid } from '@uuid-ts/uuid';
const buffer = Uuid.uuidBufferFromHex('01932c0b-e834-7b5a-9bae-2964245fc0b6');
Uuid.bufferToUuidHex(buffer); // '01932c0b-e834-7b5a-9bae-2964245fc0b6'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.
If you need help or have a problem with this project and you not found you problem in FAQ above, start an issue.
We will not provide a SLA to your issue, so, don't expect it to be answered in a short time.
[under construction] See jsdoc in the source code for more information.
@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.
Help us spreading the word or consider making a donation.
Add your company name to the Who is using secion
Make a pull request or start an issue to add your company's name.
We follow Contributor Covenant Code of Conduct. If you want to contribute to this project, you must accept and follow it.
This project adheres to Semantic Versioning 2.0.0.
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
Licensed under the MIT License.