gpedic / ex_shortuuid

ShortUUID is a simple UUID shortener for Elixir.

ShortUUID

ShortUUID is a lightweight Elixir library that generates short and unique IDs for use in URLs. It provides a solution when you need IDs that are easy to use and understand for users.

Instead of using long and complex UUIDs, ShortUUID converts them into shorter strings using a combination of lowercase and uppercase letters, as well as digits. It avoids using similar-looking characters such as 'l', '1', 'I', 'O', and '0'.

Note: It's worth noting that different ShortUUID implementations should work together if they use the same set of characters. However, there is no official standard, so if you plan to use ShortUUID with other libraries, it's a good idea to research and test for compatibility.

Unlike some other libraries, ShortUUID doesn't generate UUIDs itself. Instead, you can input any valid UUID into the ShortUUID.encode/1. To generate UUIDs, you can use libraries like Elixir UUID, Erlang UUID and also Ecto as it can generate version 4 UUIDs.

ShortUUID supports common UUID formats and is case-insensitive. It also supports binary UUIDs returned from DBs like PostgreSQL when the uuid type is used to store the UUID.

Compatibility

Starting with version v3.0.0, this library will follow suit with changes in other language implementations and move the most significant bit of the encoded value to the start. This also means that padding will be applied to the end of the string, not the start This change will restore compatibility with other libraries like shortuuid from v1.0.0 onwards and short-uuid .

Before v3.0.0

iex> "00000001-0001-0001-0001-000000000001" |> ShortUUID.encode
{:ok, "UD6ibhr3V4YXvriP822222"}

After v3.0.0

iex> "00000001-0001-0001-0001-000000000001" |> ShortUUID.encode
{:ok, "222228PirvXY4V3rhbi6DU"}

To migrate ShortUUIDs created using < v3.0.0 reverse them before passing to decode.

# UUID "00000001-0001-0001-0001-000000000001" encoded using v2.1.2 to "UD6ibhr3V4YXvriP822222"
# reversing the encoded string before decode with v3.0.0 will produce the correct result
iex> "UD6ibhr3V4YXvriP822222" |> String.reverse() |> ShortUUID.decode!()
"00000001-0001-0001-0001-000000000001"

Warning: Decoding ShortUUIDs created using a version < v3.0.0 without reversing the string first will not fail but produce an incorrect result

iex> "UD6ibhr3V4YXvriP822222" |> ShortUUID.decode!() === "00000001-0001-0001-0001-000000000001"
false
iex> "UD6ibhr3V4YXvriP822222" |> ShortUUID.decode()
{:ok, "933997ef-eb92-293f-b202-2a879fc84be9"}

Installation

Add :shortuuid to your list of dependencies in mix.exs:

def deps do
  [
    {:shortuuid, "~> 3.0"}
  ]
end

Examples

iex> "f98e80e7-9923-4173-8408-98f8254912ad" |> ShortUUID.encode
{:ok, "nQtAWSRQ6ByybDtRs7dQwE"}

iex> "f98e80e7-9923-4173-8408-98f8254912ad" |> ShortUUID.encode!
"nQtAWSRQ6ByybDtRs7dQwE"

iex> "nQtAWSRQ6ByybDtRs7dQwE" |> ShortUUID.decode
{:ok, "f98e80e7-9923-4173-8408-98f8254912ad"}

iex> "nQtAWSRQ6ByybDtRs7dQwE" |> ShortUUID.decode!
"f98e80e7-9923-4173-8408-98f8254912ad"

Using ShortUUID with Ecto

If you would like to use ShortUUID with Ecto schemas try Ecto.ShortUUID.

It provides a custom Ecto type which allows for ShortUUID primary and foreign keys while staying compatible with :binary_key (EctoUUID).

Documentation

Look up the full documentation at https://hexdocs.pm/shortuuid.

Acknowledgments

Inspired by shortuuid.

Copyright and License

Copyright (c) 2019 Goran Pedić

This work is free. You can redistribute it and/or modify it under the terms of the MIT License.

See the LICENSE.md file for more details.

ex_shortuuid's Issues

Short UUID compatibility with other libraries

There seem to be a compatibility issue with other short UUID (base57) tools out there. I've tried to compare the results of this library with results of the JS library and a python one and the results are the same between them but not the same with this elixir library.

Elixir example:

iex(6)> "91f10722-c263-4752-9ecf-53fde67c4028" |> ShortUUID.encode()
{:ok, "9JwfvPdZY9QKG6BPovn5yT"}

While JS and python libs yield:
Ty5nvoPB6GKQ9YZdPvfwJ9

Note I'm using the same alphabet of 23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz.

In the docs you specify that there should be no difference between other short uuid tools and this one so maybe this is something worth looking into. In our case it makes it hard for the JS app to communicate with our elixir server.

Thanks in advance!

Customize alphabet ?

Hi,

I would like to know if it's possible to have a version that allows customizing the alphabet used by the module?

Regards

Infinite loop with `pad_uuid`

It seems that pad_uuid will infinitely loop seemingly when given a short uuid that becomes an integer larger than a certain size.

Examples...

ShortUUID.decode("vurAvy8qYnp94isZcMSEPL") # Good
ShortUUID.decode("vurAvy8qYnp94isZcMSEPo") # Also, good
ShortUUID.decode("vurAvy8qYnp94isZcMSEPp") # Last character of p-z bad

And here's how each of those passes through steps in decode into pad_uuid...

Good
Input: "vurAvy8qYnp94isZcMSEPL"
Enum.reduce => 137256910693763254344733850037719112472
Integer.to_string => "6742B82D15634DB1B77FE1D2D4C79B18"

Good
Input: "vurAvy8qYnp94isZcMSEPo"
Enum.reduce => 338970767512771414526517954761987534011
Integer.to_string => "FF0365280EB0311FC6B2019237352CBB"

Bad
Input: "vurAvy8qYnp94isZcMSEPp"
Enum.reduce => 346441651098660605644361810492515994068
Integer.to_string => "104A23C27DF085F792F8DEFC8B61CC9D4"

Here's some logging from the loop...

[label: "uuid 104A23C27DF085F792F8DEFC8B61CC9D4"]                                                                     
[label: "uuid 0104A23C27DF085F792F8DEFC8B61CC9D4"]                                                                    
[label: "uuid 00104A23C27DF085F792F8DEFC8B61CC9D4"]
[label: "uuid 000104A23C27DF085F792F8DEFC8B61CC9D4"]
[label: "uuid 0000104A23C27DF085F792F8DEFC8B61CC9D4"]
[label: "uuid 00000104A23C27DF085F792F8DEFC8B61CC9D4"]
[label: "uuid 000000104A23C27DF085F792F8DEFC8B61CC9D4"]
[label: "uuid 0000000104A23C27DF085F792F8DEFC8B61CC9D4"]
[label: "uuid 00000000104A23C27DF085F792F8DEFC8B61CC9D4"]
[label: "uuid 000000000104A23C27DF085F792F8DEFC8B61CC9D4"]
[label: "uuid 0000000000104A23C27DF085F792F8DEFC8B61CC9D4"] 
[label: "uuid 00000000000104A23C27DF085F792F8DEFC8B61CC9D4"]
[label: "uuid 000000000000104A23C27DF085F792F8DEFC8B61CC9D4"]
[label: "uuid 0000000000000104A23C27DF085F792F8DEFC8B61CC9D4"]
[label: "uuid 00000000000000104A23C27DF085F792F8DEFC8B61CC9D4"]
[label: "uuid 000000000000000104A23C27DF085F792F8DEFC8B61CC9D4"]