UUID Parser for Typescript

Introduction

This TypeScript library will take any RFC 4122 UUID, and parse it into a stream of bytes.

The library also offers a Uuid type, and a useful validation function.

• Introduction
• Quick Start
• V1 API
  • Uuid()
  • Uuid Automatic String Conversion
  • isUuidData()
  • mustBeUuidData()
  • uuidFromBytes()
  • uuidToBytes()
  • uuidFromFormatted()
  • uuidFromUnformatted()
• NPM Scripts
  • npm run clean
  • npm run build
  • npm run test
  • npm run cover

Quick Start

# run this from your Terminal
npm install @ganbarodigital/ts-lib-uuid-parser

// add this import to your Typescript code
import { Uuid } from "@ganbarodigital/ts-lib-uuid-parser/lib/v1"

VS Code users: once you've added a single import anywhere in your project, you'll then be able to auto-import anything else that this library exports.

V1 API

Uuid()

import { Branded } from "@ganbarodigital/ts-lib-value-objects/lib/v2";

/**
 * A type-safe representation of a UUID / GUID
 */
export type Uuid = Branded<string, "uuid">;

Uuid is a branded type. It represents a validated RFC 4122 UUID.

For example:

import { uuidFromFormatted } from "@ganbarodigital/ts-lib-uuid-parser/lib/v1";

// creates a new Uuid
const myUuid = uuidFromFormatted("9c47cb7c-9793-4944-9189-61a938d0e9bd");

Uuid Automatic String Conversion

At runtime, Uuid is just a string. You can use it anywhere you'd normally use a string.

import { Uuid } from "@ganbarodigital/ts-lib-uuid-parser/lib/v1";

// creates a new Uuid
const myUuid = uuidFromFormatted("9c47cb7c-9793-4944-9189-61a938d0e9bd");

// outputs the string "9c47cb7c-9793-4944-9189-61a938d0e9bd"
console.log(myUuid);

isUuidData()

function isUuidData(input: string): boolean

isUuidData() is a data guard. It returns true if the input string contains a well-formatted UUID.

For example:

import { isUuidData } from "@ganbarodigital/ts-lib-uuid-parser/lib/v1";

if (!isUuidData("12345-67890")) {
    throw new Error("invalid UUID");
}

mustBeUuidData()

import { OnError } from "@ganbarodigital/ts-lib-error-reporting/lib/v1";

export function mustBeUuidData(input: string, onError?: OnError): void

mustBeUuidData() is a data guarantee. It throws an InvalidUuidError if the input isn't an acceptable UUID.

uuidFromBytes()

import { OnError } from "@ganbarodigital/ts-lib-error-reporting/lib/v1";

export function uuidFromBytes(input: Buffer, onError?: OnError): Uuid

uuidFromBytes() is a data transform. It builds a human-readable UUID from a Buffer, reading from offset 0. It returns the resulting Uuid value.

If the resulting string isn't a valid UUID, the onError handler is called.

uuidToBytes()

export function uuidToBytes(uuid: Uuid, target?: Buffer): Buffer

uuidToBytes() is a data transform. It converts a human-readable UUID into bytes, and writes those bytes into the target Buffer, starting at offset 0.

If you do not provide a target Buffer to write to, uuidToBytes() will allocate one for you.

The return value is the Buffer that has been written to.

uuidFromFormatted()

import { OnError } from "@ganbarodigital/ts-lib-error-reporting/lib/v1";

/**
 * this is our main factory for building Uuids
 */
export function uuidFromFormatted(input: string, onError?: OnError): Uuid;

uuidFromFormatted() is a smart constructor. It validates that input contains a well-formed UUID, and returns a Uuid type.

If the input validation fails, uuidFromFormatted() calls the onError handler. The onError handler must throw an Error of some kind.

uuidFromUnformatted()

import { OnError } from "@ganbarodigital/ts-lib-error-reporting/lib/v1";

/**
 * converts an array of bytes into a type-safe UUID
 */
export function uuidFromUnformatted(input: string, onError?: OnError): Uuid;

uuidFromUnformatted() is a data transform. It converts the contents of input into a well-formatted UUID, and then calls uuidFromFormatted().

NPM Scripts

npm run clean

Use npm run clean to delete all of the compiled code.

npm run build

Use npm run build to compile the Typescript into plain Javascript. The compiled code is placed into the lib/ folder.

npm run build does not compile the unit test code.

npm run test

Use npm run test to compile and run the unit tests. The compiled code is placed into the lib/ folder.

npm run cover

Use npm run cover to compile the unit tests, run them, and see code coverage metrics.

Metrics are written to the terminal, and are also published as HTML into the coverage/ folder.