Module: Alba::Resource::InstanceMethods

Included in:
Alba::Resource
Defined in:
lib/alba/resource.rb,
sig/alba/resource.rbs

Overview

Instance methods

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#object ⇒ Object (readonly)

Returns the value of attribute object.

Returns:

  • (Object) 


47
48
49
 
# File 'lib/alba/resource.rb', line 47

def object
  @object
end

#params ⇒ generic_hash (readonly)

Returns the value of attribute params.

Returns:

  • (generic_hash) 


47
48
49
 
# File 'lib/alba/resource.rb', line 47

def params
  @params
end

Instance Method Details

#__send__ ⇒ Object

Parameters:

  • (Symbol)
  • (Object)

Returns:

  • (Object) 


62
 
# File 'sig/alba/resource.rbs', line 62

def __send__: (Symbol, *untyped) -> untyped

#_fetch_attribute_from_object_first(obj, attribute) ⇒ Object

Parameters:

  • (Object)
  • (Symbol)

Returns:

  • (Object) 


270
271
272
273
274
275
276
 
# File 'lib/alba/resource.rb', line 270

def _fetch_attribute_from_object_first(obj, attribute)
  return obj.fetch(attribute) if obj.is_a?(Hash)

  obj.__send__(attribute)
rescue NoMethodError, KeyError
  __send__(attribute, obj)
end

#_fetch_attribute_from_resource_first(obj, attribute) ⇒ Object

Parameters:

  • (Object)
  • (Symbol)

Returns:

  • (Object) 


278
279
280
281
282
283
284
285
286
287
288
 
# File 'lib/alba/resource.rb', line 278

def _fetch_attribute_from_resource_first(obj, attribute)
  return obj.fetch(attribute) if obj.is_a?(Hash)

  if @_resource_methods.include?(attribute)
    __send__(attribute, obj)
  else
    obj.__send__(attribute)
  end
rescue KeyError
  __send__(attribute, obj)
end

#_key ⇒ root_key_type

Returns:

  • (root_key_type) 


177
178
179
180
 
# File 'lib/alba/resource.rb', line 177

def _key
  k = @_key == true ? resource_name(pluralized: false) : @_key
  Alba.regularize_key(k)
end

#_key_for_collection ⇒ root_key_type

Returns:

  • (root_key_type) 


172
173
174
175
 
# File 'lib/alba/resource.rb', line 172

def _key_for_collection
  k = @_key_for_collection == true ? resource_name(pluralized: true) : @_key_for_collection
  Alba.regularize_key(k)
end

#_metadata(block, meta) ⇒ generic_hash

Parameters:

  • (Object)
  • (generic_hash)

Returns:

  • (generic_hash) 


150
151
152
 
# File 'lib/alba/resource.rb', line 150

def _metadata(block, meta)
  block ? instance_eval(&block).merge(meta) : meta
end

#_setup ⇒ void

This method returns an undefined value.



55
 
# File 'sig/alba/resource.rbs', line 55

def _setup: () -> void

#as_json(_options = EMPTY_HASH, root_key: nil, meta: EMPTY_HASH) ⇒ Hash

Returns a Hash corresponding #serialize

Parameters:

  • _options (Hash) (defaults to: EMPTY_HASH) —

    dummy parameter for Rails compatibility

  • root_key (Symbol, nil) (defaults to: nil)
  • meta (Hash) (defaults to: EMPTY_HASH) —

    metadata for this serialization

  • (generic_hash)
  • root_key: (root_key_type) (defaults to: nil)
  • meta: (generic_hash) (defaults to: EMPTY_HASH)

Returns:

  • (Hash) 


96
97
98
99
100
101
102
103
104
105
 
# File 'lib/alba/resource.rb', line 96

def as_json(_options = EMPTY_HASH, root_key: nil, meta: EMPTY_HASH)
  key = root_key.nil? ? fetch_key : root_key
  key = Alba.regularize_key(key)
  if key && !key.empty?
    h = {key => serializable_hash}
    hash_with_metadata(h, meta)
  else
    serializable_hash
  end
end

#attributes ⇒ Hash[Symbol | String, attribute]

Returns:



42
 
# File 'sig/alba/resource.rbs', line 42

def attributes: () -> Hash[Symbol | String, attribute]

#attributes_to_hash(obj, hash) ⇒ generic_hash

Parameters:

  • (Object)
  • (generic_hash)

Returns:

  • (generic_hash) 


197
198
199
200
201
202
203
204
205
206
 
# File 'lib/alba/resource.rb', line 197

def attributes_to_hash(obj, hash)
  @_attributes.each do |key, attribute|
    set_key_and_attribute_body_from(obj, key, attribute, hash)
  rescue ::Alba::Error, FrozenError, TypeError
    raise
  rescue StandardError => e
    handle_error(e, obj, key, attribute, hash)
  end
  @with_traits.nil? ? hash : hash.merge!(hash_from_traits(obj))
