Module: Serega::ClassMethods

Included in:
Serega
Defined in:
lib/serega.rb

Overview

Serializers class methods

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#config ⇒ SeregaConfig (readonly)

Returns current config

Returns:



99
100
101
 
# File 'lib/serega.rb', line 99

def config
  @config
end

Instance Method Details

#attribute(name, **opts, &block) ⇒ Serega::SeregaAttribute

Adds attribute

Patched in:

  • plugin :presenter (additionally adds method in Presenter class)

Parameters:

  • name (Symbol) —

    Attribute name. Attribute value will be found by executing object.<name>

  • opts (Hash) —

    Options to serialize attribute

  • block (Proc) —

    Custom block to find attribute value. Accepts object and context.

Returns:



175
176
177
178
 
# File 'lib/serega.rb', line 175

def attribute(name, **opts, &block)
  attribute = self::SeregaAttribute.new(name: name, opts: opts, block: block)
  attributes[attribute.name] = attribute
end

#attributes ⇒ Hash

Lists attributes

Returns:

  • (Hash) —

    attributes list



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

def attributes
  @attributes ||= {}
end

#batch(name, value = nil, &block) ⇒ #call

Defines a batch loader

Examples:

batch :tags, PostTagsLoader

with block

batch_loader(:tags) do |posts|
  Tags.where(post: posts).group(:post_id).pluck(:post_id, Arel.sql('ARRAY_AGG(tags.tag ORDER BY tag)')).to_h
end

attribute :tags, batch: :tags, value: { |post, batch:| batch[:tags][post.id] }

with context

batch_loader(:tags) do |posts, ctx:|
  next {} if ctx[:bot]

  Tags.where(post: posts).group(:post_id).pluck(:post_id, Arel.sql('ARRAY_AGG(tags.tag ORDER BY tag)')).to_h
end

attribute :tags, batch: :tags, value: { |post, batch:| batch[:tags][post.id] }

