Module: Alba::Resource::ClassMethods

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

Overview

Class methods added when Resource is included

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#_attributes ⇒ generic_hash

Internal attribute accessors

Returns:

  • (generic_hash) 


141
142
143
 
# File 'sig/alba/resource.rbs', line 141

def _attributes
  @_attributes
end

#_collection_key ⇒ Alba::key_type

Returns the value of attribute _collection_key.

Returns:

  • (Alba::key_type) 


151
152
153
 
# File 'sig/alba/resource.rbs', line 151

def _collection_key
  @_collection_key
end

#_helper ⇒ Module?

Returns the value of attribute _helper.

Returns:

  • (Module, nil) 


152
153
154
 
# File 'sig/alba/resource.rbs', line 152

def _helper
  @_helper
end

#_key ⇒ Alba::key_type

Returns the value of attribute _key.

Returns:

  • (Alba::key_type) 


142
143
144
 
# File 'sig/alba/resource.rbs', line 142

def _key
  @_key
end

#_key_for_collection ⇒ Alba::key_type

Returns the value of attribute _key_for_collection.

Returns:

  • (Alba::key_type) 


143
144
145
 
# File 'sig/alba/resource.rbs', line 143

def _key_for_collection
  @_key_for_collection
end

#_key_transformation_cascade ⇒ Boolean

Returns the value of attribute _key_transformation_cascade.

Returns:

  • (Boolean) 


147
148
149
 
# File 'sig/alba/resource.rbs', line 147

def _key_transformation_cascade
  @_key_transformation_cascade
end

#_layout ⇒ Object

Returns the value of attribute _layout.

Returns:

  • (Object) 


150
151
152
 
# File 'sig/alba/resource.rbs', line 150

def _layout
  @_layout
end

#_meta ⇒ Object

Returns the value of attribute _meta.

Returns:

  • (Object) 


144
145
146
 
# File 'sig/alba/resource.rbs', line 144

def _meta
  @_meta
end

#_on_error ⇒ Symbol?

Returns the value of attribute _on_error.

Returns:

  • (Symbol, nil) 


148
149
150
 
# File 'sig/alba/resource.rbs', line 148

def _on_error
  @_on_error
end

#_on_nil ⇒ Symbol?

Returns the value of attribute _on_nil.

Returns:

  • (Symbol, nil) 


149
150
151
 
# File 'sig/alba/resource.rbs', line 149

def _on_nil
  @_on_nil
end

#_resource_methods ⇒ Array[Symbol]

Returns the value of attribute _resource_methods.

Returns:

  • (Array[Symbol]) 


153
154
155
 
# File 'sig/alba/resource.rbs', line 153

def _resource_methods
  @_resource_methods
end

#_select_arity ⇒ Integer?

Returns the value of attribute _select_arity.

Returns:

  • (Integer, nil) 


154
155
156
 
# File 'sig/alba/resource.rbs', line 154

def _select_arity
  @_select_arity
end

#_traits ⇒ Hash[Symbol, untyped]

Returns the value of attribute _traits.

Returns:

  • (Hash[Symbol, untyped]) 


155
156
157
 
# File 'sig/alba/resource.rbs', line 155

def _traits
  @_traits
end

#_transform_type ⇒ Alba::transform_type

Returns the value of attribute _transform_type.

Returns:

  • (Alba::transform_type) 


145
146
147
 
# File 'sig/alba/resource.rbs', line 145

def _transform_type
  @_transform_type
end

#_transforming_root_key ⇒ Boolean

Returns the value of attribute _transforming_root_key.

Returns:

  • (Boolean) 


146
147
148
 
# File 'sig/alba/resource.rbs', line 146

def _transforming_root_key
  @_transforming_root_key
end

Instance Method Details

#association(name, condition = nil, resource: nil, serializer: nil, source: nil, key: nil, with_traits: nil, params: EMPTY_HASH, **options, &block) ⇒ Object Also known as: one, many, has_one, has_many

Association DSL methods



455
456
457
458
459
460
461
462
463
464
 
# File 'lib/alba/resource.rb', line 455

def association(name, condition = nil, resource: nil, serializer: nil, source: nil, key: nil, with_traits: nil, params: EMPTY_HASH, **options, &block)
  resource ||= serializer
  transformation = @_key_transformation_cascade ? @_transform_type : :none
  assoc = Association.new(
    name: name, condition: condition, resource: resource, source: source, with_traits: with_traits,
    params: params, nesting: nesting, key_transformation: transformation, helper: @_helper,
    &block
  )
  @_attributes[key&.to_sym || name.to_sym] = options[:if] ? ConditionalAttribute.new(body: assoc, condition: options[:if]) : assoc
end

#attribute(name = nil, if: nil, **name_with_type, &block) ⇒ void

This method returns an undefined value.

Set an attribute with the given block

Parameters:

  • name (String, Symbol) (defaults to: nil) —

    key name

  • if (Proc) (defaults to: nil) —

    condition to decide if it should serialize these attributes

  • block (Block) —

    the block called during serialization

  • opts (Object)

Raises:

  • (ArgumentError) —

    if block is absent



