Class: Cuprum::Collections::Adapter

Inherits:
Object
  • Object
show all
Includes:
ResultHelpers, Steps
Defined in:
lib/cuprum/collections/adapter.rb

Overview

Utility class for converting between raw attributes and a data format.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(**options) ⇒ Adapter

Returns a new instance of Adapter.

Parameters:

  • options (Hash) —

    options for initializing the adapter.

Options Hash (**options):

  • allow_extra_attributes (true, false) —

    if false, attributes methods return an error for attributes not in attributes_names. Defaults to true if attribute_names is empty, otherwise false.

  • attributes_names (Array<String, Symbol>) —

    the valid attribute names for a data object. Defaults to [].

  • default_contract (Stannum::Constraints:Base) —

    the contract used to validate instances of the data object.

  • entity_class (Class) —

    the class of the data objects.



24
25
26
27
28
29
30
31
32
33
34
35
36
37
 
# File 'lib/cuprum/collections/adapter.rb', line 24

def initialize(**options) # rubocop:disable Metrics/MethodLength
  @attribute_names =
    options
      .fetch(:attribute_names, [])
      .compact
      .map(&:to_s)
      .then { |ary| Set.new(ary) }
  @default_contract       = options[:default_contract]
  @entity_class           = options[:entity_class]
  @allow_extra_attributes =
    options.fetch(:allow_extra_attributes, @attribute_names.empty?)

  validate_entity_class_parameter(@entity_class)
end

Instance Attribute Details

#attribute_names ⇒ Set<String> (readonly)

Returns the valid attribute names for a data object.

Returns:

  • (Set<String>) —

    the valid attribute names for a data object.



40
41
42
 
# File 'lib/cuprum/collections/adapter.rb', line 40

def attribute_names
  @attribute_names
end

#default_contract ⇒ Stannum::Constraints:Base (readonly)

Returns the contract used to validate instances of the data object.

Returns:

  • (Stannum::Constraints:Base) —

    the contract used to validate instances of the data object.



44
45
46
 
# File 'lib/cuprum/collections/adapter.rb', line 44

def default_contract
  @default_contract
end

#entity_class ⇒ Class (readonly)

Returns the class of the data objects.

Returns:

  • (Class) —

    the class of the data objects.



47
48
49
 
# File 'lib/cuprum/collections/adapter.rb', line 47

def entity_class
  @entity_class
end

Instance Method Details

#allow_extra_attributes? ⇒ true, false

Returns if false, attributes methods return an error for attributes not in attributes_names.

Returns:

  • (true, false) —

    if false, attributes methods return an error for attributes not in attributes_names.



51
52
53
 
# File 'lib/cuprum/collections/adapter.rb', line 51

def allow_extra_attributes?
  @allow_extra_attributes
end

#build(attributes:) ⇒ Cuprum::Result<Object>

Generates a data object from an attributes hash.

Parameters:

  • attributes (Hash) —

    the attributes used to initialize the object.

Returns:

  • (Cuprum::Result<Object>) —

    the result with the generated object or the error.



61
62
63
64
65
66
67
68
69
70
 
# File 'lib/cuprum/collections/adapter.rb', line 61

def build(attributes:)
  steps do
    handle_invalid_parameters(
      *validate_attributes_parameter(attributes)
    )
    handle_extra_attributes(attributes)

    build_entity(attributes:)
  end
end

#merge(attributes:, entity:) ⇒ Cuprum::Result<Object>

Returns a data object with updated attributes.

Parameters:

  • attributes (Hash) —

    the attributes used to update the object.

  • entity (Object) —

    the data object to update.

Returns:

  • (Cuprum::Result<Object>) —

    the result with the updated object or the error.



79
80
81
82
83
84
85
86
87
88
89
 
# File 'lib/cuprum/collections/adapter.rb', line 79

def merge(attributes:, entity:)
  steps do
    handle_invalid_parameters(
      *validate_attributes_parameter(attributes),
      validate_entity_parameter(entity)
    )
    handle_extra_attributes(attributes)

    merge_entity(attributes:, entity:)
  end
end

#serialize(entity:) ⇒ Cuprum::Result<Object>

Generates an attributes hash from a data object.

Parameters:

  • entity (Object) —

    the data object to serialize.

Returns:

  • (Cuprum::Result<Object>) —

    the result with the generated attributes or the error.



97
98
99
100
101
102
103
104
105
 
# File 'lib/cuprum/collections/adapter.rb', line 97

def serialize(entity:)
  steps do
    handle_invalid_parameters(
      validate_entity_parameter(entity)
    )

    serialize_entity(entity:)
  end
end

#validate(entity:, contract: nil) ⇒ Cuprum::Result<Object>

Validates a data object.

Parameters:

  • entity (Object) —

    the data object to validate.

  • contract (Stannum::Constraint) (defaults to: nil) —

    the contract used to validate the data object, if any.

Returns:

  • (Cuprum::Result<Object>) —

    a passing result with the data object, or the error if the data object is not valid.



115
116
117
118
119
120
121
122
123
 
# File 'lib/cuprum/collections/adapter.rb', line 115

def validate(entity:, contract: nil)
  steps do
    handle_invalid_parameters(
      validate_entity_parameter(entity)
    )

    validate_entity(contract:, entity:)
  end
end

#validate_attributes_parameter(attributes, as: 'attributes') ⇒ String?

Asserts that an attributes parameter is a Hash with valid keys.

Parameters:

  • attributes (Object) —

    the attributes to validate.

  • as (String) (defaults to: 'attributes') —

    the name of the validate object. Defaults to "attributes".

Returns:

  • (String, nil) —

    the error message if the attributes are not a Hash with valid keys; or nil if the attributes are valid.



133
134
135
136
137
138
139
140
141
142
143
144
145
 
# File 'lib/cuprum/collections/adapter.rb', line 133

def validate_attributes_parameter(attributes, as: 'attributes')
  return attributes_not_hash_error(as:) unless attributes.is_a?(Hash)

  attributes
    .each_key
    .with_object([]) do |key, messages|
      messages << validate_attributes_parameter_key(
        key,
        as: "#{as}[#{key.inspect}] key"
      )
    end
    .compact
end

#validate_entity_parameter(entity, as: 'entity') ⇒ String?

Asserts that an entity parameter is of valid type.

Parameters:

  • entity (Object) —

    the entity to validate.

  • as (String) (defaults to: 'entity') —

    the name of the validated object. Defaults to "entity".

Returns:

  • (String, nil) —

    the error message if the entity is not of valid type; or nil if the entity is valid.



154
155
156
157
158
159
160
161
162
163
164
 
# File 'lib/cuprum/collections/adapter.rb', line 154

def validate_entity_parameter(entity, as: 'entity')
  return unless entity_class

  return if entity.is_a?(entity_class)

  tools.assertions.error_message_for(
    'sleeping_king_studios.tools.assertions.instance_of',
    as:,
    expected: entity_class
  )
end