dry-types

The Dry::Types::Array::Member class is used to define an array type where every element must conform to a specific member type. When using this type, the member type is applied to each element during coercion or validation.

Key behaviors:

• Coercion: Each element in the input array is passed through the defined member type.
• Lax Mode: You can create a lax version of a member array, which allows for more permissive coercion of the individual elements.
• Try: The try method allows for safe processing of the array, returning a success result if all elements conform, or a failure result if any element fails or if the input is not an array.

# Note: While the class is internal, it is used via the public Array API
# to define types like:
# Types::Array(Integer)

The Dry::Types::Coercions::Params module provides specialized coercion logic designed for handling inputs typically found in web parameters (like strings from forms or URL queries). These methods handle common edge cases such as converting empty strings to nil, empty arrays, or empty hashes, and interpreting various truthy/falsy string representations.

All coercion methods in this module support an optional block. If the coercion fails, the block is yielded, allowing you to define custom fallback behavior instead of raising a CoercionError.

You can create a dedicated module for your types by including Dry.Types. This allows you to organize types into namespaces (like :strict, :coercible, or :nominal) and makes them available as constants within that module. This is the standard way to set up a type registry for use in your application.

When you include Dry.Types, the resulting module will contain constants for the types registered in the underlying container, such as Integer, String, Bool, etc., categorized under the namespaces you specified.

module Types
  include Dry.Types(:strict, :coercible, :nominal, default: :strict)
end

# Now you can access types via constants
Types::Strict::Integer
Types::Coercible::String

The use_namespaced_optionals setting controls how the .optional method behaves when called on a type within a namespace (like params).

• When false (default): .optional uses Types['nil'].
• When true: .optional uses Types['params.nil']. This allows empty strings to be treated as nil specifically within parameter types.

When using the direct call syntax type.(input) on a Map type, validation failures will raise a Dry::Types::MapError. This error occurs if:

• A key does not match the key_type.
• A value does not match the value_type.
• A key is duplicated after coercion.
• The input itself is not a valid hash primitive.

To avoid exceptions and instead handle failures gracefully, use the .try method, which returns a result object.

type = Dry::Types['hash'].map(Dry::Types['integer'], Dry::Types['string'])

result = type.try('not_an_int' => 'value')
if result.failure?
  puts result.error
end

Use Array(type) to create a strict array type where every element must match the provided type. This is a shortcut for Array#of.

Types::Strings = Types.Array(Types::String)

Use Dry::Types.define_builder to add new methods to all types. This is useful for creating reusable type transformations or aliases that can be chained onto existing types.

# Define a custom builder method :or_nil
Dry::Types.define_builder(:or_nil) do |type|
  type.optional.fallback(nil)
end

# Now you can use .or_nil on any type
Dry::Types['integer'].or_nil.("foo") # => nil

# Example: fallback alias
Dry::Types.define_builder(:or) do |type, fallback|
  type.fallback(fallback)
end

Dry::Types['integer'].or(100).("foo") # => 100

You can wrap an existing type with additional validation rules using the constrained method. This method allows you to pass nullary rules (rules that don't require arguments, like :odd) and unary rules (rules that require arguments, like gt: 0). The resulting object is a Dry::Types::Constrained instance that only validates input if it first satisfies the base type and then satisfies the provided rules.

Note: Constraints are not applied to lax versions of types; calling .lax on a constrained type will unwrap it to the underlying lax type.

# Example of applying constraints
# Assuming 'Integer' is a base type and ':odd' is a nullary rule
constrained_type = Integer.constrained(:odd)

constrained_type[1]
# => 1

constrained_type[2]
# => raises ConstraintError (or returns failure depending on usage)

The to_int method converts an input to an Integer. If the input is a String, it uses base 10 for conversion. It handles ArgumentError and TypeError by wrapping them in a CoercionError.

Dry::Types::Coercions::Params.to_int("123") # => 123
Dry::Types::Coercions::Params.to_int(123) # => 123

The Dry::Types::Coercions module provides utility functions for converting various input types into standard Ruby objects. These functions are commonly used by the built-in Params and JSON type sets.

When a coercion fails (e.g., an invalid date string), these methods catch the underlying error (like ArgumentError) and pass it to CoercionError.handle. If a block is provided to the method, the block is yielded to handle the error or provide a fallback value.

# Example of using coercion logic (conceptually via Dry::Types)
# These methods are typically used within type definitions.

# to_date(input, &block)
# to_date_time(input, &block)
# to_time(input, &block)
# to_symbol(input, &block)