dredd v1.3.0

Dredd (dredd v1.3.0)

Dredd judges structs; it's a validator.

Dredd was forked from Justify

Inspired heavily by Ecto.Changeset, Dredd allows you to pipe a plain map into a series of validation functions using a simple and familiar API. No schemas or casting required.

example

 Example 

dataset =
  %{email: "this_is_not_an_email"}
  |> Dredd.validate_required(:email)
  |> Dredd.validate_format(:email, ~r/S+@S+/)

dataset.errors #=> [email: {"has invalid format", validation: :format}]
dataset.valid? #=> false

Each validation function will return a Dredd.Dataset struct which can be passed into the next function. If a validation error is encountered the dataset will be marked as invalid and an error will be added to the struct.

custom-validations

 Custom Validations

You can provide your own custom validations using the Dredd.add_error/4 function.

example-1

 Example 

defmodule MyValidator do
  def validate_color(data, field, color) do
    dataset = Dredd.Dataset.new(data)

    value = Map.get(dataset.data, :field)

    if value == color do
      dataset
    else
      Dredd.add_error(dataset, field, "wrong color", validation: :color)
    end
  end
end

Your custom validation can be used as part of a validation pipeline.

example-2

 Example 

dataset =
  %{color: "brown"}
  |> Dredd.validation_required(:color)
  |> MyValidator.validate_color(:color, "green")

dataset.errors #=> [color: {"wrong color", validation: :color}]
dataset.valid? #=> false

supported-validations

 Supported Validations

Link to this section Summary

Types

type_t()

Functions

add_error(dataset, field, message, keys \\ [])

Adds an error to the dataset.

validate_acceptance(dataset, field, opts \\ [])

Validates the given field has a value of true.

validate_confirmation(dataset, field, opts \\ [])

Validates the value of a given field matches it's confirmation field.

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

Validates if the value of a given field is an email.

validate_embed(dataset, field, validator)

Applies a validator function to a field containing an embedded value.

validate_exclusion(dataset, field, enum, opts \\ [])

Validates the value for the given field is not contained within the provided enumerable.

validate_format(dataset, field, format, opts \\ [])

Validates the value of the given field matches the provided format.

validate_inclusion(dataset, field, enum, opts \\ [])

Validates the value for the given field is contained within the provided enumerable.

validate_length(dataset, field, opts)

Validates the length of a string or list.

validate_nanoid(dataset, field, opts \\ [])

Validates if the value of a given field is a UUID.binary_to_string!

validate_required(dataset, fields, opts \\ [])

Validates that one or more fields is not empty. This means they are neither the empty string "" nor they are nil.

validate_type(dataset, field, type, opts \\ [])

Validates that the value of a field is a specific type.

validate_uuid(dataset, field, opts \\ [])

Validates if the value of a given field is a UUID.binary_to_string!

Link to this section Types

Link to this type

type_t()

@type type_t() ::
  :boolean | :float | :integer | :non_neg_integer | :pos_integer | :string

Link to this section Functions

Link to this function

add_error(dataset, field, message, keys \\ [])

@spec add_error(Dredd.Dataset.t(), atom(), String.t(), Keyword.t()) ::
  Dredd.Dataset.t()

Adds an error to the dataset.

An optional keyword list can be used to provide additional contextual information about the error.

Link to this function

validate_acceptance(dataset, field, opts \\ [])

@spec validate_acceptance(map(), atom(), Keyword.t()) :: Dredd.Dataset.t()

Validates the given field has a value of true.

options

 Options

  • :message - error message, defaults to "must be accepted"
Link to this function

validate_confirmation(dataset, field, opts \\ [])

@spec validate_confirmation(map(), atom(), Keyword.t()) :: Dredd.Dataset.t()

Validates the value of a given field matches it's confirmation field.

By default, the field will be checked against a field with the same name but appended with _confirmation. It’s possible to provide a custom field by providing a value to the :confirmation_field option.

Note that if the confirmation field is nil or missing, by default, an error will not be added. You can specify that the confirmation field is required in the options (see below).

options

 Options

  • :confirmation_field - name of the field to validate against
  • :message - error message, defaults to "does not match"
  • :required? - whether the confirmation field must contain a value