end

#binding ⇒ Binding

Returns:

  • (Binding) 


63
 
# File 'sig/alba/resource.rbs', line 63

def binding: () -> Binding

#check_within(association_name) ⇒ Object

Parameters:

  • (Symbol)

Returns:

  • (Object) 


299
300
301
302
303
304
305
306
307
308
309
 
# File 'lib/alba/resource.rb', line 299

def check_within(association_name)
  case @within
  when WITHIN_DEFAULT then WITHIN_DEFAULT # Default value, doesn't check within tree
  when Hash then @within.fetch(association_name, nil) # Traverse within tree
  when Array then @within.find { |item| item.to_sym == association_name }
  when Symbol then @within == association_name
  when nil, true, false then false # Stop here
  else
    raise Alba::Error, "Unknown type for within option: #{@within.class}"
  end
end

#class ⇒ Class

These methods are available on the eventual resource instance. Declaring them here models the module's inclusion context for Steep.

Returns:



59
 
# File 'sig/alba/resource.rbs', line 59

def class: () -> Class

#collection_converter ⇒ Proc

Returns:

  • (Proc) 


40
 
# File 'sig/alba/resource.rbs', line 40

def collection_converter: () -> Proc

#converter ⇒ Proc

Returns:

  • (Proc) 


39
 
# File 'sig/alba/resource.rbs', line 39

def converter: () -> Proc

#deprecated_serializable_hash ⇒ Object

Returns:

  • (Object) 


28
 
# File 'sig/alba/resource.rbs', line 28

def deprecated_serializable_hash: () -> untyped

#deprecated_serializable_hash_for_collection ⇒ Object

Returns:

  • (Object) 


33
 
# File 'sig/alba/resource.rbs', line 33

def deprecated_serializable_hash_for_collection: () -> untyped

#do_select(key, value, attribute) ⇒ Boolean

Parameters:

  • (Object)
  • (Object)
  • (Object)

Returns:

  • (Boolean) 


223
224
225
226
227
228
 
# File 'lib/alba/resource.rb', line 223

def do_select(key, value, attribute)
  # `select` can be overridden with both 2 and 3 parameters
  # Here we check the arity and build arguments accordingly
  args = @_select_arity == 3 ? [key, value, attribute] : [key, value]
  select(*args)
end

#encode ⇒ String

Parameters:

  • (Object)

Returns:

  • (String) 


64
 
# File 'sig/alba/resource.rbs', line 64

def encode: (untyped) -> String

#fetch_attribute(obj, key, attribute) ⇒ Object

rubocop:disable Metrics

Parameters:

Returns:

  • (Object) 


251
252
253
254
255
256
257
258
259
260
261
262
263
264
 
# File 'lib/alba/resource.rb', line 251

def fetch_attribute(obj, key, attribute) # rubocop:disable Metrics
  value = case attribute
          when Symbol then fetch_attribute_from_object_and_resource(obj, attribute)
          when Proc then instance_exec(obj, &attribute)
          when Alba::Association then yield_if_within(attribute.name.to_sym) { |within| attribute.to_h(obj, params: params, within: within) }
          when TypedAttribute then attribute.value(object: obj) { |attr| fetch_attribute(obj, key, attr) }
          when NestedAttribute then attribute.value(object: obj, params: params, within: @within)
          when ConditionalAttribute then attribute.with_passing_condition(resource: self, object: obj) { |attr| fetch_attribute(obj, key, attr) }
            # :nocov:
          else raise ::Alba::Error, "Unsupported type of attribute: #{attribute.class}"
            # :nocov:
          end
  nil_handler && value.nil? ? instance_exec(obj, key, attribute, &nil_handler) : value
end

#fetch_attribute_from_object_and_resource(obj, attribute) ⇒ Object

Parameters:

  • (Object)
  • (Symbol)

Returns:

  • (Object) 


266
267
268
 
# File 'lib/alba/resource.rb', line 266

def fetch_attribute_from_object_and_resource(obj, attribute)
  _fetch_attribute_from_resource_first(obj, attribute)
end

#fetch_key ⇒ String

Returns:

  • (String) 


167
168
169
170
 
# File 'lib/alba/resource.rb', line 167

def fetch_key
  k = Alba.collection?(@object) ? _key_for_collection : _key
  transforming_root_key? ? transform_key(k) : k
end

#handle_error(error, obj, key, attribute, hash) ⇒ Object

Parameters:

  • (StandardError)
  • (Object)
  • (Symbol, String)
  • (attribute)
  • (generic_hash)

Returns:

  • (Object) 


230
231
232
233
234
235
236
237
238
239
240
241
242
243
 
