readable

README

Readable

Readable is a simple go package for generating fluent UUIDs.

Readables are UUIDs that are converted to a grammatically correct sentence. This makes them easy to remember and share, and adds spice to your life. You can convert a readable to a UUID and vice versa.

flowchart TD
U(( UUID )) <--> F(( Readable ))

F -- Hash --> S[[ Smol ]]
U -- Hash --> S

Examples

128-bit UUIDs

Corry Allie Evita the steerer of Bascom dreamed Lindsy Gunar Marlette and 2 short mice

Mira Corey Cord the morrow of Cedars prays Magdalene Abie Freya and 32 bright alpacas

Claire Gordon MacPherson the playmaker of Canova emptys Ilsa Alonzo Deery and 19 cute pheasants

Candis Duky Harriman the corncrib of Blevins deserted Caye Gardie Osbert and 21 deep moles

Doe Decca Giuliana the plea of Analomink dreams Lyndell Gregorio Mokas and 6 thirsty squirrels

32-bit Smol IDs

39 expensive ewes stealthily drove

24 hungry coyotes fondly sang

65 small bees kookily sang

3 high rooks greatly sings

43 low jackals needily sang

Features

• Built on UUID v4
• Optionally pass your UUID to generate a unique sentence
• 128 Bit Crypto Secure
• Grammatically correct sentences
• Easy to remember
• Has a Shakespeare feeling
• Universally Unique Identifier
• Generate Low Entropy 32 Bit Tokens

Installation

go get github.com/nascarsayan/readable

Usage

Create readable UUIDs

package main

import (
  "fmt"

  guid "github.com/google/uuid"
  "github.com/nascarsayan/readable"
)

sentence := readable.New()
fmt.Println(uid) 
// Dari Findlay Joaquin the pathos of Bandytown 
// preserves Daisy Cletis Alarice and 29 salty hogs

// + Interconvert between UUIDv4 and readable.

uuid := guid.New()
fmt.Println(uuid)
// 92e39d12-d0a6-4953-8999-edbf85f7ad66
sentence = readable.FromUUID(uuid)
fmt.Println(sentence)
// Janot Boniface Harriet the contestant of Broseley 
// preserved Carrissa Gayler Hahnert and 31 windy gnus

hex, err := readable.ToUUID(sentence)
if err != nil {
  fmt.Errorf("error converting readable to uuid: %v", err)
}
fmt.Println(hex)
// 92e39d12-d0a6-4953-8999-edbf85f7ad66

Create smol IDs from UUIDs or readables

package main

import (
  "fmt"

  "github.com/nascarsayan/readable"
)

long := readable.New()
fmt.Println(long)
// Allix Ernestus Matthieu the millwright of Cementon 
// dislikes Nerissa Fairfax Drucilla and 13 old aardvarks
short, err := readable.Smol(long)
if err != nil {
  fmt.Errorf("error converting uuid to smol: %v", err)
}
fmt.Println(short)
// 64 light doves lively ran

// Check if a smol ID is the hash of a readable
readable.VerifySmolWithReadable(short, long) // true
readable.VerifySmolWithReadable(short, readable.New()) // false

// Check if a smol ID is the hash of a UUID
uid := readable.ToUUID(sentence)
readable.VerifySmolWithUUID(short, uid) // true

Credits

• JS/TS: https://github.com/Debdut/uuid-readable

Documentation

Overview

Package readable provides a way to convert a byte array to a readable string and vice versa.

Index

• func FromUUID(u uuid.UUID) (string, error)
• func InitUID128()
• func InitUID32()
• func New() (string, error)
• func Smol(readable string) (string, error)
• func SmolFromUUID(u uuid.UUID) (string, error)
• func ToUUID(readable string) (*uuid.UUID, error)
• func VerifySmolWithReadable(smol string, readable string) bool
• func VerifySmolWithUUID(smol string, u uuid.UUID) bool
• type Converter
  • func (s *Converter) Marshal(data []byte) (string, error)
  • func (s *Converter) Unmarshal(sent string, bytes *[]byte) error

Functions

func FromUUID

func FromUUID(u uuid.UUID) (string, error)

FromUUID converts a uuid to a readable.

func InitUID128

func InitUID128()

InitUID128 initializes the readable package.

func InitUID32

func InitUID32()

InitUID32 initializes the uid32 converter.

func New

func New() (string, error)

New returns a new readable.

func Smol

func Smol(readable string) (string, error)

Smol returns a 32-bit hash of the given readable.

func SmolFromUUID

func SmolFromUUID(u uuid.UUID) (string, error)

SmolFromUUID returns a 32-bit hash of the given uuid.

func ToUUID

func ToUUID(readable string) (*uuid.UUID, error)

ToUUID converts a readable to a uuid.

func VerifySmolWithReadable

func VerifySmolWithReadable(smol string, readable string) bool

VerifySmolWithReadable verifies that the given smol is the 32-bit hash of the given readable.

func VerifySmolWithUUID

func VerifySmolWithUUID(smol string, u uuid.UUID) bool

VerifySmolWithUUID verifies that the given smol is the 32-bit hash of the given uuid.

Types

type Converter

type Converter struct {
	// contains filtered or unexported fields
}

Converter is a struct that converts a byte array to a readable string and vice versa.

func (*Converter) Marshal

func (s *Converter) Marshal(data []byte) (string, error)

Marshal converts a byte array to a readable string.

func (*Converter) Unmarshal

func (s *Converter) Unmarshal(sent string, bytes *[]byte) error

Unmarshal converts a readable string to a byte array.