@spec atom_to_readable_string(atom()) :: String.t()

Converts an atom into a human-readable string by title-casing its segments.

This is useful for turning enum values or schema field names into labels.

Use case and result

iex> JediHelpers.atom_to_readable_string(:user_profile)
"User Profile"

iex> JediHelpers.atom_to_readable_string(:admin)
"Admin"

Formats an integer, decimal string, or Decimal with thousands separators and exactly two decimal places.

This is useful for quantities and non-currency totals in reports. Returns nil for nil and the empty string.

Use case and result

iex> JediHelpers.format_decimal(1_234_567)
"1,234,567.00"

iex> JediHelpers.format_decimal("1000.1")
"1,000.10"

iex> JediHelpers.format_decimal(nil)
nil

Formats an amount as a localized currency string using Money.

Parameters

• amount: A number representing the amount to format. Supported types:
  • Money struct (used directly)
  • Decimal (e.g., from Ecto fields)
  • integer (treated as whole currency units)
  • float
  • string (parsed into a Money amount)
• currency: A string or atom representing the ISO 4217 currency code (e.g., :php for Philippine Peso).
• opts (optional): A keyword list of formatting options passed to Money.to_string/2.

Returns

• A formatted currency string on success.
• Raises a RuntimeError on formatting failure.
• Raises an ArgumentError for unsupported amount types.
• Returns nil if the amount is nil.

Use case and result

A billing page can format stored numeric values without first constructing a Money struct:

iex> JediHelpers.format_money(1000, :php)
"₱1,000.00"

iex> JediHelpers.format_money(nil, :php)
nil

iex> JediHelpers.format_money(Decimal.new("1234.56"), :usd)
"$1,234.56"

iex> JediHelpers.format_money("1234.56", :php)
"₱1,234.56"

Formatting Options

The opts are forwarded to Money.to_string/2.
Refer to the ex_money Money.to_string/2 documentation for the full list of supported options.

Formats a map or struct containing :first_name and :last_name as "First Last".

This is useful for user labels in tables and select controls. Returns nil when the user itself is nil.

Use case and result

iex> JediHelpers.format_name(%{first_name: "Luke", last_name: "Skywalker"})
"Luke Skywalker"

iex> JediHelpers.format_name(nil)
nil

Formats a user's name using a requested display style.

Pass :last_first for sortable directory labels. Any other style uses "First Last".

Use case and result

iex> JediHelpers.format_name(%{first_name: "Luke", last_name: "Skywalker"}, :last_first)
"Skywalker, Luke"

iex> JediHelpers.format_name(%{first_name: "Leia", last_name: "Organa"}, :default)
"Leia Organa"

Formats a user as "First Last - email@example.com".

This is useful when names alone are ambiguous in an admin select or audit screen.

Use case and result

iex> JediHelpers.format_name_with_email(%{first_name: "Leia", last_name: "Organa", email: "leia@alderaan.com"})
"Leia Organa - leia@alderaan.com"

@spec number_to_words(integer()) :: String.t()

Spells an integer in English words.

This is useful for human-readable totals on invoices, checks, and generated documents.

Use case and result

iex> JediHelpers.number_to_words(42)
"forty-two"

iex> JediHelpers.number_to_words(1001)
"one thousand and one"

@spec resource_type(struct()) :: String.t()

Returns the underscored (snake_case) name of a struct's module as a string.

This is useful when a Phoenix component or API needs a stable type identifier without the full module namespace.

Use case and result

iex> JediHelpers.resource_type(%URI{})
"uri"

Returns at most max_length characters from a resource's :description.

This is useful for compact table cells and card previews. It slices the text; it does not append an ellipsis. The default maximum is 50 characters.

Parameters

• resource: A map that must contain a non-nil, binary :description key.
• max_length: The maximum length of the trimmed description (default is 50).

Use case and result

iex> JediHelpers.trim_description(%{description: "This is a very long description that needs trimming"}, 10)
"This is a "

iex> JediHelpers.trim_description(%{description: "Short"}, 10)
"Short"

Raises

Raises ArgumentError if the resource does not contain a non-nil, binary :description field.

@spec uri_parse_path(String.t()) :: String.t() | nil

Extracts the path segment from a URI string.

This is useful when a redirect or callback stores an absolute URL but a Phoenix navigation function only needs its local path.

Use case and result

iex> JediHelpers.uri_parse_path("https://example.com/users/123?ref=home")
"/users/123"

iex> JediHelpers.uri_parse_path("https://example.com")
nil