dry-struct Documentation

While Dry::Struct looks similar to Virtus, there are key architectural differences:

• Immutability: Dry::Structs do not provide attribute writers and are intended to be used exclusively as immutable "data objects."
• Type Handling: Attribute value handling is delegated to standalone dry-types objects.
• Hash Handling: Attribute hash handling is provided by standalone hash schemas from dry-types.
• Composition: Dry::Struct classes "quack" like dry-types, meaning they can be used within hash schemas, as array members, or summed.

The Dry::Struct::Sum class allows you to define a sum type specifically composed of two or more Dry::Struct classes. Unlike Dry::Types::Sum::Constrained, this implementation prioritizes structural matching over coercion. It attempts to match the input against the 'left' type first, and if that fails, it attempts to match against the 'right' type.

You can compose these types using the pipe operator (|).

# Example of composing sum types (conceptual based on API)
# sum_type = LeftStruct | RightStruct

To use dry-struct in your Ruby project, ensure the gem is installed and require the main entrypoint. This makes the Dry::Struct namespace available for defining data structures.

require 'dry/struct'

To define a formal data object, inherit from Dry::Struct and use the attribute method to declare fields and their types. Dry::Struct objects are immutable data objects; they do not provide attribute writers.

Key characteristics:

• Immutability: Attributes are set at initialization and cannot be changed.
• Type Safety: Values are validated against the provided dry-types objects.
• Data Objects: Designed to be used exclusively as read-only data containers.

require 'dry-struct'

module Types
  include Dry.Types()
end

class Book < Dry::Struct
  attribute :title, Types::String
  attribute :subtitle, Types::String.optional
end

book = Book.new(
  title: 'Web Development with ROM and Roda',
  subtitle: nil
)

If you attempt to define the same attribute name multiple times within a single Dry::Struct definition, a Dry::Struct::RepeatedAttributeError is raised. The error message identifies the conflicting key.

Attribute :key_name has already been defined

Inheriting from Dry::Struct::Value creates a struct where the object and all its attributes are deeply frozen upon initialization. This is achieved using the ice_nine gem. While standard Dry::Struct objects are frozen, Dry::Struct::Value ensures that nested structures or objects assigned to attributes are also frozen, preventing any mutation of the internal state.

Note: Dry::Struct::Value is currently marked as deprecated in the codebase; users should check for the recommended replacement in the dry-struct deprecation notices.

class Location < Dry::Struct::Value
  attribute :lat, Types::Float
  attribute :lng, Types::Float
end

loc1 = Location.new(lat: 1.23, lng: 4.56)
loc2 = Location.new(lat: 1.23, lng: 4.56)

loc1.frozen? #=> true
loc2.frozen? #=> true
loc1 == loc2 #=> true

The === method checks if a given value matches either the left or the right side of the Dry::Struct::Sum type.

# Returns true if value matches left or right
# sum_type === value

You can compose structs by importing the schema of an existing Dry::Struct using attributes_from. This allows you to reuse attribute definitions across different classes or nest them within a block.

class Address < Dry::Struct
  attribute :city, Types::String
  attribute :country, Types::String
end

class User < Dry::Struct
  attribute :name, Types::String
  attributes_from Address
end

# Or nested:
class User < Dry::Struct
  attribute :name, Types::String
  attribute :address do
    attributes_from Address
  end
end