uuid-v4-validator

Generate, manage and validate easily Universally Unique Identifiers v4

Description

This package provides a all-in-one class to generate and validate Universally Unique Identifiers v4, useful for naming or identify elements in a list, documents in a database, variables etc.

Is a collision between 2 randomly generated UUIDs possible? According to the Birthday Paradox, the probability of finding a collision between 2 UUID within 103 trillion UUIDs is one in a billion. The number of random UUIDs which need to be generated in order to have a 50% probability of at least one collision is 2.71 quintillion.

Installation

npm i uuid-v4-validator

Compatibility

Compatible with Node >=6.2.0

Features

• Collision test passed on 1 million instances
• You can manage UUIDs as objects and not as strings
• Supports static generation and validation of UUID v4
• It's developed in order to support inheritance
• Extremely small: it will occupying less than 2kb in your final bundle

Other features

• Runtime type checking and static with typescript declaration files
• Exhaustive doc comments
• Tree shakable: exported with ESM modules
• Tested with available coverage report

API

Index

UUIDv4
UUIDv4.id
UUIDv4.blockingError
UUIDv4.generate
UUIDv4.validate
UUIDv4.refreshId

UUIDv4

import { UUIDv4 } from 'uuid-v4-validator'

• Class
• Constructor: ( id?: string )

Create a UUIDv4 instance with an own generated random uuid. You can pass a custom uuid that will be validate.
⚠ It could generate an error if the provided uuid doesn't pass the validation. For avoid error throwing set UUIDv4.blockingError as false.

UUIDv4.id

• string

get: The current id. It's always valid
set: Set a new custom id. ⚠ Generate an error if the provided id doesn't pass the validation.

UUIDv4.blockingError

• boolean

Generate a warn instead of stopping execution at runtime. If you provide an invalid uuid to the constructor, it will generates a new valid one

UUIDv4.generate

• Function (): string
• Return: A valid UUID v4 string

Generate a new UUID v4 string.

UUIDv4.validate

• Function ( arg: string | Object | UUIDv4 ): boolean

Returns true if the provided UUID v4 string passes the validation or the provided object or UUIDv4 instance has a valid UUID and shape

UUIDv4.refreshId

• Function (): void

Generate a new id that will override the old one

Examples

• Create an UUIDv4 instance with a random generated UUID v4

import { UUIDv4 } from "uuid-v4-validator";

const userId = new UUIDv4();

console.log(userId);
// Returns a UUIDv4 instance
// Expected output: UUIDv4 { _id: "s4F68hFDf-d3R5-4Rt6-dRgi-dEji85feY51s" }

console.log(userId.id);
// Returns UUID as string
// Expected output: "s4F68hFDf-d3R5-4Rt6-dRgi-dEji85feY51s"

• Create a UUIDv4 instance with a custom string

import { UUIDv4 } from "uuid-v4-validator";

const userId1 = new UUIDv4("s4F68hFDf-d3R5-4Rt6-dRgi-dEji85feY51s");

console.log(userId);
// Returns a UUIDv4 instance
// Expected output: UUIDv4 { _id: "s4F68hFDf-d3R5-4Rt6-dRgi-dEji85feY51s" }

const userId2 = new UUIDv4("s4F68hF");
// Execution stops due to an error
// Expected output: The provided UUIDv4 "s4F68hF" string doesn't pass the validation. Use a valid UUIDv4 string or generate a new one

• Validate an UUIDv4 instance, an UUIDv4-like object or an UUID v4 string

import { UUIDv4 } from "uuid-v4-validator";

const importedId = "s4F68hFDf-d3R5-4Rt6-dRgi-dEji85feY51s";
console.log(UUIDv4.validate(importedId));
// Returns true if the provided ID passes the validation
// Expected output: true

const importedIdInstance = new UUIDv4();
console.log(UUIDv4.validate(importedIdInstance));
// Returns true if the provided object is a valid UUIDv4 instance and the ID passes the validation
// Expected output: true

const importedIdObject = {
  _id: "s4F68hFDf-d3R5-4Rt6-dRgi-dEji85feY51s"
};
console.log(UUIDv4.validate(importedIdObject));
// Returns true if the provided object can be casted into a valid UUIDv4 instance and the ID passes the validation
// Expected output: true

• Set a new custom id

import { UUIDv4 } from "uuid-v4-validator";

const uuidv4Instance = new UUIDv4();

const validId = "s4F68hFDf-d3R5-4Rt6-dRgi-dEji85feY51s";
const invalidId = "s4F68";

uuidv4Instance.id = validId;

console.log(uuidv4Instance.id);
// Return true if the provided ID passes the validation
// Expected output: true

uuidv4Instance.id = invalidId;
// Execution stops due to an error
// Expected output: The provided UUIDv4 "s4F68h" string doesn't pass the validation. Use a valid UUIDv4 string or generate a new one

Links

• RFC 4122
• DCE 1.1: Authentication and Security Services

License

MIT