README
¶
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.20 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.
Documentation
¶
Overview ¶
Package provides functions to generate and parse readable global identifiers.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrInvalidIdentifier = errors.Base("invalid identifier")
Functions ¶
Types ¶
type Identifier ¶
type Identifier [16]byte
func FromData ¶
func FromData(data [16]byte) Identifier
FromData returns 16 bytes data encoded as an Identifier.
func FromReader ¶
func FromReader(r io.Reader) (Identifier, errors.E)
FromReader returns a new random identifier using r as a source of randomness.
func FromString ¶
func FromString(data string) (Identifier, errors.E)
FromString parses a string-encoded identifier in base 58 encoding into a corresponding Identifier value.
func FromUUID ¶
func FromUUID(data uuid.UUID) Identifier
FromUUID returns the UUID encoded as an Identifier.
func MustFromReader ¶
func MustFromReader(r io.Reader) Identifier
MustFromReader is the same as FromReader but panics on an error.
func MustFromString ¶
func MustFromString(data string) Identifier
MustFromString is the same as FromString but panics on an error.
func (Identifier) MarshalText ¶
func (i Identifier) MarshalText() ([]byte, error)
func (Identifier) String ¶
func (i Identifier) String() string
String encodes Identifier value into a string using base 58 encoding.
func (*Identifier) UnmarshalText ¶
func (i *Identifier) UnmarshalText(text []byte) error
Source Files