/uxid-ex

User eXperience focused IDentifiers - Elixir implementation

Primary LanguageElixirMIT LicenseMIT

UXID

MIT License Hex Version Hex Downloads

User eXperience focused IDentifiers (UXIDs) are identifiers which:

  • Describe the resource (aid in debugging and investigation)
  • Work well with copy and paste (double clicking selects the entire ID)
  • Can be shortened for low cardinality resources
  • Are secure against enumeration attacks
  • Can be generated by application code (not tied to the datastore)
  • Are K-sortable (lexicographically sortable by time - works well with datastore indexing)
  • Do not require any coordination (human or automated) at startup, or generation
  • Are very unlikely to collide (more likely with less randomness)
  • Are easily and accurately transmitted to another human using a telephone

Many of the concepts of Stripe IDs have been used in this library.

Usage

Generating UXIDs

# No options generates a basic ULID
UXID.generate! # "01EMDGJF0DQXQJ8FM78XE97Y3H"

# A prefix can be provided
UXID.generate! prefix: "cus" # "cus_01EMDGJF0DQXQJ8FM78XE97Y3H"

# The amount of randomness can be decreased for smaller cardinality resources
# T-Shirt sizes can be used (xs, s, m, l, xl) or (xsmall, small, medium, large, xlarge)
UXID.generate! prefix: "cus", size: :small # "cus_01EQRH884AQYY1"

Ecto

UXIDs can be used as Ecto fields including primary keys.

defmodule YourApp.User do
  use Ecto.Schema

  @primary_key {:id, UXID, autogenerate: true, prefix: "usr", size: :medium}
  schema "users" do
    field :api_key, UXID, autogenerate: true, prefix: "apikey", size: :small
    field :api_secret, UXID, autogenerate: true, prefix: "apisecret", size: :xlarge
  end
end

Installation

The package can be installed by adding uxid to your list of dependencies in mix.exs:

def deps do
  [
    {:uxid, "~> 0.2"}
  ]
end

Online documenttion can be found at https://hexdocs.pm/uxid.