README.md

Readable global identifiers

A package providing functions to generate and parse readable global identifiers.

Features:

• Identifiers have 128 bits of entropy, making them suitable as global identifiers.
• By default identifiers are random, but you can convert existing UUIDs.
• They are encoded into readable base 58 strings always of 22 characters in length.

Installation

Go installation

You can add it to your project using go get:

go get gitlab.com/tozd/identifier

It requires Go 1.23 or newer.

TypeScript/JavaScript installation

You can add it to your project using npm:

npm install --save @tozd/identifer

It requires node 20 or newer. It works in browsers, too.

Usage

Go usage

See full package documentation on pkg.go.dev.

TypeScript/JavaScript usage

import { Identifier } from "@tozd/identifier"

const id = Identifier.new() // A random identifier.
const s = id.toString()
console.log(s)
Identifier.valid(s) // True.
Identifier.fromString(s) // Is equal to id.
const u = Identifier.fromUUID("c97e2491-dd58-4a4e-b351-d786554e2ae6") // Is equal to Rt7JRSoDY1woPhLidZNvz1.
JSON.stringify({ id }) // Works, id is converted to string.

Related projects

• Nano ID – a similar project which allows more customization (both choosing the alphabet and the size); this project supports only one type of identifiers to make sure everyone using it has the same identifiers.

GitHub mirror

There is also a read-only GitHub mirror available, if you need to fork the project there.