Link to this function

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

@spec validate_email(map(), atom(), Keyword.t()) :: Dredd.Dataset.t()

Validates if the value of a given field is an email.

NOTE: this validator is not RFC822 compliant. If you really need to be sure, send an email to that address.

options

 Options

  • :message - error message, default to "is not a valid email address"
Link to this function

validate_embed(dataset, field, validator)

@spec validate_embed(map(), atom(), (... -> any())) :: Dredd.Dataset.t()

Applies a validator function to a field containing an embedded value.

An embedded value can be either a map or a list of maps.

example

 Example 

validator = fn(metadata) -> Dredd.validate_required(metadata, :key) end

data = %{metadata: [%{value: "a value"}]}

validate_embed(data, :metadata, validator)
#> %Dredd.Dataset{errors: [metadata: [[key: {"can't be blank", validation: :required}]]], valid?: false}
Link to this function

validate_exclusion(dataset, field, enum, opts \\ [])

@spec validate_exclusion(map(), atom(), Enum.t(), Keyword.t()) :: Dredd.Dataset.t()

Validates the value for the given field is not contained within the provided enumerable.

options

 Options

  • :message - error message, defaults to "is reserved"
Link to this function

validate_format(dataset, field, format, opts \\ [])

@spec validate_format(map(), atom(), Regex.t(), Keyword.t()) :: Dredd.Dataset.t()

Validates the value of the given field matches the provided format.

options

 Options

  • :message - error message, defaults to "has invalid format"
Link to this function

validate_inclusion(dataset, field, enum, opts \\ [])

@spec validate_inclusion(map(), atom(), Enum.t(), Keyword.t()) :: Dredd.Dataset.t()

Validates the value for the given field is contained within the provided enumerable.

options

 Options

  • :message - error message, defaults to "is invalid"
Link to this function

validate_length(dataset, field, opts)

@spec validate_length(map(), atom(), Keyword.t()) :: Dredd.Dataset.t()

Validates the length of a string or list.

options

 Options

  • :count - how to calculate the length of a string. Must be one of
           `:codepoints`, `:graphemes` or `:bytes`. Defaults to
       `:graphemes`.
  • :is - the exact length match
  • :min - match a length greater than or equal to
  • :max - match a length less than or equal to
  • :message - error message, defaults to one of the following variants:
    • for strings
      • “should be %{count} character(s)”
      • “should be at least %{count} character(s)”
      • “should be at most %{count} character(s)”
    • for binary
      • “should be %{count} byte(s)”
      • “should be at least %{count} byte(s)”
      • “should be at most %{count} byte(s)”
    • for lists
      • “should have %{count} item(s)”
      • “should have at least %{count} item(s)”
      • “should have at most %{count} item(s)”
Link to this function

validate_nanoid(dataset, field, opts \\ [])

@spec validate_nanoid(map(), atom(), Keyword.t()) :: Dredd.Dataset.t()

Validates if the value of a given field is a UUID.binary_to_string!

options

 Options

  • :message - error message, defaults to "is not a valid UUID"
Link to this function

validate_required(dataset, fields, opts \\ [])

@spec validate_required(map(), atom() | [atom()], Keyword.t()) :: Dredd.Dataset.t()

Validates that one or more fields is not empty. This means they are neither the empty string "" nor they are nil.

options

 Options

  • :message - error message, defaults to "must be accepted"
  • :trim? - remove whitespace before validating, defaults to true
Link to this function

validate_type(dataset, field, type, opts \\ [])

@spec validate_type(map(), atom(), type_t(), Keyword.t()) :: Dredd.Dataset.t()

Validates that the value of a field is a specific type.

Supported types:

  • :boolean
  • :float
  • :integer
  • :non_neg_integer
  • :pos_integer
  • :string

options

 Options

  • :message - error message, defaults to "has invalid type"
Link to this function

validate_uuid(dataset, field, opts \\ [])

@spec validate_uuid(map(), atom(), Keyword.t()) :: Dredd.Dataset.t()

Validates if the value of a given field is a UUID.binary_to_string!

options

 Options

  • :message - error message, defaults to "is not a valid UUID"