{"id":13509387,"url":"https://github.com/gpedic/ex_shortuuid","last_synced_at":"2026-02-18T09:42:04.802Z","repository":{"id":45873227,"uuid":"100687554","full_name":"gpedic/ex_shortuuid","owner":"gpedic","description":"ShortUUID is a simple UUID shortener for Elixir.","archived":false,"fork":false,"pushed_at":"2025-04-09T10:46:21.000Z","size":106,"stargazers_count":51,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-11-22T06:09:30.395Z","etag":null,"topics":["elixir","encoding","shortuuid"],"latest_commit_sha":null,"homepage":null,"language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gpedic.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-08-18T07:52:33.000Z","updated_at":"2025-11-07T21:07:35.000Z","dependencies_parsed_at":"2025-04-08T20:39:16.067Z","dependency_job_id":null,"html_url":"https://github.com/gpedic/ex_shortuuid","commit_stats":{"total_commits":31,"total_committers":3,"mean_commits":"10.333333333333334","dds":"0.12903225806451613","last_synced_commit":"1766fe3f39064b48e974ccbd0859a9cd312b8437"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/gpedic/ex_shortuuid","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gpedic%2Fex_shortuuid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gpedic%2Fex_shortuuid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gpedic%2Fex_shortuuid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gpedic%2Fex_shortuuid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gpedic","download_url":"https://codeload.github.com/gpedic/ex_shortuuid/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gpedic%2Fex_shortuuid/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29575108,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-18T08:38:15.585Z","status":"ssl_error","status_checked_at":"2026-02-18T08:38:14.917Z","response_time":162,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["elixir","encoding","shortuuid"],"created_at":"2024-08-01T02:01:07.060Z","updated_at":"2026-02-18T09:41:59.792Z","avatar_url":"https://github.com/gpedic.png","language":"Elixir","funding_links":[],"categories":["Text and Numbers"],"sub_categories":[],"readme":"# ShortUUID\n\n![Build Status](https://github.com/gpedic/ex_shortuuid/actions/workflows/ci.yml/badge.svg?branch=master)\n[![Coverage Status](https://coveralls.io/repos/github/gpedic/ex_shortuuid/badge.svg)](https://coveralls.io/github/gpedic/ex_shortuuid)\n[![Module Version](https://img.shields.io/hexpm/v/shortuuid.svg)](https://hex.pm/packages/shortuuid)\n[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/shortuuid/)\n[![Total Download](https://img.shields.io/hexpm/dt/shortuuid.svg)](https://hex.pm/packages/shortuuid)\n[![License](https://img.shields.io/hexpm/l/shortuuid.svg)](https://github.com/gpedic/ex_shortuuid/blob/master/LICENSE.md)\n[![Last Updated](https://img.shields.io/github/last-commit/gpedic/shortuuid.svg)](https://github.com/gpedic/ex_shortuuid/commits/master)\n\n\u003c!-- MDOC !--\u003e\n\nShortUUID is a lightweight Elixir library for generating short, unique IDs in URLs. It turns standard UUIDs into smaller strings ideal for use in URLs.\nYou can choose from a set of predefined alphabets or define your own. \nThe default alphabet includes lowercase letters, uppercase letters, and digits, omitting characters like 'l', '1', 'I', 'O', and '0' to keep them readable.\n\n**Note:** Different ShortUUID implementations be compatible as long as they use the same alphabet. 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.\n\nUnlike some other solutions, ShortUUID does not produce UUIDs on its own as there are already plenty of libraries to do so. To generate UUIDs, use libraries such as\n[Elixir UUID](https://github.com/zyro/elixir-uuid), [Erlang UUID](https://github.com/okeuday/uuid) and also [Ecto](https://hexdocs.pm/ecto/Ecto.UUID.html) as it can generate version 4 UUIDs.\n\nShortUUID supports common UUID formats and is case-insensitive.\n\n## Compatibility\n\n### v4.0.0 breaking changes\n\nRaw binary UUID input (as `\u003c\u003c...\u003e\u003e`) is no longer supported. UUIDs must be provided as strings in standard UUID format (`\"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"`) or as 32-character hex strings without hyphens.\n\nExamples of supported formats:\n```elixir\n# Supported\n\"550e8400-e29b-41d4-a716-446655440000\"  # With hyphens\n\"550e8400e29b41d4a716446655440000\"      # Without hyphens\n\n# No longer supported in v4.0.0\n\u003c\u003c85, 14, 132, 0, 226, 155, 65, 212, 167, 22, 68, 102, 85, 68, 0, 0\u003e\u003e\n```\n\n### v3.0.0 breaking changes\n\nChanged bit order and padding behavior to align with other language implementations:\n- Most significant bits are now encoded first\n- Padding characters appear at the end of the string\n- Compatible with Python's [shortuuid](https://github.com/skorokithakis/shortuuid) v1.0.0+ and Node.js [short-uuid](https://github.com/oculus42/short-uuid)\n\nBefore `v3.0.0`\n```elixir\n\niex\u003e \"00000001-0001-0001-0001-000000000001\" |\u003e ShortUUID.encode\n{:ok, \"UD6ibhr3V4YXvriP822222\"}\n\n```\n\nAfter `v3.0.0`\n```elixir\n\niex\u003e \"00000001-0001-0001-0001-000000000001\" |\u003e ShortUUID.encode\n{:ok, \"222228PirvXY4V3rhbi6DU\"}\n\n```\n\nTo migrate ShortUUIDs created using `\u003c v3.0.0` reverse them before passing to `decode`.\n\n```elixir\n# UUID \"00000001-0001-0001-0001-000000000001\" encoded using v2.1.2 to \"UD6ibhr3V4YXvriP822222\"\n# reversing the encoded string before decode with v3.0.0 will produce the correct result\niex\u003e \"UD6ibhr3V4YXvriP822222\" |\u003e String.reverse() |\u003e ShortUUID.decode!()\n\"00000001-0001-0001-0001-000000000001\"\n```\n\n*Warning:* Decoding ShortUUIDs created using a version `\u003c v3.0.0` without reversing the string first will not fail but produce an incorrect result\n\n```elixir\niex\u003e \"UD6ibhr3V4YXvriP822222\" |\u003e ShortUUID.decode!() === \"00000001-0001-0001-0001-000000000001\"\nfalse\niex\u003e \"UD6ibhr3V4YXvriP822222\" |\u003e ShortUUID.decode()\n{:ok, \"933997ef-eb92-293f-b202-2a879fc84be9\"}\n```\n\n## Installation\n\nAdd `:shortuuid` to your list of dependencies in `mix.exs`:\n\n```elixir\ndef deps do\n  [\n    {:shortuuid, \"~\u003e 4.0\"}\n  ]\nend\n```\n\n## Examples\n\n```elixir\niex\u003e \"f98e80e7-9923-4173-8408-98f8254912ad\" |\u003e ShortUUID.encode\n{:ok, \"nQtAWSRQ6ByybDtRs7dQwE\"}\n\niex\u003e \"f98e80e7-9923-4173-8408-98f8254912ad\" |\u003e ShortUUID.encode!\n\"nQtAWSRQ6ByybDtRs7dQwE\"\n\niex\u003e \"nQtAWSRQ6ByybDtRs7dQwE\" |\u003e ShortUUID.decode\n{:ok, \"f98e80e7-9923-4173-8408-98f8254912ad\"}\n\niex\u003e \"nQtAWSRQ6ByybDtRs7dQwE\" |\u003e ShortUUID.decode!\n\"f98e80e7-9923-4173-8408-98f8254912ad\"\n```\n\n## Using ShortUUID with Ecto\n\nIf you would like to use ShortUUID with Ecto schemas try [Ecto.ShortUUID](https://github.com/gpedic/ecto_shortuuid).\n\nIt provides a custom Ecto type which allows for ShortUUID primary and foreign keys while staying compatible with `:binary_key` (`EctoUUID`).\n\n## Custom Alphabets\n\nStarting with version `v4.0.0`, ShortUUID allows you to define custom alphabets for encoding and decoding UUIDs. You can use predefined alphabets or define your own.\n\n### Restrictions\n\n- The alphabet must contain at least 16 unique characters.\n- The alphabet must not contain duplicate characters.\n\n### Predefined Alphabets\n\nStarting with version `v4.0.0`, the following predefined alphabets are available:\n\n- `:base57_shortuuid` - \"23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz\"\n- `:base32` - \"ABCDEFGHIJKLMNOPQRSTUVWXYZ234567\"\n- `:base32_crockford` - \"0123456789ABCDEFGHJKMNPQRSTVWXYZ\"\n- `:base32_hex` - \"0123456789ABCDEFGHIJKLMNOPQRSTUV\"\n- `:base32_z` - \"ybndrfg8ejkmcpqxot1uwisza345h769\"\n- `:base58` - \"123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz\"\n- `:base62` - \"0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz\"\n- `:base64` - \"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/\"\n- `:base64_url` - \"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_\"\n\n### Using a custom or predefined alphabet\n\n```elixir\ndefmodule MyBase58UUID do\n  use ShortUUID.Builder, alphabet: :base58\nend\n\ndefmodule MyCustomUUID do\n  use ShortUUID.Builder, alphabet: \"0123456789ABCDEF\"\nend\n\niex\u003e MyBase58UUID.encode(\"550e8400-e29b-41d4-a716-446655440000\")\n{:ok, \"BWBeN28Vb7cMEx7Ym8AUzs\"}\n\niex\u003e MyBase58UUID.decode(\"BWBeN28Vb7cMEx7Ym8AUzs\")\n{:ok, \"550e8400-e29b-41d4-a716-446655440000\"}\n```\n\n### Just for fun\n\nSince v4.0.0 alphabets are not limited to alphanumeric characters either\n\n```elixir\ndefmodule UnicodeUUID do\n  use ShortUUID.Builder, alphabet: \"🌟💫✨⭐️🌙🌎🌍🌏🌑🌒🌓🌔🌕🌖🌗🌘\"\nend\n\niex\u003e UnicodeUUID.encode(\"550e8400-e29b-41d4-a716-446655440000\")\n{:ok, \"🌎🌎🌟🌗🌑🌙🌟🌟🌗✨🌒🌔🌙💫🌖🌙🌓🌏💫🌍🌙🌙🌍🌍🌎🌎🌙🌙🌟🌟🌟🌟\"}\n\n\ndefmodule SmileyUUID do\n  use ShortUUID.Builder, alphabet: \"😀😊😄😍🥰😘😜🤪😋🤔😌🧐😐😑😶😮😲😱😴🥱😪😢😭😤😎🤓😇😈👻👽🤖🤡💀\"\nend\n\niex\u003e SmileyUUID.encode(\"550e8400-e29b-41d4-a716-446655440000\")\n{:ok, \"😊🤪😢😘💀🥰😲😊🤡🤖🤔😊😘😤👽🤓👻😊👽😲😋😀😭😇😲🤖\"}\n\n```\n\n## Implementing Compatible Modules\n\nStarting with version `v4.1.0`, ShortUUID provides a behavior that you can implement to create compatible modules. \nThis is useful if you want to create your own ShortUUID-compatible module with custom functionality while maintaining a consistent interface.\n\n```elixir\ndefmodule MyCustomShortUUID do\n  @behaviour ShortUUID.Behaviour\n\n  @spec encode(String.t()) :: {:ok, String.t()} | {:error, String.t()}\n  def encode(uuid) do\n    # Your custom implementation here\n    {:ok, \"encoded_\" \u003c\u003e uuid}\n  end\n\n  @spec encode!(String.t()) :: String.t() | no_return()\n  def encode!(uuid) do\n    case encode(uuid) do\n      {:ok, encoded} -\u003e encoded\n      {:error, msg} -\u003e raise ArgumentError, message: msg\n    end\n  end\n\n  @spec decode(String.t()) :: {:ok, String.t()} | {:error, String.t()}\n  def decode(encoded) do\n    # Your custom implementation here\n    if String.starts_with?(encoded, \"encoded_\") do\n      {:ok, String.replace_prefix(encoded, \"encoded_\", \"\")}\n    else\n      {:error, \"Invalid format\"}\n    end\n  end\n\n  @spec decode!(String.t()) :: String.t() | no_return()\n  def decode!(encoded) do\n    case decode(encoded) do\n      {:ok, decoded} -\u003e decoded\n      {:error, msg} -\u003e raise ArgumentError, message: msg\n    end\n  end\nend\n```\n\nThe `ShortUUID.Behaviour` requires implementing four callbacks:\n- `encode/1` - Encode a UUID into a shorter representation\n- `encode!/1` - Same as encode/1 but raises on error\n- `decode/1` - Decode a shortened UUID back to standard format\n- `decode!/1` - Same as decode/1 but raises on error\n\nUsing this behavior ensures that your custom implementation will be compatible with code expecting a ShortUUID-compatible module.\n\n## Documentation\n\nLook up the full documentation at [https://hexdocs.pm/shortuuid](https://hexdocs.pm/shortuuid).\n\n## Acknowledgments\n\nInspired by [shortuuid](https://github.com/skorokithakis/shortuuid).\n\n## Copyright and License\n\nCopyright (c) 2024 Goran Pedić\n\nThis work is free. You can redistribute it and/or modify it under the\nterms of the MIT License. \n\nSee the [LICENSE.md](./LICENSE.md) file for more details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgpedic%2Fex_shortuuid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgpedic%2Fex_shortuuid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgpedic%2Fex_shortuuid/lists"}