Dredd (dredd v2.0.2)

Dredd judges data for you. It's a validator for a wide range of datastructures.

See the README for a detailed guide.

Summary

Functions

This is a convenience function in case you want to write your own validators. It will set the valid? flag of the given Dredd.Dataset to false. It will also create a Dredd.SingleError structure with the given values and assing it to the error field of the Dredd.Dataset.

Validates the given values binaries. Optionally also validates the length of the binary either .

Validates the given values is of type boolean. Optionally also validates against a specific boolean value.

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

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

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

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

Applies a validator function to a each element of a list contained in a field.

Validates the structure of a Map, Keyword List, Struct or anything else that supports the Access behaviour and whose structure can be represented by a map.

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

Validates that the value of a field is a number.

Validates the given values is of type string. Optionally also validates the length of the string either as codepoints or graphemes.

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

Types

Link to this type

field_spec()

@type field_spec() :: single_validator_fun() | {:optional, single_validator_fun()}
@type number_t() :: :float | :integer | :non_neg_integer | :pos_integer
Link to this type

single_validator_fun()

@type single_validator_fun() :: (any() -> Dredd.Dataset.t())
Link to this type

validator_map()

@type validator_map() :: %{required(any()) => field_spec()}

Functions

Link to this function

set_single_error(dataset, message, validator, metadata \\ %{})

@spec set_single_error(Dredd.Dataset.t(), String.t(), atom(), map()) ::
  Dredd.Dataset.t()

This is a convenience function in case you want to write your own validators. It will set the valid? flag of the given Dredd.Dataset to false. It will also create a Dredd.SingleError structure with the given values and assing it to the error field of the Dredd.Dataset.

Link to this function

validate_binary(dataset, opts \\ [])

@spec validate_binary(any(), Keyword.t()) :: Dredd.Dataset.t()

Validates the given values binaries. Optionally also validates the length of the binary either .

Options

  • :is - exact required length of a binary
  • :min - minimal required length of a binary (should not be used together with is)
  • :max - maximal allowed length of a binary (should not be used together with is)
  • :type_message - error message in case the type is wrong; defaults to "is not a binary"
  • :is_message - error message in case the exact length is wrong defaults to "should be %{count} bytes(s)"
  • :min_message - error message in case the length is too short defaults to "should be at least %{count} bytes(s)"
  • :max_message - error message in case the length is too long defaults to "should be at "should be at most %{count} bytes(s)"
Link to this function

validate_boolean(dataset, opts \\ [])

@spec validate_boolean(any(), Keyword.t()) :: Dredd.Dataset.t()

Validates the given values is of type boolean. Optionally also validates against a specific boolean value.

Options

  • :is - the expected value (true|false)
  • :wrong_type_message - error message, defaults to "is not a boolean"
  • :wrong_value_message - error message, defaults to "expected value: %{expected}"

Examples

Simple case with data of invalid type:

iex> Dredd.validate_boolean('foo')
%Dredd.Dataset{
  data: 'foo',
  error: %Dredd.SingleError{
    validator: :boolean,
    message: "is not a boolean",
    metadata: %{kind: :type}
  },
  valid?: false
}

Simple case with valid boolean type:

iex> Dredd.validate_boolean(true)
%Dredd.Dataset{data: true, error: nil, valid?: true}

Special invalid case with optional expected value:

iex> Dredd.validate_boolean(false, is: true)
%Dredd.Dataset{
  data: false,
  error: %Dredd.SingleError{
    validator: :boolean,
    message: "expected value: %{expected}",
    metadata: %{expected: true, kind: :value}
  },
  valid?: false
}
Link to this function

validate_email(dataset, opts \\ [])