425
426
427
428
429
430
431
432
433
434
435
436
 
# File 'lib/alba/resource.rb', line 425

def attribute(name = nil, if: nil, **name_with_type, &block)
  if_value = binding.local_variable_get(:if)
  raise ArgumentError, 'No block given in attribute method' unless block
  raise ArgumentError, 'You must specify either name or name with type' if name.nil? && name_with_type.empty?

  if name.nil?
    assign_attributes_with_types(name_with_type, if_value, &block)
  else # Symbol
    attr = if_value ? ConditionalAttribute.new(body: block, condition: if_value) : block
    @_attributes[name.to_sym] = attr
  end
end

#attributes(*attrs, if: nil, **attrs_with_types) ⇒ void

This method returns an undefined value.

DSL Methods for defining attributes

Parameters:

  • attrs (Symbol, String)
  • if: (Proc, Symbol, nil) (defaults to: nil)
  • opts (Object) 


392
393
394
395
396
 
# File 'lib/alba/resource.rb', line 392

def attributes(*attrs, if: nil, **attrs_with_types)
  if_value = binding.local_variable_get(:if)
  assign_attributes(attrs, if_value)
  assign_attributes_with_types(attrs_with_types, if_value)
end

#belongs_to ⇒ Object 



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

def belongs_to: (

#collection_key(key) ⇒ void

This method returns an undefined value.

Sets key for collection serialization

Parameters:

  • key (String, Symbol) 


594
595
596
 
# File 'lib/alba/resource.rb', line 594

def collection_key(key)
  @_collection_key = key.to_sym
end

#helper(mod = @_helper || Module.new, &block) ⇒ void

This method returns an undefined value.

Helper methods

Parameters:

  • helper_module (Module) 


634
635
636
637
638
639
 
# File 'lib/alba/resource.rb', line 634

def helper(mod = @_helper || Module.new, &block)
  mod.module_eval(&block) if block
  extend mod

  @_helper = mod
end

#ignoring { ... } ⇒ void

This method returns an undefined value.

Ignoring attributes

Parameters:

  • attr (Symbol, String)

Yields:

Yield Returns:

  • (void) 


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

def ignoring: (Symbol | String attr) { () -> void } -> void

#inherited(subclass) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



378
379
380
381
 
# File 'lib/alba/resource.rb', line 378

def inherited(subclass)
  super
  INTERNAL_VARIABLES.each_key { |name| subclass.instance_variable_set(:"@#{name}", instance_variable_get(:"@#{name}").clone) }
end

#layout(file: nil, inline: nil) ⇒ void

This method returns an undefined value.

Set layout

Parameters:

  • file (String) (defaults to: nil) —

    name of the layout file

  • inline (Proc) (defaults to: nil) —

    a proc returning JSON string or a Hash representing JSON

  • file: (String, nil) (defaults to: nil)
  • inline: (Proc, nil) (defaults to: nil) 


548
549
550
 
# File 'lib/alba/resource.rb', line 548

def layout(file: nil, inline: nil)
  @_layout = Layout.new(file: file, inline: inline)
end

#meta(key = :meta, &block) ⇒ void

This method returns an undefined value.

Meta and params

Parameters:

  • meta (Symbol, Proc, nil) 


539
540
541
 
# File 'lib/alba/resource.rb', line 539

def meta(key = :meta, &block)
  @_meta = [key, block]
end

#method_added(method_name) ⇒ Object

This method_added is used for defining "resource methods"



357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
 
# File 'lib/alba/resource.rb', line 357

def method_added(method_name) # rubocop:disable Metrics/MethodLength
  case method_name
  when :collection_converter, :converter
    warn "Defining ##{method_name} methods is deprecated", category: :deprecated, uplevel: 1
    alias_method :serializable_hash_for_collection, :deprecated_serializable_hash_for_collection
    private(:serializable_hash_for_collection)
    alias_method :serializable_hash, :deprecated_serializable_hash
    alias_method :to_h, :deprecated_serializable_hash
  when :attributes
    warn 'Overriding `attributes` is deprecated, use `select` instead.', category: :deprecated, uplevel: 1
  when :select
    @_select_arity = instance_method(:select).arity
  when :_setup # noop
  else
    _resource_methods << method_name.to_sym
  end

  super
end

#nested_attribute(name, **options) { ... } ⇒ void Also known as: nested

This method returns an undefined value.

Nested attributes

Parameters:

  • name (Symbol, String)
  • opts (Object)

Yields:

Yield Returns:

  • (void) 


487
488
489
490
491
492
493
 
# File 'lib/alba/resource.rb', line 487

def nested_attribute(name, **options, &block)
  raise ArgumentError, 'No block given in attribute method' unless block

  key_transformation = @_key_transformation_cascade ? @_transform_type : :none
  attribute = NestedAttribute.new(key_transformation: key_transformation, &block)
  @_attributes[name.to_sym] = options[:if] ? ConditionalAttribute.new(body: attribute, condition: options[:if]) : attribute
end

#on_error(handler = nil, &block) ⇒ void

This method returns an undefined value.

Set error handler If this is set it's used as a error handler overriding global one

Parameters:

  • handler (Symbol) (defaults to: nil) —

    :raise, :ignore or :nullify

  • block (Block)

Raises:

  • (ArgumentError) 


604
605
606
607
608
609
 
# File 'lib/alba/resource.rb', line 604

def on_error(handler = nil, &block)
  raise ArgumentError, 'You cannot specify error handler with both Symbol and block' if handler && block
  raise ArgumentError, 'You must specify error handler with either Symbol or block' unless handler || block

  @_on_error = block || validated_error_handler(handler)
end

#on_nil(&block) ⇒ void

This method returns an undefined value.

Set nil handler

Parameters:

  • block (Block)
  • handler (:ignore, nil) 


626
627
628
 
# File 'lib/alba/resource.rb', line 626

def on_nil(&block)
  @_on_nil = block
end

#prefer_object_method! ⇒ void

This method returns an undefined value.

DSL for alias, purely for readability



649
650
651
 
# File 'lib/alba/resource.rb', line 649

def prefer_object_method!
  alias_method :fetch_attribute_from_object_and_resource, :_fetch_attribute_from_object_first
end

#prefer_resource_method! ⇒ void

This method returns an undefined value.

DSL for alias, purely for readability



643
644
645
 
# File 'lib/alba/resource.rb', line 643

def prefer_resource_method!
  alias_method :fetch_attribute_from_object_and_resource, :_fetch_attribute_from_resource_first
end

#root_key(key, key_for_collection = nil) ⇒ void

This method returns an undefined value.

Set root key

Parameters:

  • key (String, Symbol)
  • key_for_collection (String, Symbol) (defaults to: nil)

Raises:

  • (NoMethodError) —

    when key doesn't respond to to_sym method



515
516
517
518
 
# File 'lib/alba/resource.rb', line 515

def root_key(key, key_for_collection = nil)
  @_key = key.to_sym
  @_key_for_collection = key_for_collection&.to_sym
end

#root_key! ⇒ void

This method returns an undefined value.

Set root key to true

Parameters:

  • key (Symbol, String, true, nil)
  • key_for_collection (Symbol, String, true, nil) 


532
533
534
535
 
# File 'lib/alba/resource.rb', line 532

def root_key!
  @_key = true
  @_key_for_collection = true
end

#root_key_for_collection(key) ⇒ void

This method returns an undefined value.

Set root key for collection

Parameters:

  • key (String, Symbol)

Raises:

  • (NoMethodError) —

    when key doesn't respond to to_sym method



525
526
527
528
 
# File 'lib/alba/resource.rb', line 525

def root_key_for_collection(key)
  @_key = true
  @_key_for_collection = key.to_sym
end

#select ⇒ Boolean

Selecting attributes

Parameters:

  • attrs (Symbol)

Returns:

  • (Boolean) 


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

def select: (*Symbol attrs) -> bool

#trait(name) { ... } ⇒ void

This method returns an undefined value.

Traits

Parameters:

  • name (Symbol)

Yields:

Yield Returns:

  • (void) 


502
503
504
505
506
507
 
# File 'lib/alba/resource.rb', line 502

def trait(name, &block)
  raise ArgumentError, 'No block given in trait method' unless block

  name = name.to_sym
  @_traits[name] = block
end

#transform_keys(type, root: true, cascade: true) ⇒ void

This method returns an undefined value.

Transform and configuration

Parameters:

  • type (Alba::transform_type)
  • root: (Boolean) (defaults to: true)
  • cascade: (Boolean) (defaults to: true) 


560
561
562
563
564
565
566
567
568
569
570
 
# File 'lib/alba/resource.rb', line 560

def transform_keys(type, root: true, cascade: true)
  type = type.to_sym
  unless %i[none snake camel lower_camel dash].include?(type)
    # This should be `ArgumentError` but for backward compatibility it raises `Alba::Error`
    raise ::Alba::Error, "Unknown transform type: #{type}. Supported type are :camel, :lower_camel and :dash."
  end

  @_transform_type = type
  @_transforming_root_key = root
  @_key_transformation_cascade = cascade
end

#transform_keys!(type) ⇒ Object

Transform keys as specified type AFTER the class is defined Note that this is an experimental API and may be removed/changed

See Also:



576
577
578
579
580
581
582
583
584
585
586
587
588
 
# File 'lib/alba/resource.rb', line 576

def transform_keys!(type)
  dup.class_eval do
    transform_keys(type, root: @_transforming_root_key, cascade: @_key_transformation_cascade)

    if @_key_transformation_cascade
      # We need to update key transformation of associations and nested attributes
      @_attributes.each_value do |attr|
        attr.key_transformation = type if attr.is_a?(Association) || attr.is_a?(NestedAttribute)
      end
    end
    self # Return the new class
  end
end

#typed_attribute ⇒ void

This method returns an undefined value.

Type checking

Parameters:

  • name (Symbol, String)
  • type (Symbol, Class)
  • opts (Object) 


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

def typed_attribute: (Symbol | String name, Symbol | Class type, **untyped opts) -> void