BitcrowdEcto.Changeset (bitcrowd_ecto v1.2.0)

View Source

Extensions for Ecto changesets.

Summary

Functions

Introspects a schema and casts all defined fields from a params map.

Validates that a field that has been changed.

Validates a date field in the changeset is after the given reference date.

Validates two date fields to be a date range, so if both are set the first field has to be before the second field. The error is placed on the later field.

Validates a field timestamp to be after the given one

Validates two datetime fields to be a time range, so if both are set the first has to be before the second field. The error is placed on the later field.

Validates that an email has valid format.

Validates a field timestamp to be in the future, if present

Validates a changeset field with hexadecimal color format

Validates that a field is not changed from its current value, unless the current value is nil.

Validates a t:Money.t value according to the given options.

Validates two fields to be a range, so if both are set the first has to be before the second field. The error is placed on the second field.

Validates a field timestamp to be in the past, if present

Validates that a field has changed in a defined way.

Validates a field url to be qualified url

Types

cast_all_option()

(since 0.1.0)
@type cast_all_option() :: {:action, atom()}

validate_email_option()

(since 0.1.0)
@type validate_email_option() ::
  {:max_length, non_neg_integer()} | {:only_web, boolean()}

validate_money_option()

(since 0.1.0)
@type validate_money_option() ::
  {:equal_to, Money.t()}
  | {:more_than, Money.t()}
  | {:less_than, Money.t()}
  | {:more_than_or_equal_to, Money.t()}
  | {:less_than_or_equal_to, Money.t()}
  | {:currency, atom()}

Functions

cast_all(schema_or_struct_or_changeset, params, opts \\ [])

(since 0.17.0)
@spec cast_all(module() | struct(), map(), [cast_all_option()]) :: Ecto.Changeset.t()

Introspects a schema and casts all defined fields from a params map.

  • Accepts a schema module or structs or changesets.
  • Can deal with embeds.

Options

  • required list of required field names
  • optional list of optional field names (= inverse set is required)

required and optional options must not be present at the same time.

Examples

iex> changeset = cast_all(TestEmbeddedSchema, %{some_field: 4})
iex> changeset.valid?
true

iex> changeset = cast_all(%TestEmbeddedSchema{}, %{some_field: 4})
iex> changeset.valid?
true

iex> changeset = cast_all(change(%TestEmbeddedSchema{}), %{some_field: 4})
iex> changeset.valid?
true

iex> changeset = cast_all(TestEmbeddedSchema, %{}, required: [:some_field])
iex> changeset.errors
[some_field: {"can't be blank", [validation: :required]}]

iex> changeset = cast_all(TestEmbeddedSchema, %{}, optional: [:some_other_field])
iex> changeset.errors
[some_field: {"can't be blank", [validation: :required]}]

validate_changed(changeset, field)

(since 0.1.0)
@spec validate_changed(Ecto.Changeset.t(), atom()) :: Ecto.Changeset.t()

Validates that a field that has been changed.

validate_date_after(changeset, date_field, ref_date, opts \\ [])

(since 0.11.0)
@spec validate_date_after(Ecto.Changeset.t(), atom(), Date.t(), [{:formatter, fun()}]) ::
  Ecto.Changeset.t()

Validates a date field in the changeset is after the given reference date.

validate_date_order(changeset, from_field, until_field, opts \\ [])

(since 0.6.0)
@spec validate_date_order(Ecto.Changeset.t(), atom(), atom(),
  formatter: fun(),
  valid_orders: [atom()]
) ::
  Ecto.Changeset.t()

Validates two date fields to be a date range, so if both are set the first field has to be before the second field. The error is placed on the later field.

Examples

validate_date_order(changeset, :from, :to)
validate_date_order(changeset, :from, :to, [valid_orders: :lt])
validate_date_order(changeset, :from, :to, [formatter: &Date.day_of_week/1])

validate_datetime_after(changeset, field, reference_datetime, opts \\ [])

(since 0.6.0)
@spec validate_datetime_after(Ecto.Changeset.t(), atom(), DateTime.t(), [
  {:formatter, fun()}
]) ::
  Ecto.Changeset.t()

Validates a field timestamp to be after the given one