# File 'lib/alba/resource.rb', line 230

def handle_error(error, obj, key, attribute, hash)
  case (on_error = @_on_error || :raise)
  when :raise, nil then raise(error)
  when :nullify then hash[key] = nil
  when :ignore then nil
  when Proc
    key, value = on_error.call(error, obj, key, attribute, self.class)
    hash[key] = value unless Alba::REMOVE_KEY == key # rubocop:disable Style/YodaCondition
  else
    # :nocov:
    raise Alba::Error, 'Impossible path'
    # :nocov:
  end
end

#hash_from_traits(obj) ⇒ Object

Parameters:

  • (Object)

Returns:

  • (Object) 


117
118
119
120
121
122
123
124
125
126
127
128
 
# File 'lib/alba/resource.rb', line 117

def hash_from_traits(obj)
  return {} if @with_traits.nil?

  Array(@with_traits).each_with_object({}) do |trait, hash|
    body = @_traits.fetch(trait) { raise Alba::Error, "Trait not found: #{trait}" }
    resource_class = Class.new(self.class)
    resource_class.instance_variable_set(:@_attributes, {})
    resource_class.class_eval(&body)
    resource_class.transform_keys(@_transform_type) unless @_transform_type == :none
    hash.merge!(resource_class.new(obj, params: params, within: @within).serializable_hash)
  end
end

#hash_with_metadata(hash, meta) ⇒ Object

Parameters:

  • (Object)
  • (generic_hash)

Returns:

  • (Object) 


137
138
139
140
141
142
143
144
145
146
147
148
 
# File 'lib/alba/resource.rb', line 137

def hash_with_metadata(hash, meta)
  return hash if meta.empty? && @_meta&.last.nil?

  key, block = @_meta || :meta

  if key
    hash[key] = _metadata(block, meta)
  else
    _metadata(block, meta).each { |k, v| hash[k] = v }
  end
  hash
end

#initialize(object, params: EMPTY_HASH, within: WITHIN_DEFAULT, with_traits: nil, select: nil) ⇒ InstanceMethods

Returns a new instance of InstanceMethods.

Parameters:

  • object (Object) —

    the object to be serialized

  • params (Hash) (defaults to: EMPTY_HASH) —

    user-given Hash for arbitrary data

  • within (Alba::WITHIN_DEFAULT, Hash, Array, nil, false, true) (defaults to: WITHIN_DEFAULT) —

    determines what associations to be serialized. If not set, it serializes all associations.

  • with_traits (Symbol, Array<Symbol>, nil) (defaults to: nil) —

    specified traits

  • select (Method) (defaults to: nil) —

    DEPRECATED noop

  • (Object)
  • params: (generic_hash) (defaults to: EMPTY_HASH)
  • within: (Object) (defaults to: WITHIN_DEFAULT)
  • with_traits: (Symbol, Array[Symbol], nil) (defaults to: nil)
  • select: (Method, nil) (defaults to: nil)

Returns:



55
56
57
58
59
60
61
62
 
# File 'lib/alba/resource.rb', line 55

def initialize(object, params: EMPTY_HASH, within: WITHIN_DEFAULT, with_traits: nil, select: nil)
  @object = object
  @params = params
  @within = within
  @with_traits = with_traits
  warn '`select` keyword for Alba::Resource is deprecated', category: :deprecated, uplevel: 1 if select
  _setup
end

#instance_eval ⇒ void

This method returns an undefined value.



60
 
# File 'sig/alba/resource.rbs', line 60

def instance_eval: [A] () { () [self: self] -> A } -> A

#instance_exec ⇒ void

This method returns an undefined value.



61
 
# File 'sig/alba/resource.rbs', line 61

def instance_exec: [A] (*untyped) { (*untyped) [self: self] -> A } -> A

#nil_handler ⇒ Object

Returns:

  • (Object) 


290
291
292
 
# File 'lib/alba/resource.rb', line 290

def nil_handler
  @_on_nil
end

#resource_name(pluralized: false) ⇒ String

Parameters:

  • pluralized: (Boolean) (defaults to: false)

Returns:

  • (String)

Raises:



182
183
184
185
186
187
188
189
190
191
 
# File 'lib/alba/resource.rb', line 182

def resource_name(pluralized: false)
  inflector = Alba.inflector
  raise Alba::Error, 'You must set inflector when setting root key as true.' unless inflector

  class_name = self.class.name
  suffix = class_name.end_with?('Resource') ? 'Resource' : 'Serializer'
  name = inflector.demodulize(class_name).delete_suffix(suffix)
  underscore_name = inflector.underscore(name)
  pluralized ? inflector.pluralize(underscore_name) : underscore_name
end

#select(_key, _value, _attribute) ⇒ Boolean

Default implementation for selecting attributes Override this method to filter attributes based on key and value

