PID

This module generates IDs with the same level of uniqueness as UUIDs (version 4 of RFC4122), but shorter, and, by default, without hyphens. This makes them a better fit for URL parameters and other places where IDs will be visible or public to the end-user, hence public ID or PID.

Here's an example of the difference between a PID and a UUID:

'2uiLXlsQx4BWVAVtqN1QDj' // PID
'e7a717df-3b31-46f6-bd56-cba1d6c5febf' // UUID

Installation

npm i @yesiree/pid

Usage

NodeJS

const { simplePid } = require('@yesiree/pid')

const pid = simplePid()

console.log(pid) // Outputs something like `dxu50ozbj4obelaop470y791v`

API

createPid([uuid | config]) => string

Creates a PID. Optionally, you can pass in a UUID and a base. If no UUID is provide, one will be generated. If no base is provided, base 64 is used. Passing in the same UUID and using the same base will always produce the same PID. This function is the most flexible way to generate a PID. However, for most use-cases, the simplePid() method described below is recommended.

Parameters

| Name | Type | Required | Description | | --- | --- | --- | --- | | uuid | string | No | A UUID, such as the ones generated by this package. | | config | object | No | A PidConfig object |

Returns

A PID as a string.

simplePid() => string

This function returns a PID using base 36 (0-9a-z). All PIDs generated with this method will be exactly 25 characters in length and all alpha characters will be lower case. This is the recommend way to generate PIDs, as it is less likely to cause issues in case-insensitive environments, where the combination of upper and lower case letters in a PID might cause issues.

Returns

A PID as a string.

compactPid() => string

This function returns a PID using base 64 (0-9a-zA-Z-_). All PIDs generated with this method will be exactly 22 characters in length. This method is NOT recommend for case-insensitive environments as the capitalization of alpha characters matters.

Returns

A PID as a string.

create, simple, compact

These method names are aliases retained for backwards compatibility. They correspond to the methods described above. They have been deprecated in favor of their more explicitly named equivalents, which are better suited for tree-shaking-compatible imports.

PidConfig

The following describes the properties of a PidConfig object:

| Property | Type | Required | Description | | --- | --- | --- | --- | | uuid | string | No | A RFC4122 version 4 compliant UUID string. If one is not provide, it will be generated using this package. | | base | number | No | The base to convert the UUID string to. The default is 64. Any base between 2 and 64 is valid. See below for details about the base alphabets. |

Base Alphabet

The alphabet used to generate all PIDs is:

0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ-_

The base chosen when creating a PID determines the subset of this alphabet used to generate that PID. For example, base 2 uses 0 and 1 as the alphabet; base 10 uses the digits 0 through 9; base 32 uses 0 through 9 and a through z. The maximum base (base 64) uses 0 through 9, a through z (lower case letters), A through Z (upper case letters) as well as - and _.

A longer explanation of purpose

When multiple systems exchange data (such as a public API), it's often necessary to have unique IDs with which to identify that data. Sharing IDs generated in and used internally by a database is usually a bad idea. If the storage mechanism needs to change, the IDs may neeed to change as well. This would require that any system consuming that data would also have to update all references to those IDs. If these systems exist within different organizations, this may not be feasible. Even if the systems exist within the same organization, the effort required to make these changes could be enormous.

Even if it is not anticipated that the storage mechanism will change, sometimes the most optimal ID format for the storage mechanism will not provide enough uniqueness to prevent collisions in the systems consuming data. For example, assume that you are building a system that pulls data from multiple APIs. You use the IDs given by those APIs to identify the data. Now assume that those APIs all use an auto-incrementing integer ID. It's inevitable that IDs from one of those APIs will collide with IDs from another. If the APIs used auto-incrementing integer IDs internally, but used universally unique IDs externally, there would be no concern for collision.

For these reasons and others, it's often best to have two IDs for each piece of data: one used internally by the storage mechanism that can change as needed and one exposed externally to other systems consuming the data. The external ID should be globally unique (to all systems). UUIDs or GUIDs are often used for this purpose, but they tend to be long and ugly. When used in web applications, for example, they tend to fill up the address bar and make it less human-readable.

This library guarantees the same level of uniqueness, but in a more compact form. This is accomplished by generating UUIDs and then converting them to a different base that can be representated in fewer characters.