shortuuid

# ShortUUID usage rules

ShortUUID converts existing UUIDs to short strings and back.

- It does not generate UUIDs. Generate them with `Ecto.UUID.generate/0`,
  [Uniq](https://hex.pm/packages/uniq) or similar, then encode them.
- `ShortUUID.encode/1` and `ShortUUID.decode/1` use the default alphabet
  `:base57_shortuuid`, the same default as Python's `shortuuid`.
- For a different alphabet, define a module and call it the same way:

  ```elixir
  defmodule MyApp.ShortID do
    use ShortUUID.Builder, alphabet: :base58
  end

  MyApp.ShortID.encode("550e8400-e29b-41d4-a716-446655440000")
  ```

  The alphabet must be a predefined atom or a literal string; it is validated
  at compile time. Don't call `ShortUUID.Core` directly.
- Never change a module's alphabet once short IDs are stored or shared. The
  same UUID gets a different short ID, and old IDs can silently decode to a
  different, valid UUID instead of failing.
- On untrusted input use `decode/1` and `encode/1`, which return
  `{:error, message}` for any invalid term and never raise. `decode!/1` and
  `encode!/1` raise `ArgumentError`.
- `encode/1` accepts UUIDs with or without hyphens, in curly braces or as
  `urn:uuid:`, in any letter case. `decode/1` always returns a lowercase,
  hyphenated UUID.
- Short IDs are case-sensitive. Don't downcase, trim or otherwise normalize them.
- `:base64` and custom alphabets may contain characters that need escaping in
  URLs; the other predefined alphabets are URL-safe.
- To share IDs with Python `shortuuid` or Node.js `short-uuid`, use an alphabet
  marked compatible in the README's compatibility table. A mismatched alphabet
  decodes to the wrong UUID instead of failing.
- For Ecto schemas, use the `ecto_shortuuid` package instead of converting by hand.