Module: Alba::Resource

Extended by:

ClassMethods

Includes:

InstanceMethods

Defined in:

lib/alba/resource.rb,
sig/alba/resource.rbs

Overview

This module represents what should be serialized

Defined Under Namespace

Modules: ClassMethods, InstanceMethods, _ClassContext, _ClassMethods, _InstanceMethods

Constant Summary

INTERNAL_VARIABLES =

Returns:

• (Hash[Symbol, untyped])

{_attributes: {}, _key: nil, _key_for_collection: nil, _meta: nil, _transform_type: :none, _transforming_root_key: false, _key_transformation_cascade: true, _on_error: nil, _on_nil: nil, _layout: nil, _collection_key: nil, _helper: nil, _resource_methods: [], _select_arity: nil, _traits: {}}.freeze

WITHIN_DEFAULT =

Returns:

• (Object)

Object.new.freeze

EMPTY_HASH =

Returns:

• (generic_hash)

{}.freeze

Instance Attribute Summary

• #object ⇒ Object included from InstanceMethods readonly

  Returns the value of attribute object.

• #params ⇒ Object included from InstanceMethods readonly

  Returns the value of attribute params.

Class Method Summary

• ._resource_methods ⇒ Array[Symbol] extended from ClassMethods
• .alias_method ⇒ Symbol extended from ClassMethods
• .association(name, modifier = nil, resource: nil, serializer: nil, source: nil, key: nil, with_traits: nil, params: EMPTY_HASH, **options, &block) ⇒ void (also: #one, #many, #has_one, #has_many) extended from ClassMethods

  Set association.

• .attribute(name = nil, if: nil, **name_with_type, &block) ⇒ void extended from ClassMethods

  Set an attribute with the given block.

• .attributes(*attrs, if: nil, **attrs_with_types) ⇒ void extended from ClassMethods

  Set multiple attributes at once.

• .class_eval ⇒ void extended from ClassMethods
• .collection_key(key) ⇒ void extended from ClassMethods

  Sets key for collection serialization.

• .dup ⇒ Object extended from ClassMethods
• .extend ⇒ self extended from ClassMethods
• .helper(mod = @_helper || Module.new, &block) ⇒ void extended from ClassMethods

  Define helper methods.

• .include ⇒ self extended from ClassMethods
• .included(base) ⇒ void private

  setup method is meta-programmatically defined here for performance.

• .inherited(subclass) ⇒ Object extended from ClassMethods private
• .instance_method ⇒ UnboundMethod extended from ClassMethods
• .layout(file: nil, inline: nil) ⇒ void extended from ClassMethods

  Set layout.

• .meta(key = :meta, &block) ⇒ void extended from ClassMethods

  Set metadata.

• .method_added(method_name) ⇒ Object extended from ClassMethods

  This method_added is used for defining "resource methods".

• .module_eval ⇒ void extended from ClassMethods
• .name ⇒ String^? extended from ClassMethods
• .nested_attribute(name, **options, &block) ⇒ void (also: #nested) extended from ClassMethods

  Set a nested attribute with the given block.

• .new ⇒ Resource::_InstanceMethods extended from ClassMethods
• .on_error(handler = nil, &block) ⇒ void extended from ClassMethods

  Set error handler Defaults to raising errors when no handler is set.

• .on_nil(&block) ⇒ void extended from ClassMethods

  Set nil handler.

• .prefer_object_method! ⇒ void extended from ClassMethods

  DSL for alias, purely for readability.

• .prefer_resource_method! ⇒ void extended from ClassMethods

  DSL for alias, purely for readability.

• .private ⇒ void extended from ClassMethods
• .root_key(key, key_for_collection = nil) ⇒ void extended from ClassMethods

  Set root key.

• .root_key! ⇒ void extended from ClassMethods

  Set root key to true.

• .root_key_for_collection(key) ⇒ void extended from ClassMethods

  Set root key for collection.

• .trait(name, &block) ⇒ void extended from ClassMethods

  Set a trait.

• .transform_keys(type, root: true, cascade: true) ⇒ void extended from ClassMethods

  Transform keys as specified type.

• .transform_keys!(type) ⇒ Object extended from ClassMethods

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

Instance Method Summary

• #__send__ ⇒ Object included from InstanceMethods
• #_fetch_attribute_from_object_first(obj, attribute) ⇒ Object included from InstanceMethods
• #_fetch_attribute_from_resource_first(obj, attribute) ⇒ Object included from InstanceMethods
• #_key ⇒ root_key_type included from InstanceMethods
• #_key_for_collection ⇒ root_key_type included from InstanceMethods
• #_metadata(block, meta) ⇒ generic_hash included from InstanceMethods
• #_setup ⇒ void included from InstanceMethods
• #as_json(_options = EMPTY_HASH, root_key: nil, meta: EMPTY_HASH) ⇒ Hash included from InstanceMethods

  Returns a Hash corresponding InstanceMethods#serialize.

• #attributes_to_hash(obj, hash) ⇒ generic_hash included from InstanceMethods
• #binding ⇒ Binding included from InstanceMethods
• #check_within(association_name) ⇒ within included from InstanceMethods
• #class ⇒ Class included from InstanceMethods

  These methods are available on the eventual resource instance.

• #do_select(key, value, attribute) ⇒ Boolean included from InstanceMethods
• #encode ⇒ String included from InstanceMethods
• #fetch_attribute(obj, key, attribute) ⇒ Object included from InstanceMethods

  rubocop:disable Metrics.

• #fetch_attribute_from_object_and_resource(obj, attribute) ⇒ Object included from InstanceMethods
• #fetch_key ⇒ String included from InstanceMethods
• #handle_error(error, obj, key, attribute, hash) ⇒ void included from InstanceMethods
• #hash_from_traits(obj) ⇒ generic_hash included from InstanceMethods
• #hash_with_metadata(hash, meta) ⇒ generic_hash included from InstanceMethods
• #initialize(object, params: EMPTY_HASH, within: WITHIN_DEFAULT, with_traits: nil) ⇒ InstanceMethods included from InstanceMethods

  A new instance of InstanceMethods.

• #instance_eval ⇒ void included from InstanceMethods
• #instance_exec ⇒ Object included from InstanceMethods
• #nil_handler ⇒ instance_proc^? included from InstanceMethods
• #resource_name(pluralized: false) ⇒ String included from InstanceMethods
• #select(_key, _value, _attribute) ⇒ Boolean included from InstanceMethods

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

• #serializable_hash ⇒ Hash (also: #to_h) included from InstanceMethods

  A Hash for serialization.

• #serializable_hash_for_collection ⇒ Array[generic_hash], Hash[root_key_type, generic_hash] included from InstanceMethods
• #serialize(root_key: nil, meta: EMPTY_HASH) ⇒ String included from InstanceMethods

  Serialize object into JSON string.

• #serialize_with(hash) ⇒ String included from InstanceMethods
• #set_key_and_attribute_body_from(obj, key, attribute, hash) ⇒ void included from InstanceMethods
• #to_json(options = EMPTY_HASH, root_key: nil, meta: EMPTY_HASH) ⇒ Object included from InstanceMethods

  For Rails compatibility The first options is a dummy parameter.

• #transform_key(key) ⇒ Object included from InstanceMethods
• #transforming_root_key? ⇒ Boolean included from InstanceMethods
• #yield_if_within(association_name) {|arg0| ... } ⇒ Object included from InstanceMethods

Methods included from _ClassMethods

#assign_attributes, #assign_attributes_with_types, #association, #attribute, #attributes, #collection_key, #helper, #inherited, #layout, #meta, #method_added, #nested_attribute, #nesting, #on_error, #on_nil, #prefer_object_method!, #prefer_resource_method!, #root_key, #root_key!, #root_key_for_collection, #trait, #transform_keys, #transform_keys!, #validated_error_handler

Methods included from _InstanceMethods

#as_json, #nil?, #object, #params, #serializable_hash, #serialize, #to_json

Instance Attribute Details

#object ⇒ Object (readonly) Originally defined in module InstanceMethods

Returns the value of attribute object.

#params ⇒ Object (readonly) Originally defined in module InstanceMethods

Returns the value of attribute params.

Class Method Details

._resource_methods ⇒ Array[Symbol] Originally defined in module ClassMethods

Returns:

• (Array[Symbol])

.alias_method ⇒ Symbol Originally defined in module ClassMethods

Parameters:

• (Symbol)
• (Symbol)

Returns:

• (Symbol)

.association(name, modifier = nil, resource: nil, serializer: nil, source: nil, key: nil, with_traits: nil, params: EMPTY_HASH, **options, &block) ⇒ void Also known as: one, many, has_one, has_many Originally defined in module ClassMethods

This method returns an undefined value.

Set association

Parameters:

• name (String, Symbol) —

  name of the association, used as key when key param doesn't exist

• modifier (Proc, nil) (defaults to: nil) —

  a Proc to modify the association

• resource (Class<Alba::Resource>, String, Proc, nil) (defaults to: nil) —

  representing resource for this association

• serializer (Class<Alba::Resource>, String, Proc, nil) (defaults to: nil) —

  alias for resource

• source (Proc, nil) (defaults to: nil) —

  a Proc to customize the association source

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

  used as key when given

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

  specified traits

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

  params override for the association

• options (Hash<Symbol, Proc>)
• block (Block)

Options Hash (**options):

• if (Proc, Symbol, nil) —

  a condition to decide if this association should be serialized When it's Proc, it's called to check condition When it's Symbol, it's treated as a method name on the Resource and the method is called

See Also:

• Association#initialize

.attribute(name = nil, if: nil, **name_with_type, &block) ⇒ void Originally defined in module ClassMethods

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

Raises:

• (ArgumentError) —

  if block is absent

.attributes(*attrs, if: nil, **attrs_with_types) ⇒ void Originally defined in module ClassMethods

This method returns an undefined value.

Set multiple attributes at once

Parameters:

• attrs (Array<String, Symbol>)
• if (Proc) (defaults to: nil) —

  condition to decide if it should serialize these attributes

• attrs_with_types (Hash{Symbol, String => Array<Symbol, Proc>, Symbol}) —

  attributes with name in its key and type and optional type converter in its value

.class_eval ⇒ void Originally defined in module ClassMethods

This method returns an undefined value.

.collection_key(key) ⇒ void Originally defined in module ClassMethods

This method returns an undefined value.

Sets key for collection serialization

Parameters:

• key (String, Symbol)

.dup ⇒ Object Originally defined in module ClassMethods

Returns:

• (Object)

.extend ⇒ self Originally defined in module ClassMethods

Parameters:

• (Module)

Returns:

• (self)

.helper(mod = @_helper || Module.new, &block) ⇒ void Originally defined in module ClassMethods

This method returns an undefined value.

Define helper methods

Parameters:

• mod (Module) (defaults to: @_helper || Module.new) —

  a module to extend

.include ⇒ self Originally defined in module ClassMethods

Parameters:

• (Module)

Returns:

• (self)

.included(base) ⇒ void

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.

This method returns an undefined value.

setup method is meta-programmatically defined here for performance.

Parameters:

• (Class)

# File 'lib/alba/resource.rb', line 28

def self.included(base) # rubocop:disable Metrics/MethodLength
  super
  base.class_eval do
    # Initialize
    setup_method_body = +'private def _setup;'
    INTERNAL_VARIABLES.each do |name, initial|
      instance_variable_set(:"@#{name}", initial.dup) unless instance_variable_defined?(:"@#{name}")
      setup_method_body << "@#{name} = self.class.#{name};"
    end
    setup_method_body << 'end'
    class_eval(setup_method_body, __FILE__, __LINE__ + 1)
    define_method(:encode, Alba.encoder)
  end
  base.include InstanceMethods
  base.extend ClassMethods
end

.inherited(subclass) ⇒ Object Originally defined in module ClassMethods

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.

.instance_method ⇒ UnboundMethod Originally defined in module ClassMethods

Parameters:

• (Symbol)

Returns:

• (UnboundMethod)

.layout(file: nil, inline: nil) ⇒ void Originally defined in module ClassMethods

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

.meta(key = :meta, &block) ⇒ void Originally defined in module ClassMethods

This method returns an undefined value.

Set metadata

.method_added(method_name) ⇒ Object Originally defined in module ClassMethods

This method_added is used for defining "resource methods"

.module_eval ⇒ void Originally defined in module ClassMethods

This method returns an undefined value.

.name ⇒ String^? Originally defined in module ClassMethods

Returns:

• (String, nil)

.nested_attribute(name, **options, &block) ⇒ void Also known as: nested Originally defined in module ClassMethods

This method returns an undefined value.

Set a nested attribute with the given block

Parameters:

• name (String, Symbol) —

  key name

• options (Hash<Symbol, Proc>)
• block (Block) —

  the block called during serialization

Options Hash (**options):

• if (Proc) —

  a condition to decide if this attribute should be serialized

Raises:

• (ArgumentError) —

  if block is absent

.new ⇒ Resource::_InstanceMethods Originally defined in module ClassMethods

Parameters:

• (Object)
• (Object)

Returns:

• (Resource::_InstanceMethods)

.on_error(handler = nil, &block) ⇒ void Originally defined in module ClassMethods

This method returns an undefined value.

Set error handler Defaults to raising errors when no handler is set.

Parameters:

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

  :raise, :ignore or :nullify

• block (Block)

Raises:

• (ArgumentError)

.on_nil(&block) ⇒ void Originally defined in module ClassMethods

This method returns an undefined value.

Set nil handler

Parameters:

• block (Block)

.prefer_object_method! ⇒ void Originally defined in module ClassMethods

This method returns an undefined value.

DSL for alias, purely for readability

.prefer_resource_method! ⇒ void Originally defined in module ClassMethods

This method returns an undefined value.

DSL for alias, purely for readability

.private ⇒ void Originally defined in module ClassMethods

This method returns an undefined value.

Parameters:

• (Symbol)

.root_key(key, key_for_collection = nil) ⇒ void Originally defined in module ClassMethods

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

.root_key! ⇒ void Originally defined in module ClassMethods

This method returns an undefined value.

Set root key to true

.root_key_for_collection(key) ⇒ void Originally defined in module ClassMethods

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

.trait(name, &block) ⇒ void Originally defined in module ClassMethods

This method returns an undefined value.

Set a trait

Parameters:

• name (String, Symbol) —

  name of the trait

• block (Block) —

  the "content" of the trait

Raises:

• (ArgumentError) —

  if block is absent

.transform_keys(type, root: true, cascade: true) ⇒ void Originally defined in module ClassMethods

This method returns an undefined value.

Transform keys as specified type

Parameters:

• type (String, Symbol) —

  one of snake, :camel, :lower_camel, :dash and none

• root (Boolean) (defaults to: true) —

  decides if root key also should be transformed

• cascade (Boolean) (defaults to: true) —

  decides if key transformation cascades into inline association Default is true but can be set false for old (v1) behavior

Raises:

• (Alba::Error) —

  when type is not supported

.transform_keys!(type) ⇒ Object Originally defined in module ClassMethods

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

See Also:

• #transform_keys

Instance Method Details

#__send__ ⇒ Object Originally defined in module InstanceMethods

Parameters:

• (Symbol)
• (Object)

Returns:

• (Object)

#_fetch_attribute_from_object_first(obj, attribute) ⇒ Object Originally defined in module InstanceMethods

Parameters:

• (Object)
• (Symbol)

Returns:

• (Object)

#_fetch_attribute_from_resource_first(obj, attribute) ⇒ Object Originally defined in module InstanceMethods

Parameters:

• (Object)
• (Symbol)

Returns:

• (Object)

#_key ⇒ root_key_type Originally defined in module InstanceMethods

Returns:

• (root_key_type)

#_key_for_collection ⇒ root_key_type Originally defined in module InstanceMethods

Returns:

• (root_key_type)

#_metadata(block, meta) ⇒ generic_hash Originally defined in module InstanceMethods

Parameters:

• (metadata_proc, nil)
• (generic_hash)

Returns:

• (generic_hash)

#_setup ⇒ void Originally defined in module InstanceMethods

This method returns an undefined value.

#as_json(_options = EMPTY_HASH, root_key: nil, meta: EMPTY_HASH) ⇒ Hash Originally defined in module InstanceMethods

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

Returns:

• (Hash)

#attributes_to_hash(obj, hash) ⇒ generic_hash Originally defined in module InstanceMethods

Parameters:

• (Object)
• (generic_hash)

Returns:

• (generic_hash)

#binding ⇒ Binding Originally defined in module InstanceMethods

Returns:

• (Binding)

#check_within(association_name) ⇒ within Originally defined in module InstanceMethods

Parameters:

• (Symbol)

Returns:

• (within)

#class ⇒ Class Originally defined in module InstanceMethods

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

Returns:

• (Class)

#do_select(key, value, attribute) ⇒ Boolean Originally defined in module InstanceMethods

Parameters:

• (key_type)
• (Object)
• (attribute)

Returns:

• (Boolean)

#encode ⇒ String Originally defined in module InstanceMethods

Parameters:

• (Object)

Returns:

• (String)

#fetch_attribute(obj, key, attribute) ⇒ Object Originally defined in module InstanceMethods

rubocop:disable Metrics

Parameters:

• (Object)
• (key_type)
• (attribute)

Returns:

• (Object)

#fetch_attribute_from_object_and_resource(obj, attribute) ⇒ Object Originally defined in module InstanceMethods

Parameters:

• (Object)
• (Symbol)

Returns:

• (Object)

#fetch_key ⇒ String Originally defined in module InstanceMethods

Returns:

• (String)

#handle_error(error, obj, key, attribute, hash) ⇒ void Originally defined in module InstanceMethods

This method returns an undefined value.

Parameters:

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

#hash_from_traits(obj) ⇒ generic_hash Originally defined in module InstanceMethods

Parameters:

• (Object)

Returns:

• (generic_hash)

#hash_with_metadata(hash, meta) ⇒ generic_hash Originally defined in module InstanceMethods

Parameters:

• (generic_hash)
• (generic_hash)

Returns:

• (generic_hash)

#initialize(object, params: EMPTY_HASH, within: WITHIN_DEFAULT, with_traits: nil) ⇒ InstanceMethods Originally defined in module 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

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

Returns:

• (InstanceMethods) —

  a new instance of InstanceMethods

#instance_eval ⇒ void Originally defined in module InstanceMethods

This method returns an undefined value.

#instance_exec ⇒ void #instance_exec ⇒ void Originally defined in module InstanceMethods

Overloads:

• #instance_exec ⇒ void

  This method returns an undefined value.
• #instance_exec ⇒ void

  This method returns an undefined value.

#nil_handler ⇒ instance_proc^? Originally defined in module InstanceMethods

Returns:

• (instance_proc, nil)

#resource_name(pluralized: false) ⇒ String Originally defined in module InstanceMethods

Parameters:

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

Returns:

• (String)

Raises:

• (Alba::Error)

#select(_key, _value, _attribute) ⇒ Boolean Originally defined in module InstanceMethods

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

Parameters:

• (key_type)
• (Object)
• (attribute)

Returns:

• (Boolean)

#serializable_hash ⇒ Hash Also known as: to_h Originally defined in module InstanceMethods

A Hash for serialization

Returns:

• (Hash)

#serializable_hash_for_collection ⇒ Array[generic_hash], Hash[root_key_type, generic_hash] Originally defined in module InstanceMethods

Returns:

• (Array[generic_hash], Hash[root_key_type, generic_hash])

#serialize(root_key: nil, meta: EMPTY_HASH) ⇒ String Originally defined in module InstanceMethods

Serialize object into JSON string

Parameters:

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

  metadata for this serialization

Returns:

• (String) —

  serialized JSON string

#serialize_with(hash) ⇒ String Originally defined in module InstanceMethods

Parameters:

• (Object)

Returns:

• (String)

#set_key_and_attribute_body_from(obj, key, attribute, hash) ⇒ void Originally defined in module InstanceMethods

This method returns an undefined value.

Parameters:

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

#to_json(options = EMPTY_HASH, root_key: nil, meta: EMPTY_HASH) ⇒ Object Originally defined in module InstanceMethods

For Rails compatibility The first options is a dummy parameter

See Also:

• #serialize
• https://github.com/rails/rails/blob/7-0-stable/actionpack/lib/action_controller/metal/renderers.rb#L156

#transform_key(key) ⇒ Object Originally defined in module InstanceMethods

Parameters:

• (Symbol, String, nil)

Returns:

• (Object)

#transforming_root_key? ⇒ Boolean Originally defined in module InstanceMethods

Returns:

• (Boolean)

#yield_if_within(association_name) {|arg0| ... } ⇒ Object Originally defined in module InstanceMethods

Parameters:

• (Symbol)

Yields:

Yield Parameters:

• arg0 (within)

Yield Returns:

• (Object)

Returns:

• (Object)