Parameters:

  • (Object)
  • (Object)
  • (Object)

Returns:

  • (Boolean) 


210
211
212
 
# File 'lib/alba/resource.rb', line 210

def select(_key, _value, _attribute)
  true
end

#serializable_hash ⇒ Hash Also known as: to_h

A Hash for serialization

Returns:

  • (Hash) 


110
111
112
 
# File 'lib/alba/resource.rb', line 110

def serializable_hash
  Alba.collection?(@object) ? serializable_hash_for_collection : attributes_to_hash(@object, {})
end

#serializable_hash_for_collection ⇒ Object

Returns:

  • (Object) 


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

def serializable_hash_for_collection
  if @_collection_key
    @object.to_h do |item|
      k = item.public_send(@_collection_key)
      key = Alba.regularize_key(k)
      [key, attributes_to_hash(item, {})]
    end
  else
    @object.map { |obj| attributes_to_hash(obj, {}) }
  end
end

#serialize(root_key: nil, meta: EMPTY_HASH) ⇒ String

Serialize object into JSON string

Parameters:

  • root_key (Symbol, nil) (defaults to: nil)
  • meta (Hash) (defaults to: EMPTY_HASH) —

    metadata for this serialization

  • root_key: (root_key_type) (defaults to: nil)
  • meta: (generic_hash) (defaults to: EMPTY_HASH)

Returns:

  • (String) —

    serialized JSON string



69
70
71
 
# File 'lib/alba/resource.rb', line 69

def serialize(root_key: nil, meta: EMPTY_HASH)
  serialize_with(as_json(root_key: root_key, meta: meta))
end

#serialize_with(hash) ⇒ String

Parameters:

  • (Object)

Returns:

  • (String) 


130
131
132
133
134
135
 
# File 'lib/alba/resource.rb', line 130

def serialize_with(hash)
  serialized_json = encode(hash)
  return serialized_json unless @_layout

  @_layout.serialize(resource: self, serialized_json: serialized_json, binding: binding)
end

#set_key_and_attribute_body_from(obj, key, attribute, hash) ⇒ Object

Parameters:

  • (Object)
  • (Object)
  • (attribute)
  • (generic_hash)

Returns:

  • (Object) 


214
215
216
217
218
219
220
221
 
# File 'lib/alba/resource.rb', line 214

def set_key_and_attribute_body_from(obj, key, attribute, hash)
  key = transform_key(key)
  value = fetch_attribute(obj, key, attribute)
  # When `select` is not overridden, skip calling it for better performance
  return if !@_select_arity.nil? && !do_select(key, value, attribute)

  hash[key] = value unless Alba::REMOVE_KEY == value # rubocop:disable Style/YodaCondition
end

#to_json(options = EMPTY_HASH, root_key: nil, meta: EMPTY_HASH) ⇒ String

For Rails compatibility The first options is a dummy parameter

Parameters:

  • (generic_hash)
  • root_key: (root_key_type) (defaults to: nil)
  • meta: (generic_hash) (defaults to: EMPTY_HASH)

Returns:

  • (String)

See Also:



78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/alba/resource.rb', line 78

def to_json(options = EMPTY_HASH, root_key: nil, meta: EMPTY_HASH)
  confusing_keys = [:only, :except]
  confusing_options = options.keys.select { |k| confusing_keys.include?(k.to_sym) }
  unless confusing_options.empty?
    confusing_options.sort!
    confusing_options.map! { |s| "\"#{s}\"" }
    message = "You passed #{confusing_options.join(' and ')} options but ignored. Please refer to the document: https://github.com/okuramasafumi/alba/blob/main/docs/rails.md"
    Kernel.warn(message)
  end
  serialize(root_key: root_key, meta: meta)
end

#transform_key(key) ⇒ Object

Parameters:

  • (Object)

Returns:

  • (Object) 


245
246
247
248
249
 
# File 'lib/alba/resource.rb', line 245

def transform_key(key)
  return Alba.regularize_key(key) if @_transform_type == :none || key.nil? || key.empty? # We can skip transformation

  Alba.transform_key(key, transform_type: @_transform_type)
end

#transforming_root_key? ⇒ Boolean

Returns:

  • (Boolean) 


193
194
195
 
# File 'lib/alba/resource.rb', line 193

def transforming_root_key?
  @_transforming_root_key
end

#yield_if_within(association_name) {|arg0| ... } ⇒ Object

Parameters:

  • (Symbol)

Yields:

Yield Parameters:

  • arg0 (Object)

Yield Returns:

  • (Object)

Returns:

  • (Object) 


294
295
296
297
 
# File 'lib/alba/resource.rb', line 294

def yield_if_within(association_name)
  within = check_within(association_name)
  within ? yield(within) : Alba::REMOVE_KEY
end