Slab.Helpers.URI (Slab v1.0.0)

Helpers for reading and writing URL query parameters.

Slab stores UI state — checked rows, visible columns — in the URL query string so that table state survives navigation, refreshes, and can be shared as a link. These helpers manipulate query params on a URI string and return paths suitable for Phoenix.LiveView.push_patch/2.

Keys support single-level bracket notation (e.g. "filter[status]"), which encodes to nested query params.

Summary

Functions

create_or_update_or_delete_query_param(uri, key, value)

Sets a query param, or removes it when the value is nil, "", or [].

create_or_update_query_param(uri, key, value)

Sets a query param on the given URI string, replacing any existing value.

delete_query_param(uri, key)

Removes a query param from the given URI string.

extract_full_path(value)

Returns the path, query, and fragment of a URI as a single string, stripping scheme and host. Suitable for push_patch/2.

get_query_param(uri, key)

Returns the decoded value of a query param, or nil when absent.

get_query_param_count(uri)

Returns the number of query params on a URI, counting nested params recursively.

query_path(value)

Returns the path and query string of a URI as a single string.

Functions

create_or_update_or_delete_query_param(uri, key, value)

@spec create_or_update_or_delete_query_param(String.t(), String.t() | atom(), any()) ::
  String.t()

Sets a query param, or removes it when the value is nil, "", or [].

create_or_update_query_param(uri, key, value)

@spec create_or_update_query_param(String.t(), String.t() | atom(), any()) ::
  String.t()

Sets a query param on the given URI string, replacing any existing value.

Examples

iex> Slab.Helpers.URI.create_or_update_query_param("/users", "sort", "name")
"/users?sort=name"

iex> Slab.Helpers.URI.create_or_update_query_param("/users?sort=name", "sort", "email")
"/users?sort=email"

delete_query_param(uri, key)

@spec delete_query_param(String.t(), String.t() | atom()) :: String.t()

Removes a query param from the given URI string.

Examples

iex> Slab.Helpers.URI.delete_query_param("/users?sort=name&page=2", "sort")
"/users?page=2"

iex> Slab.Helpers.URI.delete_query_param("/users?sort=name", "sort")
"/users"

extract_full_path(value)

@spec extract_full_path(String.t()) :: String.t()

Returns the path, query, and fragment of a URI as a single string, stripping scheme and host. Suitable for push_patch/2.

Examples

iex> Slab.Helpers.URI.extract_full_path("https://example.com/users?sort=name#top")
"/users?sort=name#top"

get_query_param(uri, key)

@spec get_query_param(String.t(), String.t()) :: String.t() | list() | map() | nil

Returns the decoded value of a query param, or nil when absent.

Array params (checked[]=1&checked[]=2) decode to lists, bracket params decode to maps.

Examples

iex> Slab.Helpers.URI.get_query_param("/users?sort=name", "sort")
"name"

iex> Slab.Helpers.URI.get_query_param("/users?checked[]=1&checked[]=2", "checked")
["1", "2"]

iex> Slab.Helpers.URI.get_query_param("/users", "sort")
nil

get_query_param_count(uri)

@spec get_query_param_count(String.t() | nil) :: non_neg_integer()

Returns the number of query params on a URI, counting nested params recursively.

Useful as the count badge on a share tab — it reflects how much state the shareable URL carries.

Examples

iex> Slab.Helpers.URI.get_query_param_count("/users?sort=name&filter[role]=admin")
2

iex> Slab.Helpers.URI.get_query_param_count("/users")
0

query_path(value)

@spec query_path(String.t()) :: String.t()

Returns the path and query string of a URI as a single string.

Examples

iex> Slab.Helpers.URI.query_path("https://example.com/users?sort=name")
"/users?sort=name"

iex> Slab.Helpers.URI.query_path("https://example.com/users")
"/users"