Why I created a new UUID package for Node.js

I've been working with Node.js for a long time and I've always used the uuid package to generate UUIDs in my projects. It's a great package and it works well, but I always felt that it could be improved in some aspects.

Problems

Simple API

One of the things that always bothered me about the uuid package is that it is limited to a simple UUID generation in the default format. You have to know how to convert it to different formats, which can be a bit confusing for beginners.

Long UUID strings

Although the UUID string is a standard format, it is not very suitable for URLs or other contexts where you need a more compact representation, such as base64. This forces you to parse the UUID string and convert it to a different format, which can be a bit cumbersome.

Storage efficiency

Also, the string form of UUIDs is not very efficient in terms of storage space. It uses 36 characters to represent a 16-byte value, which is not very efficient for storage or transmission over the network neither for database storage.

Solution

To solve these problems, I decided to create a new package called @uuid-ts/uuid 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.

It is a simple TypeScript class with UUID version 7 support that can be used in both Node.js and browser environments. It is isomorphic and can be used with modern JavaScript and TypeScript without any additional configuration.

Features

• Automatic parsing of UUIDs from hex, base64 or buffer
• Automatic generation of UUIDs (defaults to v7)
• Easy conversion of UUIDs to hex, base64 or buffer
• Utility methods to validate existing strings or buffers

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'

It also comes with the following 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

Conclusion

I hope this package will be useful for you and that it will help you work with UUIDs in a more efficient and user-friendly way. If you have any feedback or suggestions, please let me know.

You can find the package on npm at https://www.npmjs.com/package/@uuid-ts/uuid.