validate_datetime_order(changeset, from_field, until_field, opts \\ [])

(since 0.6.0)
@spec validate_datetime_order(Ecto.Changeset.t(), atom(), atom(),
  formatter: fun(),
  valid_orders: [atom()]
) :: Ecto.Changeset.t()

Validates two datetime fields to be a time range, so if both are set the first has to be before the second field. The error is placed on the later field.

Examples

validate_datetime_order(changeset, :from, :to)
validate_datetime_order(changeset, :from, :to, [valid_orders: :lt])
validate_datetime_order(changeset, :from, :to, [formatter: &DateTime.to_time/1])

validate_email(changeset, field, opts \\ [])

(since 0.1.0)
@spec validate_email(Ecto.Changeset.t(), atom(), [validate_email_option()]) ::
  Ecto.Changeset.t()

Validates that an email has valid format.

  • Ignores nil values.

Compliance

For a good list of valid/invalid emails, see https://gist.github.com/cjaoude/fd9910626629b53c4d25

The regex used in this validator doesn't understand half of the inputs, but we don't really care for now. Validating super strange emails is not a sport we want to compete in.

Options

  • :max_length - restricts the maximum length of the input, defaults to 320
  • :only_web - requires a dot in the domain part, e.g. domain.tld, defaults to true

validate_future_datetime(changeset, field, now \\ DateTime.utc_now())

(since 0.6.0)
@spec validate_future_datetime(Ecto.Changeset.t(), atom(), DateTime.t()) ::
  Ecto.Changeset.t()

Validates a field timestamp to be in the future, if present

validate_hex_color(changeset, hex_color_field)

(since 0.11.0)
@spec validate_hex_color(Ecto.Changeset.t(), atom()) :: Ecto.Changeset.t()

Validates a changeset field with hexadecimal color format

validate_immutable(changeset, field)

(since 0.1.0)
@spec validate_immutable(Ecto.Changeset.t(), atom()) :: Ecto.Changeset.t()

Validates that a field is not changed from its current value, unless the current value is nil.

validate_money(changeset, field, opts)

(since 0.13.0)
@spec validate_money(Ecto.Changeset.t(), atom(), [validate_money_option()]) ::
  Ecto.Changeset.t() | no_return()

Validates a t:Money.t value according to the given options.

Examples

validate_money(changeset, :amount, less_than: Money.new("100.00", :USD))
validate_money(changeset, :amount, greater_than_or_equal_to: Money.new("100.00", :USD))
validate_money(changeset, :amount, currency: :USD)

validate_order(changeset, from_field, until_field, validation_key, opts \\ [])

(since 0.6.0)
@spec validate_order(Ecto.Changeset.t(), atom(), atom(), atom(),
  formatter: fun(),
  compare_fun: fun(),
  valid_orders: [atom()]
) :: Ecto.Changeset.t()

Validates two fields to be a range, so if both are set the first has to be before the second field. The error is placed on the second field.

Examples

validate_order(changeset, :from, :to, :to_is_after_from)
validate_order(changeset, :from, :to, :to_is_after_from, [compare_fun: fn a, b -> String.length(a) > String.length(b) end])
validate_order(changeset, :from, :to, :to_is_after_from, [formatter: &String.length/1])

validate_past_datetime(changeset, field, now \\ DateTime.utc_now())

(since 0.6.0)
@spec validate_past_datetime(Ecto.Changeset.t(), atom(), DateTime.t()) ::
  Ecto.Changeset.t()

Validates a field timestamp to be in the past, if present

validate_transition(changeset, field, transitions)

(since 0.1.0)
@spec validate_transition(Ecto.Changeset.t(), atom(), [{any(), any()}]) ::
  Ecto.Changeset.t()

Validates that a field has changed in a defined way.

Examples

validate_transition(changeset, field, [{"foo", "bar"}, {"foo", "yolo"}])

This marks the changeset invalid unless the value of :field is currently "foo" and is changed to "bar" or "yolo". If the field is not changed, a {state, state} transition has to be present in the list of transitions.

validate_url(changeset, field)

(since 0.1.0)
@spec validate_url(Ecto.Changeset.t(), atom()) :: Ecto.Changeset.t()

Validates a field url to be qualified url