@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

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'

Installation

Requirements

Installing

Via package manager

$ npm install --save @uuid-ts/uuid

See other options

Yarn

$ yarn add @uuid-ts/uuid

Unpkg

https://unpkg.com/:@uuid-ts/uuid

<script src="https://unpkg.com/:@uuid-ts/uuid" />

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:

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:

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:

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:

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]

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:

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:

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:

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.

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.