id64

id64 provides probably-unique, random, 64-bit identifiers.

Properties

id64 was created with some very specific goals in mind:

• id64's are represented as a single, uint64
  • for single-operation comparisons (one 64-bit word each)
  • can also be cast to an int64 for storage as a simpler int (e.g. for sqlite)
• alternatively, id64's may be represented as a 11-byte, Base64-encoded string
  • safe for use in HTTP GET requests
  • safe for use as file names (on unix)
    • Note: ~ is included, but will never be the first character of an id
• id64's can be transformed in both directions between string and numeric forms (see below)
• id64's have exactly one string representation
  • for reliable comparison
  • id64's are case-sensitive
• non-random id64's can be sorted
  • by their numeric value (i.e. uint64)
  • by their string value (i.e. []byte)
  • numeric and string (byte-order) collation order is identical!
  • (e.g. 64-bit timestamps can also be used as id64's)
• implemented in go
  • with an additional CLI command, id64
  • with a port for JS

Notes:

• Base64 alphabet used (note: in ascending code-point order) 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz~
• the first character of each id64 string is restricted to the characters 0..F due to the fact that 11 Base64 bytes can encode 66 bits (so the first character only encodes 4 bits and all other characters encode 6 bits each).
• the tilde character ~ will never be the first character of an id64 string, so there is no chance that the id64 string can be mis-interpreted as a unix home directory.

Command Line

id64 - random 64-bit id generator

Usage:
    id64 [-isx] [number|id64]
    id64 [-hv]

Description:
    By default, id64 generates a new, random, 64-bit id.
    If a number is provided, that number will be converted to an id64 string.
    If valid id64 id is provided, its numeric value will be printed.
    The -i, -s and -x flags override the default output format.

Options:
    -i      display the id as an integer
    -s      display the id as a Base-64 string
    -x      display the id as a hexadecimal string
    number  an integer to encode as an id64 string
    id64    an id64 string to decode

    -h      show this help and exit
    -v      show version info and exit

Examples

# generate a new random id
% id64
BVUCZkBD2wm

# generate a random 64-bit hex string
% id64 -x
0xef0b6d9bf902b638

# convert an id64 to its hex value
% id64 BVUCZkBD2wm
0xb7de323bcb342ef1

# convert an id64 to its integer value
% id64 -i BVUCZkBD2wm
13249082386164231921

# convert a hex value to an id64
% id64 0xb7de323bcb342ef1
BVUCZkBD2wm

# convert an integer value to an id64
% id64 13249082386164231921
BVUCZkBD2wm

Golang

Usage:

import "codeberg.org/japh/id64"

// create a new, random ID64
id := id64.NewRandomID()              // => 0xf414d42d56e87d7e

// transformations of an id64 between its uint64 and string forms
uint64ID := id.Uint64()               // => uint64(0xf414d42d56e87d7e)
uint64ID := uint64(id)                // => uint64(0xf414d42d56e87d7e)
int64ID  := id.Int64()                // => int64(0xf414d42d56e87d7e)
int64ID  := int64(id)                 // => int64(0xf414d42d56e87d7e)
stringID := id.String()               // => "4FJp1pLu6py"
id2      := id64.FromString(idString) // => id64.ID64(0xf414d42d56e87d7e)
bytesID  := id.Bytes()                // => []byte{0xf4, 0x14, 0xd4, 0x2d, 0x56, 0xe8, 0x7d, 0x7e} // big endian
id3      := id64.FromBytes(bytesID)   // => id64.ID64(0xf414d42d56e87d7e)

Javascript

The Javascript implementation currently only provides the ability to create pseudorandom id64's. Once created, javascript code should simply use the generated ID's as read-only strings.

import { RandomID } from "./id64.mjs"

const id = RandomID()