@spec validate_email(any(), 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

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

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

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

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

Options

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

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

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

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

Options

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

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

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

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

Options

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

validate_list(dataset, validator, opts \\ [])

@spec validate_list(any(), single_validator_fun(), Keyword.t()) :: Dredd.Dataset.t()

Applies a validator function to a each element of a list contained in a field.

Options

  • :is - exact required length of a list
  • :min - minimal required length of a list (should not be used together with is)
  • :max - maximal allowed length of a list (should not be used together with is)
  • :type_message - error message in case the type is wrong; defaults to "is not a list"
  • :is_message - error message in case the exact length is wrong defaults to "should be %{count} item(s)"
  • :min_message - error message in case the length is too short defaults to "should be at least %{count} item(s)"
  • :max_message - error message in case the length is too long defaults to "should be at "should be at most %{count} item(s)"

Example

Link to this function

validate_map(dataset, validator_map, opts \\ [])

@spec validate_map(any(), validator_map(), Keyword.t()) :: Dredd.Dataset.t()

Validates the structure of a Map, Keyword List, Struct or anything else that supports the Access behaviour and whose structure can be represented by a map.

Options

  • message - error message in case the type-check fails defaults to: "is not a map"

Example

iex> value = %{ field_a: 10, field_b: "foo" }
%{field_a: 10, field_b: "foo"}
iex> validator_map = %{
...>   field_a: &Dredd.validate_string/1,
...>   field_b: fn data -> Dredd.validate_number(data, :integer) end
...>}
iex> Dredd.validate_map(value, validator_map)
%Dredd.Dataset{
  data: %{field_a: 10, field_b: "foo"},
  error: %Dredd.MapErrors{
    validator: :map,
    errors: %{
      field_a: %Dredd.SingleError{
        validator: :string,
        message: "is not a string",
        metadata: %{kind: :type}
      },
      field_b: %Dredd.SingleError{
        validator: :number,
        message: "has incorrect numerical type",
        metadata: %{kind: :integer}
      }
    }
  },
  valid?: false
}
Link to this function

validate_nanoid(dataset, opts \\ [])

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

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

Options

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

validate_number(dataset, type, opts \\ [])

@spec validate_number(any(), number_t(), Keyword.t()) :: Dredd.Dataset.t()

Validates that the value of a field is a number.

Supported types:

  • :float
  • :integer
  • :non_neg_integer
  • :pos_integer

Options

  • ´predicate- function of type(any -> boolean)*:type_message- error message in case the type is wrong. Defaults to "has incorrect numerical type" *:predicate_message` - error message in case the predicate check fails. Defaults to "violates the given predicate"
Link to this function

validate_string(dataset, opts \\ [])

@spec validate_string(any(), Keyword.t()) :: Dredd.Dataset.t()

Validates the given values is of type string. Optionally also validates the length of the string either as codepoints or graphemes.

Options

  • :is - exact required length of a string
  • :min - minimal required length of a string (should not be used together with is)
  • :max - maximal allowed length of a string (should not be used together with is)
  • :count - can be :codepoints or :graphemes. Defaults to :graphemes
  • :type_message - error message in case the type is wrong; defaults to "is not a string"
  • :is_message - error message in case the exact length is wrong defaults to "should be %{count} character(s)"
  • :min_message - error message in case the length is too short defaults to "should be at least %{count} character(s)"
  • :max_message - error message in case the length is too long defaults to "should be at "should be at most %{count} character(s)"

Examples

Here's a simple data with invalid data:

iex> Dredd.validate_string(10)
%Dredd.Dataset{
  data: 10,
  error: %Dredd.SingleError{
    validator: :string,
    message: "is not a string",
    metadata: %{kind: :type}
  },
  valid?: false
}

Here's an example with a string that is too short but has a length requirement:

iex> Dredd.validate_string("", min_length: 5)
%Dredd.Dataset{
  data: "",
  error: %Dredd.SingleError{
    validator: :string,
    message: "should be at least %{count} character(s)",
    metadata: %{count: 5, kind: :min_length}
  },
  valid?: false
}
Link to this function

validate_uuid(dataset, opts \\ [])

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

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

Options

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