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 ⇒ Object extended from ClassMethods
• .helper(mod = @_helper || Module.new, &block) ⇒ void extended from ClassMethods

  Define helper methods.

• .include ⇒ Object extended from ClassMethods
• .included(base) ⇒ Object 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 ⇒ Object extended from ClassMethods
• .nested_attribute(name, **options, &block) ⇒ void (also: #nested) extended from ClassMethods

  Set a nested attribute with the given block.

• .new ⇒ Object 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 ⇒ Object 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) ⇒ Object 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) ⇒ Object included from InstanceMethods
• #hash_from_traits(obj) ⇒ Object included from InstanceMethods
• #hash_with_metadata(hash, meta) ⇒ Object 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 ⇒ void included from InstanceMethods
• #nil_handler ⇒ Object 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 ⇒ Object 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) ⇒ Object 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, #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 ⇒ Object Originally defined in module ClassMethods

Parameters:

• (Module)

Returns:

• (Object)

.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 ⇒ Object Originally defined in module ClassMethods

Parameters:

• (Module)

Returns:

• (Object)

.included(base) ⇒ 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.

setup method is meta-programmatically defined here for performance.

Parameters:

• (Class)

Returns:

• (Object)

# 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 ⇒ Object Originally defined in module ClassMethods

Returns:

• (Object)

.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 ⇒ Object Originally defined in module ClassMethods

Parameters:

• (Object)
• (Object)

Returns:

• (Object)

.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 ⇒ Object Originally defined in module ClassMethods

Parameters:

• (Symbol)

Returns:

• (Object)

.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:

• (Object)
• (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) ⇒ Object Originally defined in module InstanceMethods

Parameters:

• (Symbol)

Returns:

• (Object)

#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:

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

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)
• (Object)
• (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) ⇒ Object Originally defined in module InstanceMethods

Parameters:

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

Returns:

• (Object)

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

Parameters:

• (Object)

Returns:

• (Object)

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

Parameters:

• (Object)
• (generic_hash)

Returns:

• (Object)

#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: (Object) (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 Originally defined in module InstanceMethods

This method returns an undefined value.

#nil_handler ⇒ Object Originally defined in module InstanceMethods

Returns:

• (Object)

#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:

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

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 ⇒ Object Originally defined in module InstanceMethods

Returns:

• (Object)

#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) ⇒ Object Originally defined in module InstanceMethods

Parameters:

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

Returns:

• (Object)

#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:

• (Object)

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 (Object)

Yield Returns:

• (Object)

Returns:

• (Object)