Class default

API Reference

Generate random or sequential UUID of any length.

Use as module

 
// Deno (web module) Import
import ShortUniqueId from 'https://cdn.jsdelivr.net/npm/short-unique-id@latest/src/index.ts';

// ES6 / TypeScript Import
import ShortUniqueId from 'short-unique-id';

//or Node.js require
const ShortUniqueId = require('short-unique-id');

//Instantiate
const uid = new ShortUniqueId();

// Random UUID
console.log(uid());

// Sequential UUID
console.log(uid.seq());

Use in browser

 
<!-- Import -->
<script src="https://cdn.jsdelivr.net/npm/short-unique-id@latest/dist/short-unique-id.min.js"></script>

<!-- Usage -->
<script>
  // Instantiate
  var uid = new ShortUniqueId();

  // Random UUID
  document.write(uid());

  // Sequential UUID
  document.write(uid.seq());
</script>

Options

Options can be passed when instantiating uid:

const options = { ... };

const uid = new ShortUniqueId(options);

For more information take a look at the ShortUniqueIdOptions type definition.

Hierarchy

  • Function
    • default

Index

Constructors

Properties

Methods

Constructors

constructor

Properties

counter

counter: number

debug

debug: boolean

dict

dict: string[]

dictIndex

dictIndex: number = 0

dictLength

dictLength: number = 0

dictRange

dictRange: number[] = []

lowerBound

lowerBound: number = 0

upperBound

upperBound: number = 0

uuidLength

uuidLength: number

version

version: string

Static default

default: typeof default = ...

Methods

approxMaxBeforeCollision

  • approxMaxBeforeCollision(rounds?: number): number

  • Calculates approximate number of hashes before first collision.

    Given that:

    • H is the total number of possible UUIDs, or in terms of this library, the result of running availableUUIDs()
    • the expected number of values we have to choose before finding the first collision can be expressed as the quantity Q(H)

    Then Q(H) can be approximated as the square root of the product of half of pi times H:

    This function returns Q(H).

    (see Poisson distribution)

    Parameters

    • rounds: number = ...

    Returns number

availableUUIDs

  • availableUUIDs(uuidLength?: number): number

  • Calculates total number of possible UUIDs.

    Given that:

    • H is the total number of possible UUIDs
    • n is the number of unique characters in the dictionary
    • l is the UUID length

    Then H is defined as n to the power of l:

    This function returns H.

    Parameters

    • uuidLength: number = ...

    Returns number

collisionProbability

  • collisionProbability(rounds?: number, uuidLength?: number): number

  • Calculates probability of generating duplicate UUIDs (a collision) in a given number of UUID generation rounds.

    Given that:

    • r is the maximum number of times that randomUUID() will be called, or better said the number of rounds
    • H is the total number of possible UUIDs, or in terms of this library, the result of running availableUUIDs()

    Then the probability of collision p(r; H) can be approximated as the result of dividing the square root of the product of half of pi times r by H:

    This function returns p(r; H).

    (see Poisson distribution)

    (Useful if you are wondering "If I use this lib and expect to perform at most r rounds of UUID generations, what is the probability that I will hit a duplicate UUID?".)

    Parameters

    • rounds: number = ...
    • uuidLength: number = ...

    Returns number

getVersion

  • getVersion(): string

  • Return the version of this module.

    Returns string

parseStamp

  • parseStamp(stamp: string): Date

  • Extracts the date embeded in a UUID generated using the uid.stamp(finalLength); method.

     const uidWithTimestamp = uid.stamp(32);
 console.log(uidWithTimestamp);
 // GDa608f973aRCHLXQYPTbKDbjDeVsSb3

 console.log(uid.parseStamp(uidWithTimestamp));
 // 2021-05-03T06:24:58.000Z

    Parameters

    • stamp: string

    Returns Date

randomUUID

  • randomUUID(uuidLength?: number): string

  • Generates UUID by creating each part randomly.

    alias

    const uid = new ShortUniqueId(); uid(uuidLength: number);

    Parameters

    • uuidLength: number = ...

    Returns string

seq

  • seq(): string

sequentialUUID

  • sequentialUUID(): string

  • Generates UUID based on internal counter that's incremented after each ID generation.

    alias

    const uid = new ShortUniqueId(); uid.seq();

    Returns string

setDictionary

  • setDictionary(dictionary: string[] | defaultDictionaries, shuffle?: boolean): void

  • Change the dictionary after initialization.

    Parameters

    • dictionary: string[] | defaultDictionaries
    • Optional shuffle: boolean

    Returns void

stamp

  • stamp(finalLength: number): string

  • Generates a UUID with a timestamp that can be extracted using uid.parseStamp(stampString);.

     const uidWithTimestamp = uid.stamp(32);
 console.log(uidWithTimestamp);
 // GDa608f973aRCHLXQYPTbKDbjDeVsSb3

 console.log(uid.parseStamp(uidWithTimestamp));
 // 2021-05-03T06:24:58.000Z

    Parameters

    • finalLength: number

    Returns string

uniqueness

  • uniqueness(rounds?: number): number

  • Calculate a "uniqueness" score (from 0 to 1) of UUIDs based on size of dictionary and chosen UUID length.

    Given that:

    • H is the total number of possible UUIDs, or in terms of this library, the result of running availableUUIDs()
    • Q(H) is the approximate number of hashes before first collision, or in terms of this library, the result of running approxMaxBeforeCollision()

    Then uniqueness can be expressed as the additive inverse of the probability of generating a "word" I had previously generated (a duplicate) at any given iteration up to the the total number of possible UUIDs expressed as the quotiend of Q(H) and H:

    (Useful if you need a value to rate the "quality" of the combination of given dictionary and UUID length. The closer to 1, higher the uniqueness and thus better the quality.)

    Parameters

    • rounds: number = ...

    Returns number