defmodule NavEx do
@moduledoc """
NavEx is a navigation history tool that uses adapter pattern
and lets you choose between available adapters or just to
write your own adapter.
There are 2 available adapters right now - ETS adapter storing
user navigation history in the ETS and Session adapter storing
user navigation history in user's sessions.
## Configuration:
config :nav_ex,
tracked_methods: ["GET"], # what methods to track
excluded_paths: ["/admin", "/dev], # paths you won't need to keep track on
history_length: 10, # what is the history list length per user
adapter: NavEx.Adapters.ETS # adapter used by NavEx to save data
adapter_config: ... # adapter specific configuration
### ETS Adapter config
adapter_config: %{
identity_key: "nav_ex_identity", # name of the key in session where the user's identity is saved
table_name: :navigation_history # name of the ETS table
}
## Session Adapter config
adapter_config: %{
history_key: "nav_ex_history" # name of the key in session where navigation history is saved
}
"""
@adapter Application.compile_env(:nav_ex, :adapter) || NavEx.Adapters.ETS
@tracked_methods Application.compile_env(:nav_ex, :tracked_methods) || ["GET"]
@history_length (Application.compile_env(:nav_ex, :history_length) || 10) + 1
@doc """
Used by ExNav.Plug. Takes %Plug.Conn{} as an input.
Calls Adapter `insert/1` function. Returns `{:ok, %Plug.Conn{}}` or `{:ok, %Phoenix.LiveView.Socket{}}` tuple.
## Examples
iex(1)> NavEx.insert(conn)
{:ok, %Plug.Conn{...}}
iex(2)> NavEx.insert(socket, "/sample/path")
{:ok, %Phoenix.LiveView.Socket{...}}
"""
def insert(%Plug.Conn{method: method} = conn)
when method in @tracked_methods,
do: @adapter.insert(conn)
def insert(%Plug.Conn{} = conn), do: {:ok, conn}
def insert(%Phoenix.LiveView.Socket{} = socket, path)
when is_binary(path) do
@adapter.insert(socket, path)
end
@doc """
Takes %Plug.Conn{} or %Phoenix.LiveView.Socket{} as an input. Calls Adapter `list/1` function.
## Examples
# for existing user
iex(1)> NavEx.list(conn)
{:ok, ["/sample/path/2", "sample/path/1]}
# for not existing user
iex(2)> NavEx.list(conn)
{:error, :not_found}
# for sockets
iex(3)> NavEx.list(socket)
{:ok, ["/sample/path/2", "sample/path/1]}
"""
def list(%Plug.Conn{} = conn), do: @adapter.list(conn)
def list(%Phoenix.LiveView.Socket{} = socket), do: @adapter.list(socket)
@doc """
Takes %Plug.Conn{} or %Phoenix.LiveView.Socket{} as an input. Calls Adapter `last_path/1` function.
## Examples
# for existing user
iex(1)> NavEx.last_path(conn)
{:ok, "/sample/path"}
# for existing user, but without 2 paths
iex(2)> NavEx.last_path(conn)
{:ok, nil}
# for not existing user
iex(3)> NavEx.last_path(conn)
{:error, :not_found}
# for sockets
iex(4)> NavEx.last_path(socket)
{:ok, "/sample/path"}
"""
def last_path(%Plug.Conn{} = conn), do: @adapter.last_path(conn)
def last_path(%Phoenix.LiveView.Socket{} = socket),
do: @adapter.last_path(socket)
@doc """
Takes %Plug.Conn{} or %Phoenix.LiveView.Socket{} and number as inputs. Calls Adapter `path_at/1` function.
## Examples
# for existing user
iex(1)> NavEx.path_at(conn, 5)
{:ok, "/sample/path"}
# for existing user but exceeding paths number
iex(2)> NavEx.path_at(conn, 5)
{:ok, nil}
# for not existing user
iex(3)> NavEx.path_at(conn, 5)
{:error, :not_found}
# exceeding history limit
iex(4)> NavEx.path_at(conn, 999)
** (ArgumentError) Max history depth is 10 counted from 0 to 9. You asked for record number 999.
# for sockets
iex(5)> NavEx.path_at(socket, 5)
{:ok, "/sample/path"}
"""
def path_at(%Plug.Conn{} = conn, n) when is_integer(n) and n < @history_length - 1,
do: @adapter.path_at(conn, n)
def path_at(%Plug.Conn{} = _conn, n) when is_integer(n) do
raise ArgumentError,
"Max history depth is #{@history_length - 1} counted from 0 to #{@history_length - 2}. You asked for record number #{n}."
end
def path_at(%Phoenix.LiveView.Socket{} = socket, n)
when is_integer(n) and n < @history_length - 1,
do: @adapter.path_at(socket, n)
def path_at(%Phoenix.LiveView.Socket{} = _socket, n) when is_integer(n) do
raise ArgumentError,
"Max history depth is #{@history_length - 1} counted from 0 to #{@history_length - 2}. You asked for record number #{n}."
end
end