ramsey-uuid

ramsey-uuid

A TypeScript library that provides a 'ramsey/uuid'-like interface for the uuid package.

ramsey-uuid is a TypeScript library for generating and working with universally unique identifiers (UUIDs). It provides a ramsey/uuid-like interface to the uuid package that

This project adheres to a code of conduct. By participating in this project and its community, you are expected to uphold this code.

Quickstart

1. Install

npm i --save ramsey-uuid

1. Generate a UUID (ES6 module syntax)

import { Uuid } from 'ramsey-uuid';
const uuid = Uuid.uuid4();

... or using CommonJS syntax:

const { Uuid } = require('ramsey-uuid');
const uuid = Uuid.uuid4();

API Summary

getUuid()

Returns the array of bytes of the UUID

returns	Uint8Array[16]
throws	TypeError if str is not a valid UUID

Example:

import { Uuid } from 'ramsey-uuid';

const uuid = Uuid.uuid4();
const byteArray = uuid.getUuid();

fromString(str)

Convert a UUID string to array of bytes

str	A valid UUID String
returns	Uint8Array[16]
throws	TypeError if str is not a valid UUID

Example:

import { Uuid } from 'ramsey-uuid';

const uuid = Uuid.fromString('6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b');

toString()

Convert array of bytes to UUID string

returns	String
throws	TypeError if a valid UUID string cannot be generated

Example:

import { Uuid } from 'ramsey-uuid';

const uuid = Uuid.uuid4();
uuid.toString(); // ⇨ '6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b'

toHex

Convert array of bytes to UUID hexadecimal string

returns	String
throws	TypeError if a valid UUID string cannot be generated

Example:

import { Uuid } from 'ramsey-uuid';

const uuid = Uuid.uuid4();
uuid.toHex(); // ⇨ '6EC0BD7F11C043DA975E2A8AD9EBAE0B'

fromBytes(str)

Convert a UUID byte string to array of bytes

str	A valid UUID byte string String
returns	Uint8Array[16]
throws	TypeError if str is not a valid UUID

Example:

import { Uuid } from 'ramsey-uuid';

const uuid = Uuid.fromString('acCäügF¥˜Üs܇?4');

getBytes()

Convert an array of bytes to a binary string representation of the UUID

returns	String
throws	TypeError if a valid UUID string cannot be generated

Example:

import { Uuid } from 'ramsey-uuid';

const uuid = Uuid.uuid4();
uuid.getBytes(); // ⇨ 'acCäügF¥˜Üs܇?4'

Use in Database - MySQL

The recommended use for saving UUID values in the database would be to create a BINARY(16) column in the database. When persisting the UUIDs you can UNHEX the hexadecimal representation of the UUID.

TypeORM

await this.model
.createQueryBuilder()
.insert()
.into(Table)
.values({
  uuid: () => `UNHEX('${Uuid.uuid4().toHex()}')`,
})
.execute();

MySQL

INSERT INTO `ActivityDefinition` (`uuid`)
VALUES('UNHEX("616343E4FC6746A598DC73C39C873F34")');

Contributing

Contributions are welcome! To contribute, please familiarize yourself with CONTRIBUTING.md.

Copyright and License

The ramsey-uuid library is copyright © Connor Smyth and licensed for use under the MIT License (MIT). Please see LICENSE for more information.