Implement ShortUUID.Behaviour (#13)

* implement behaviour

* update readme

Author: gpedic

README.md

@@ -175,6 +175,57 @@ iex> SmileyUUID.encode("550e8400-e29b-41d4-a716-446655440000")
 
 ```
 
+## Implementing Compatible Modules
+
+Starting with version `v4.1.0`, ShortUUID provides a behavior that you can implement to create compatible modules. 
+This is useful if you want to create your own ShortUUID-compatible module with custom functionality while maintaining a consistent interface.
+
+```elixir
+defmodule MyCustomShortUUID do
+  @behaviour ShortUUID.Behaviour
+
+  @spec encode(String.t()) :: {:ok, String.t()} | {:error, String.t()}
+  def encode(uuid) do
+    # Your custom implementation here
+    {:ok, "encoded_" <> uuid}
+  end
+
+  @spec encode!(String.t()) :: String.t() | no_return()
+  def encode!(uuid) do
+    case encode(uuid) do
+      {:ok, encoded} -> encoded
+      {:error, msg} -> raise ArgumentError, message: msg
+    end
+  end
+
+  @spec decode(String.t()) :: {:ok, String.t()} | {:error, String.t()}
+  def decode(encoded) do
+    # Your custom implementation here
+    if String.starts_with?(encoded, "encoded_") do
+      {:ok, String.replace_prefix(encoded, "encoded_", "")}
+    else
+      {:error, "Invalid format"}
+    end
+  end
+
+  @spec decode!(String.t()) :: String.t() | no_return()
+  def decode!(encoded) do
+    case decode(encoded) do
+      {:ok, decoded} -> decoded
+      {:error, msg} -> raise ArgumentError, message: msg
+    end
+  end
+end
+```
+
+The `ShortUUID.Behaviour` requires implementing four callbacks:
+- `encode/1` - Encode a UUID into a shorter representation
+- `encode!/1` - Same as encode/1 but raises on error
+- `decode/1` - Decode a shortened UUID back to standard format
+- `decode!/1` - Same as decode/1 but raises on error
+
+Using this behavior ensures that your custom implementation will be compatible with code expecting a ShortUUID-compatible module.
+
 ## Documentation
 
 Look up the full documentation at [https://hexdocs.pm/shortuuid](https://hexdocs.pm/shortuuid).

lib/shortuuid.ex

@@ -18,6 +18,7 @@ defmodule ShortUUID do
       {:ok, "550e8400-e29b-41d4-a716-446655440000"}
 
   For custom alphabets and more options, see `ShortUUID.Builder`.
+  To implement your own compatible ShortUUID module, use `ShortUUID.Behaviour`.
   """
   use ShortUUID.Builder, alphabet: :base57_shortuuid
 end

lib/shortuuid/behaviour.ex

@@ -0,0 +1,80 @@
+defmodule ShortUUID.Behaviour do
+  @moduledoc """
+  Defines the behavior for ShortUUID-compatible modules.
+
+  This behavior ensures consistent interface across different ShortUUID implementations.
+  Any module implementing this behavior should provide encode/decode functionality
+  for converting UUIDs to shorter string representations and back.
+
+  ## Required Callbacks
+
+  - `encode/1` - Encodes a standard UUID into a shorter string
+  - `encode!/1` - Encodes a UUID, raising an exception on invalid input
+  - `decode/1` - Decodes a shortened UUID string back into standard UUID format
+  - `decode!/1` - Decodes a shortened UUID, raising an exception on invalid input
+  """
+
+  @doc """
+  Encodes a UUID string into a shorter string representation.
+
+  ## Parameters
+
+  - `uuid` - A standard UUID string (with or without hyphens)
+
+  ## Returns
+
+  - `{:ok, encoded}` - Successfully encoded string
+  - `{:error, message}` - Error with descriptive message
+  """
+  @callback encode(uuid :: String.t()) :: {:ok, String.t()} | {:error, String.t()}
+
+  @doc """
+  Encodes a UUID string into a shorter string representation.
+  Raises an ArgumentError if the input is invalid.
+
+  ## Parameters
+
+  - `uuid` - A standard UUID string (with or without hyphens)
+
+  ## Returns
+
+  - `encoded` - Successfully encoded string
+
+  ## Raises
+
+  - `ArgumentError` - If the input is invalid
+  """
+  @callback encode!(uuid :: String.t()) :: String.t() | no_return()
+
+  @doc """
+  Decodes a shortened UUID string back into standard UUID format.
+
+  ## Parameters
+
+  - `string` - A shortened UUID string
+
+  ## Returns
+
+  - `{:ok, uuid}` - Successfully decoded UUID
+  - `{:error, message}` - Error with descriptive message
+  """
+  @callback decode(string :: String.t()) :: {:ok, String.t()} | {:error, String.t()}
+
+  @doc """
+  Decodes a shortened UUID string back into standard UUID format.
+  Raises an ArgumentError if the input is invalid.
+
+  ## Parameters
+
+  - `string` - A shortened UUID string
+
+  ## Returns
+
+  - `uuid` - Successfully decoded UUID
+
+  ## Raises
+
+  - `ArgumentError` - If the input is invalid
+  """
+  @callback decode!(string :: String.t()) :: String.t() | no_return()
+end

lib/shortuuid/builder.ex

@@ -70,6 +70,7 @@ defmodule ShortUUID.Builder do
     quote do
       import Bitwise
       alias ShortUUID.Core
+      @behaviour ShortUUID.Behaviour
 
       @alphabet unquote(validated_alphabet)
       @padding_char unquote(padding_char)

mix.exs

@@ -2,7 +2,7 @@ defmodule ShortUUID.Mixfile do
   use Mix.Project
 
   @name "ShortUUID"
-  @version "4.0.0"
+  @version "4.1.0"
   @url "https://github.com/gpedic/ex_shortuuid"
 
   def project do