Parameters:

  • name (Symbol) —

    A batch loader name

  • value (#call) (defaults to: nil) —

    Batch loader

  • block (Proc) —

    Batch loader

Returns:

  • (#call) —

    Batch loader

Raises:



208
209
210
211
212
213
 
# File 'lib/serega.rb', line 208

def batch(name, value = nil, &block)
  raise SeregaError, "Batch loader must be defined with a callable value or block" if (value && block) || (!value && !block)

  batch_loader = self::SeregaEngineLoader.new(name: name, block: value || block)
  batch_loaders[batch_loader.name] = batch_loader
end

#batch_loaders ⇒ Hash

Lists defined batch loaders

Returns:

  • (Hash) —

    batch loaders list



159
160
161
 
# File 'lib/serega.rb', line 159

def batch_loaders
  @batch_loaders ||= {}
end

#call(object, opts = nil) ⇒ Hash Also known as: to_h

Serializes provided object to Hash

Parameters:

  • object (Object) —

    Serialized object

  • opts (Hash, nil) (defaults to: nil) —

    Serializer modifiers and other instantiating options

Options Hash (opts):

  • :only (Array, Hash, String, Symbol) —

    The only attributes to serialize

  • :except (Array, Hash, String, Symbol) —

    Attributes to hide

  • :with (Array, Hash, String, Symbol) —

    Attributes (usually hidden) to serialize additionally

  • :validate (Boolean) —

    Validates provided modifiers (Default is true)

  • :context (Hash) —

    Serialization context

  • :many (Boolean) —

    Set true if provided multiple objects (Default object.is_a?(Enumerable))

Returns:

  • (Hash) —

    Serialization result



261
262
263
264
265
266
 
# File 'lib/serega.rb', line 261

def call(object, opts = nil)
  opts = opts&.transform_keys(&:to_sym)
  modifiers_opts = init_modifier_opts(opts)
  serialize_opts = init_serialize_opts(opts)
  new(modifiers_opts).to_h(object, serialize_opts)
end

#plugin(name, **opts) ⇒ class<Module>

Enables plugin for current serializer

Parameters:

  • name (Symbol, Class<Module>) —

    Plugin name or plugin module itself

  • opts (Hash) —

    ] Plugin options

Returns:

  • (class<Module>) —

    Loaded plugin module

Raises:



108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/serega.rb', line 108

def plugin(name, **opts)
  raise SeregaError, "This plugin is already loaded" if plugin_used?(name)

  plugin = SeregaPlugins.find_plugin(name)

  # We split loading of plugin to three parts - before_load, load, after_load:
  #
  # - **before_load_plugin** usually used to check requirements and to load additional plugins
  # - **load_plugin** usually used to include plugin modules
  # - **after_load_plugin** usually used to add config options
  plugin.before_load_plugin(self, **opts) if plugin.respond_to?(:before_load_plugin)
  plugin.load_plugin(self, **opts) if plugin.respond_to?(:load_plugin)
  plugin.after_load_plugin(self, **opts) if plugin.respond_to?(:after_load_plugin)

  # Store attached plugins, so we can check it is loaded later
  config.plugins << (plugin.respond_to?(:plugin_name) ? plugin.plugin_name : plugin)

  plugin
end

#plugin_used?(name) ⇒ Boolean

Checks plugin is used

Parameters:

  • name (Symbol, Class<Module>) —

    Plugin name or plugin module itself

Returns:

  • (Boolean) —

    Is plugin used



135
136
137
138
139
140
141
142
143
 
# File 'lib/serega.rb', line 135

def plugin_used?(name)
  plugin_name =
    case name
    when Module then name.respond_to?(:plugin_name) ? name.plugin_name : name
    else name
    end

  config.plugins.include?(plugin_name)
end

#preload_with(value = nil, &block) ⇒ #call?

Registers (or returns) the handler used to preload an attribute's associations onto the records gathered during serialization.

The handler is called once per preloaded attribute with the gathered objects and that attribute's preloads. ORM plugins register a handler that performs the actual eager loading.

Examples:

with a block

preload_with { |objects, preloads| MyORM.eager_load(objects, preloads) }

with a callable value

preload_with MyPreloader

Parameters:

  • value (#call, nil) (defaults to: nil) —

    Preload handler accepting two positional arguments

  • block (Proc) —

    Preload handler accepting two positional arguments

Returns:

  • (#call, nil) —

    The registered preload handler

Raises:



234
235
236
237
238
239
240
241
242
243
244
245
 
# File 'lib/serega.rb', line 234

def preload_with(value = nil, &block)
  return @preload_with if value.nil? && block.nil?
  raise SeregaError, "preload_with accepts a single callable or a block, not both" if value && block

  handler = value || block
  raise SeregaError, "preload_with value must be a Proc or respond to #call" if !handler.is_a?(Proc) && !handler.respond_to?(:call)

  signature = SeregaUtils::MethodSignature.call(handler, pos_limit: 2)
  raise SeregaError, "preload_with handler must accept two positional arguments: (objects, preloads)" unless signature == "2"

  @preload_with = handler
end

#to_data(object, opts = nil) ⇒ Data, ...

Serializes provided object to a tree of Ruby Data objects

Parameters:

  • object (Object) —

    Serialized object

  • opts (Hash, nil) (defaults to: nil) —

    Serializer modifiers and other instantiating options

Options Hash (opts):

  • :only (Array, Hash, String, Symbol) —

    The only attributes to serialize

  • :except (Array, Hash, String, Symbol) —

    Attributes to hide

  • :with (Array, Hash, String, Symbol) —

    Attributes (usually hidden) to serialize additionally

  • :validate (Boolean) —

    Validates provided modifiers (Default is true)

  • :context (Hash) —

    Serialization context

  • :many (Boolean) —

    Set true if provided multiple objects (Default object.is_a?(Enumerable))

Returns:

  • (Data, Array<Data>, nil) —

    Serialization result as Data object(s)



282
283
284
285
286
287
 
# File 'lib/serega.rb', line 282

def to_data(object, opts = nil)
  opts = opts&.transform_keys(&:to_sym)
  modifiers_opts = init_modifier_opts(opts)
  serialize_opts = init_serialize_opts(opts)
  new(modifiers_opts).to_data(object, serialize_opts)
end